ICal.Recurrence
(iCal v2.0.0)
View Source
Support for recurring events, todos, and journals.
Summary
Functions
Applies a generated date or datetime recurrence to an ICal component such as
an event, todo, or journal entry.
Takes a string starting with "RRULE:" and returns a recurrence struct.
Normalizes a recurrence, to ensure it is within the boundaries defined by RFC5545.
Creates a stream of recurrences for a recurrence rule or a component with a recurrence rule.
Returns true if the recurrence terminates eventually, false if it has no defined end and instead continues indefinitely.
Types
@type frequency() ::
:secondly | :minutely | :hourly | :daily | :weekly | :monthly | :yearly
@type recurrable_component() :: %{ :rrule => t() | nil, :dtstart => Date.t() | DateTime.t() | nil, optional(:exdates) => [Date.t() | DateTime.t()], optional(:dtend) => Date.t() | DateTime.t() | nil, optional(:rdates) => [Date.t() | DateTime.t() | ICal.period()] }
@type recurrence_date() :: Date.t() | DateTime.t()
@type stream_option() :: {:start_date, recurrence_date()} | {:end_date, recurrence_date()} | {:include, [recurrence_date()]} | {:exclude, [recurrence_date()]}
@type t() :: %ICal.Recurrence{ by_day: [{offset :: integer(), byday :: weekday()}] | nil, by_hour: [non_neg_integer()] | nil, by_minute: [non_neg_integer()] | nil, by_month: [non_neg_integer()] | nil, by_month_day: [non_neg_integer()] | nil, by_second: [non_neg_integer()] | nil, by_set_position: [non_neg_integer()] | nil, by_week_number: [non_neg_integer()] | nil, by_year_day: [non_neg_integer()] | nil, count: non_neg_integer(), frequency: frequency(), interval: non_neg_integer(), until: DateTime.t() | nil, week_start_day: weekday() | :default }
@type weekday() ::
:monday | :tuesday | :wednesday | :thursday | :friday | :saturday | :sunday
Functions
Applies a generated date or datetime recurrence to an ICal component such as
an event, todo, or journal entry.
Takes a string starting with "RRULE:" and returns a recurrence struct.
Normalizes a recurrence, to ensure it is within the boundaries defined by RFC5545.
Call this before using the recurrence if creating recurrences manually. Recurrences parsed from ics data are automatically normalized.
@spec stream(t() | recurrable_component(), options :: [stream_option()]) :: Enumerable.t()
Creates a stream of recurrences for a recurrence rule or a component with a recurrence rule.
The stream takes into consideration any recurrence rules (RRULE), recurrence dates (RDATE), and excluded dates (EXDATE). It starts at the start date (DTSTART) defined in the component.
As recurrences may not have an end, continuing on forever, the resulting stream can be also
be infinite. For this reason, unless absolutely sure the stream terminates do not request the
entire contents of the stream by calling Enum.to_list() on it, for isntance. Instead, always
consume the stream in chunks until it is exausted.
Parameters
component: AnICal.Event,ICal.Todo,ICal.Journal, or a bareICal.Recurrencestructoptions: An optional list ofstream_option/0values. Can be used to set explicit start and end dates as well as recurrences to include in or exclude from the stream.
Examples
iex> dt = ~D[2016-08-13]
iex> dt_end = ~D[2016-08-23]
iex> recurrence = %ICal.Recurrence{frequency: :daily}
iex> event = %ICal.Event{rrule: recurrence, dtstart: dt, dtend: dt_end}
iex> ICal.Recurrence.stream(event) |> Enum.take(5)
[~D[2016-08-13], ~D[2016-08-14], ~D[2016-08-15], ~D[2016-08-16], ~D[2016-08-17]]
iex> rule = ICal.Recurrence.from_ics("RRULE:FREQ=DAILY")
iex> ICal.Recurrence.stream(rule, start_date: dt, end_date: dt_end) |> Enum.take(5)
[~D[2016-08-13], ~D[2016-08-14], ~D[2016-08-15], ~D[2016-08-16], ~D[2016-08-17]]Returns true if the recurrence terminates eventually, false if it has no defined end and instead continues indefinitely.