@spec add_exception_time(t(), Cocktail.time()) :: t()

Adds an exception time to the schedule.

This exception time will cancel out any occurrence generated from the schedule's recurrence rules or recurrence times.

@spec add_recurrence_rule(t(), Cocktail.frequency(), Cocktail.rule_options()) :: t()

Adds a recurrence rule of the given frequency to a schedule.

The frequency can be one of :monthly, :weekly, :daily, :hourly, :minutely or :secondly

options

Options

• :interval - How often to repeat, given the frequency. For example a :daily rule with interval 2 would be "every other day".
• :count - The number of times this rule can produce an occurrence. (not yet support)
• :until - The end date/time after which the rule will no longer produce occurrences.
• :days_of_month - Restrict this rule to specific days of the month. (e.g. [-1, 10, 31])
• :days - Restrict this rule to specific days. (e.g. [:monday, :wednesday, :friday])
• :hours - Restrict this rule to certain hours of the day. (e.g. [10, 12, 14])
• :minutes - Restrict this rule to certain minutes of the hour. (e.g. [0, 15, 30, 45])
• :seconds - Restrict this rule to certain seconds of the minute. (e.g. [0, 30])

examples

Examples

iex> start_time = ~N[2017-01-01 06:00:00]
...> start_time |> new() |> add_recurrence_rule(:daily, interval: 2, hours: [10, 14])
#Cocktail.Schedule<Every 2 days on the 10th and 14th hours of the day>

@spec add_recurrence_time(t(), Cocktail.time()) :: t()

Adds a one-off recurrence time to the schedule.

This recurrence time can be any time after (or including) the schedule's start time. When generating occurrences from this schedule, the given time will be included in the set of occurrences alongside any recurrence rules.

@spec end_all_recurrence_rules(t(), Cocktail.time()) :: t()

Add an end time to all recurrence rules in the schedule.

This has the same effect as if you'd passed the :until option when adding all recurrence rules to the schedule.

@spec from_i_calendar(String.t()) :: {:ok, t()} | {:error, term()}

Parses a string in iCalendar format into a Cocktail.Schedule.t/0.

see Cocktail.Parser.ICalendar.parse/1 for details.

@spec new(Cocktail.time(), Cocktail.schedule_options()) :: t()

Creates a new schedule using the given start time and options.

This schedule will be empty and needs recurrence rules added to it before it is useful. Use add_recurrence_rule/3 to add rules to a schedule.

options

Options

• :duration - The duration of each event in the schedule (in seconds).

examples

Examples

iex> new(~N[2017-01-01 06:00:00], duration: 3_600)
#Cocktail.Schedule<>

@spec occurrences(t(), Cocktail.time() | nil) :: Enumerable.t()

Creates a stream of occurrences from the given schedule.

An optional start_time can be supplied to not start at the schedule's start time.

The occurrences that are produced by the stream can be one of several types:

• If the schedule's start time is a DateTime.t/0, then it will produce DateTime.t/0s
• If the schedule's start time is a NaiveDateTime.t/0, the it will produce NaiveDateTime.t/0s
• If a duration is supplied when creating the schedule, the stream will produce Cocktail.Span.t/0s with :from and :until fields matching the type of the schedule's start time

examples

Examples

# using a NaiveDateTime
iex> start_time = ~N[2017-01-01 06:00:00]
...> schedule = start_time |> new() |> add_recurrence_rule(:daily, interval: 2, hours: [10, 14])
...> schedule |> occurrences() |> Enum.take(3)
[~N[2017-01-01 10:00:00],
 ~N[2017-01-01 14:00:00],
 ~N[2017-01-03 10:00:00]]

# using an alternate start time
iex> start_time = ~N[2017-01-01 06:00:00]
...> schedule = start_time |> new() |> add_recurrence_rule(:daily, interval: 2, hours: [10, 14])
...> schedule |> occurrences(~N[2017-10-01 06:00:00]) |> Enum.take(3)
[~N[2017-10-02 10:00:00],
 ~N[2017-10-02 14:00:00],
 ~N[2017-10-04 10:00:00]]

# using a DateTime with a time zone
iex> start_time = Timex.to_datetime(~N[2017-01-02 10:00:00], "America/Los_Angeles")
...> schedule = start_time |> new() |> add_recurrence_rule(:daily)
...> schedule |> occurrences() |> Enum.take(3) |> Enum.map(&Timex.format!(&1, "{ISO:Extended}"))
["2017-01-02T10:00:00-08:00",
 "2017-01-03T10:00:00-08:00",
 "2017-01-04T10:00:00-08:00"]

# using a NaiveDateTime with a duration
iex> start_time = ~N[2017-02-01 12:00:00]
...> schedule = start_time |> new(duration: 3_600) |> add_recurrence_rule(:weekly)
...> schedule |> occurrences() |> Enum.take(3)
[%Cocktail.Span{from: ~N[2017-02-01 12:00:00], until: ~N[2017-02-01 13:00:00]},
 %Cocktail.Span{from: ~N[2017-02-08 12:00:00], until: ~N[2017-02-08 13:00:00]},
 %Cocktail.Span{from: ~N[2017-02-15 12:00:00], until: ~N[2017-02-15 13:00:00]}]

@spec to_i_calendar(t()) :: String.t()

Builds an iCalendar format string representation of a Cocktail.Schedule.t/0.

see Cocktail.Builder.ICalendar.build/1 for details.

@spec to_i_calendar_rrule(t()) :: String.t()

Builds an iCalendar RRULE format string representation of a Cocktail.Schedule.t/0.

see Cocktail.Builder.ICalendar.build_rule/1 for details.

@spec to_string(t()) :: String.t()

Builds a human readable string representation of a Cocktail.Schedule.t/0.

see Cocktail.Builder.String.build/1 for details.