Cocktail.Schedule (Cocktail v0.9.0) View Source

Struct used to represent a schedule of recurring events.

Use the new/2 function to create a new schedule, and the add_recurrence_rule/2 function to add rules to describe how to repeat.

Currently, Cocktail supports the following types of repeat rules:

  • Weekly - Every week, relative to the schedule's start time
  • Daily - Every day at the schedule's start time
  • Hourly - Every hour, starting at the schedule's start time
  • Minutely - Every minute, starting at the schedule's start time
  • Secondly - Every second, starting at the schedule's start time

Once a schedule has been created, you can use occurrences/2 to generate a stream of occurrences, which are either Cocktail.time/0s or Cocktail.Span.t/0s if a duration option was given to the schedule.

Various options can be given to modify the way the repeat rule and schedule behave. See add_recurrence_rule/3 for details on them.

Link to this section Summary

Types

t()

Struct used to represent a schedule of recurring events.

Functions

Adds an exception time to the schedule.

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

Adds a one-off recurrence time to the schedule.

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

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

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

Creates a stream of occurrences from the given schedule.

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

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

Link to this section Types

Specs

t() :: %Cocktail.Schedule{
  duration: pos_integer() | nil,
  exception_times: [Cocktail.time()],
  recurrence_rules: [Cocktail.Rule.t()],
  recurrence_times: [Cocktail.time()],
  start_time: Cocktail.time()
}

Struct used to represent a schedule of recurring events.

This type should be considered opaque, so its fields shouldn't be modified directly. Instead, use the functions provided in this module to create and manipulate schedules.

Fields:

  • :start_time - The schedule's start time
  • :duration - The duration of each occurrence (in seconds)

Link to this section Functions

Link to this function

add_exception_time(schedule, time)

View Source

Specs

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.

Link to this function

add_recurrence_rule(schedule, frequency, options \\ [])

View Source

Specs

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

  • :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

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>
Link to this function

add_recurrence_time(schedule, time)

View Source

Specs

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.

Link to this function

end_all_recurrence_rules(schedule, end_time)

View Source

Specs

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.

Link to this function

from_i_calendar(i_calendar_string)

View Source

Specs

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.

Link to this function

new(start_time, options \\ [])

View Source

Specs

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

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

Examples

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

occurrences(schedule, start_time \\ nil)

View Source

Specs

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:

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]}]

Specs

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.

Specs

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.