Class: IRecur

IRecur(oOptionsopt)

new IRecur(oOptionsopt)

The IRecur object (part of ExICalendar/JS) defines the recurrence rule (RRULE), according with Internet Calendaring and Scheduling Core Object Specification, RFC 5545.
Parameters:
Name Type Attributes Description
oOptions IRecurOptions <optional>
 Specifies the options to create the parsing object, as an object of exontrol.ICalendar.IRecurOptions type
Requires:
  • module:exontrol.commmon.min.js

Requires

  • module:exontrol.commmon.min.js

Members

(static) count :number

The count field defines the number of recurrences to get if no UNTIL or COUNT part rule.
Type:
  • number

(static) type :string

The type field defines the full-name of the object (the constructor.name does not give the same name for minimized forms)
Type:
  • string
Since:
  • 1.8

(static) version :string

The version field defines the version of the library
Type:
  • string

Methods

(static) Parse(expression, oOptionsopt) → {IRecur}

The IRecur.Parse() method parses the giving recurrence-rules and returns an object of IRecur type
Parameters:
Name Type Attributes Description
expression string | object Indicates a string that represents the recurrence-expression to parse, or an object of {dtstart, freq, until, count, interval, bysecond, byminute, byhour, byday, bymonthday, byyearday, byweekno, bymonth, bysetpos, wkst} type. The expression may include any of the following fields:
  • FREQ, {string} The FREQ rule part identifies the type of recurrence rule. This rule part MUST be specified in the recurrence rule. Valid values include SECONDLY, to specify repeating events based on an interval of a second or more; MINUTELY, to specify repeating events based on an interval of a minute or more; HOURLY, to specify repeating events based on an interval of an hour or more; DAILY, to specify repeating events based on an interval of a day or more; WEEKLY, to specify repeating events based on an interval of a week or more; MONTHLY, to specify repeating events based on an interval of a month or more; and YEARLY, to specify repeating events based on an interval of a year or more. The valid values are "SECONDLY", "MINUTELY", "HOURLY", "DAILY", "WEEKLY", "MONTHLY" and "YEARLY".
  • DTSTART {Date}, The DTSTART rule specifies the date the recurrence starts from, in YYYYMMDD[THHNNSS[Z]] format. If missing the current date and time is used.
  • INTERVAL {number}, The INTERVAL rule part contains a positive integer representing at which intervals the recurrence rule repeats. The default value is "1", meaning every second for a SECONDLY rule, every minute for a MINUTELY rule, every hour for an HOURLY rule, every day for a DAILY rule, every week for a WEEKLY rule, every month for a MONTHLY rule, and every year for a YEARLY rule. For example, within a DAILY rule, a value of "8" means every eight days.
  • COUNT {number}, The COUNT rule part defines the number of occurrences at which to range-bound the recurrence. The "DTSTART" property value always counts as the first occurrence.
  • WKST {string}, The WKST rule part specifies the day on which the workweek starts. Valid values are MO, TU, WE, TH, FR, SA, and SU. This is significant when a WEEKLY "RRULE" has an interval greater than 1, and a BYDAY rule part is specified. This is also significant when in a YEARLY "RRULE" when a BYWEEKNO rule part is specified. The default value is MO.
  • UNTIL {Date}, The UNTIL rule part defines a DATE or DATE-TIME value that bounds the recurrence rule in an inclusive manner. If the value specified by UNTIL is synchronized with the specified recurrence, this DATE or DATE-TIME becomes the last instance of the recurrence. The value of the UNTIL rule part MUST have the same value type as the "DTSTART" property.
  • BYWEEKNO {string}, The BYWEEKNO rule part specifies a COMMA-separated list of ordinals specifying weeks of the year. Valid values are 1 to 53 or -53 to -1.
  • BYDAY {string}, The BYDAY rule part specifies a COMMA-separated list of days of the week; SU indicates Sunday; MO indicates Monday; TU indicates Tuesday; WE indicates Wednesday; TH indicates Thursday; FR indicates Friday; and SA indicates Saturday.
  • BYMONTHDAY {string}, The BYMONTHDAY rule part specifies a COMMA-separated list of days of the month. Valid values are 1 to 31 or -31 to -1. For example, -10 represents the tenth to the last day of the month. The BYMONTHDAY rule part MUST NOT be specified when the FREQ rule part is set to WEEKLY.
  • BYYEARDAY {string}, The BYYEARDAY rule part specifies a COMMA-separated list of days of the year. Valid values are 1 to 366 or -366 to -1. For example, -1 represents the last day of the year (December 31st) and -306 represents the 306th to the last day of the year (March 1st). The BYYEARDAY rule part MUST NOT be specified when the FREQ rule part is set to DAILY, WEEKLY, or MONTHLY.
  • BYSETPOS {string}, The BYSETPOS rule part specifies a COMMA-separated list of values that corresponds to the nth occurrence within the set of recurrence instances specified by the rule. BYSETPOS operates on a set of recurrence instances in one interval of the recurrence rule. For example, in a WEEKLY rule, the interval would be one week A set of recurrence instances starts at the beginning of the interval defined by the FREQ rule part. Valid values are 1 to 366 or -366 to -1. It MUST only be used in conjunction with another BYxxx rule part. For example "the last work day of the month" could be represented as: FREQ=MONTHLY;BYDAY=MO,TU,WE,TH,FR;BYSETPOS=-1 Each BYSETPOS value can include a positive (+n) or negative (-n) integer. If present, this indicates the nth occurrence of the specific occurrence within the set of occurrences specified by the rule.
  • BYMONTH {string}, The BYMONTH rule part specifies a COMMA-separated list of months of the year. Valid values are 1 to 12.
  • BYHOUR {string}, The BYHOUR rule part specifies a COMMA-separated list of hours of the day. Valid values are 0 to 23.
  • BYMINUTE {string}, The BYMINUTE rule part specifies a COMMA-separated list of minutes within an hour. Valid values are 0 to 59.
  • BYSECOND {string}, The BYSECOND rule part specifies a COMMA-separated list of seconds within a minute. Valid values are 0 to 60.
oOptions IRecurOptions <optional>
 Specifies the options to create the parsing object, as an object of {exontrol.ICalendar.IRecurOptions} type
Returns:
Returns an object of IRecur type
Type
IRecur
Example
exontrol.ICalendar.IRecur.Parse("FREQ=WEEKLY;BYDAY=MO,WE") or exontrol.ICalendar.IRecur.Parse({FREQ:"WEEKLY",BYDAY:"MO,WE"}), every week on Monday, Wednesday
 exontrol.ICalendar.IRecur.Parse("FREQ=DAILY;INTERVAL=3;COUNT=10"), every 3 days for 10 times
 exontrol.ICalendar.IRecur.Parse("FREQ=MONTHLY;BYMONTHDAY=10,15;COUNT=20"), every month on the 10th and 15th for 20 times

all(optionsopt) → {object}

The all() method gets all or only a part of recurrences.
Parameters:
Name Type Attributes Description
options object <optional>
 Defines the options to collect recurrences, as an object of {start,count,until,filter} type. If options is missing the method gets all recurrences.
Properties
Name Type Description
start number | string | Date Specifies the date the method starts collecting recurrences from. If missing the DTSTART rule or current date and time is used instead. If start option and DTSTART rule are present, the method collects recurrences from max(start, DTSTART).
until number | string | Date Specifies the date the method ends collecting recurrences to. If missing the UNTIL rule is used instead. If until option and UNTIL rule are present, the method collects recurrences until min(until, UNTIL).
count number Specifies the number of recurrences to return (overrides the COUNT rule). If missing, the COUNT rule is used instead.
filter callback Specifies a function of callback(dateTimeN) {number} type that filters the date-time within the result. The dateTimeN parameter indicates the result of getTime() method of a Date object (An integer value representing the number of milliseconds since January 1, 1970, 00:00:00 UTC). For instance: function(dateTime) { return dateTime - dateTime % exontrol.msday; } excludes the time from the each date-time of the result.
Returns:
Returns undefined (the rules-expression is not valid), or an object of exontrol.Arr([dateTimeN]) type, where dateTimeN is the result of Date's getTime() method (An integer value representing the number of milliseconds since January 1, 1970, 00:00:00 UTC)
Type
object
Example
all(), {object} returns all recurrences, as an object of exontrol.Arr([dateTimeN]) type
 all({filter: function(dateTime) { return dateTime - dateTime % exontrol.msday; }}), {object} returns all recurrences, as an object of exontrol.Arr([dateN]) type (excludes the time)
 all({start: 2001}), {object} returns all recurrences after Jan 1st, 2001, as an object of exontrol.Arr([dateTimeN]) type
 all({until: "#2/15/2002#"}), {object} returns all recurrences before Feb 15st, 2002, as an object of exontrol.Arr([dateTimeN]) type

error() → {string}

The error() method describes the parsing error
Returns:
Returns the description of the parsing error.
Type
string

get(rule) → {any}

The get() method requests the value of specified rule
Parameters:
Name Type Description
rule string Indicates the name of the rule to request
Returns:
Returns undefined if no rule is found, or the value of the rule, as explained:
  • "FREQ" {string}, "SECONDLY", "MINUTELY", "HOURLY", "DAILY", "WEEKLY", "MONTHLY", "YEARLY"
  • "DTSTART" {Date}, an object of Date type
  • "INTERVAL" {number}, a positive integer
  • "COUNT" {number}, an integer
  • "WKST" {exontrol.WeekDayEnum}, any integer between 0 to 6
  • "UNTIL" {Date}, an object of Date type
  • "BYWEEKNO" {number[]}, stores an array of [number] type. Valid values are 1 to 53 or -53 to -1.
  • "BYDAY" {Map}, gets undefined (missing or invalid values for "BYDAY" rule), or a map of [weekday => [ordwk]] type, where weekday is of exontrol.WeekDayEnum type and ordwk is an integer between -53 and 53
  • "BYMONTHDAY" {number[]}, stores an array of [number] type. Valid values are 1 to 31 or -31 to -1.
  • "BYYEARDAY" {number[]}, stores an array of [number] type. Valid values are 1 to 366 or -366 to -1.
  • "BYSETPOS" {number[]}, stores an array of [number] type. Valid values are 1 to 366 or -366 to -1.
  • "BYMONTH" {number[]}, stores an array of [number] type. Valid values are 1 to 12.
  • "BYHOUR" {number[]}, stores an array of [number] type. Valid values are 0 to 23.
  • "BYMINUTE" {number[]}, stores an array of [number] type. Valid values are 0 to 59.
  • "BYSECOND" {number[]}, stores an array of [number] type. Valid values are 0 to 60.
Type
any

has(rule) → {boolean}

The has() method checks whether the specified rule exists
Parameters:
Name Type Description
rule string Indicates the name of the rule to request. The rule can be aby of the following:
  • FREQ, {string} The FREQ rule part identifies the type of recurrence rule. This rule part MUST be specified in the recurrence rule. Valid values include SECONDLY, to specify repeating events based on an interval of a second or more; MINUTELY, to specify repeating events based on an interval of a minute or more; HOURLY, to specify repeating events based on an interval of an hour or more; DAILY, to specify repeating events based on an interval of a day or more; WEEKLY, to specify repeating events based on an interval of a week or more; MONTHLY, to specify repeating events based on an interval of a month or more; and YEARLY, to specify repeating events based on an interval of a year or more. The valid values are "SECONDLY", "MINUTELY", "HOURLY", "DAILY", "WEEKLY", "MONTHLY" and "YEARLY".
  • DTSTART {Date}, The DTSTART rule specifies the date the recurrence starts from, in YYYYMMDD[THHNNSS[Z]] format. If missing the current date and time is used.
  • INTERVAL {number}, The INTERVAL rule part contains a positive integer representing at which intervals the recurrence rule repeats. The default value is "1", meaning every second for a SECONDLY rule, every minute for a MINUTELY rule, every hour for an HOURLY rule, every day for a DAILY rule, every week for a WEEKLY rule, every month for a MONTHLY rule, and every year for a YEARLY rule. For example, within a DAILY rule, a value of "8" means every eight days.
  • COUNT {number}, The COUNT rule part defines the number of occurrences at which to range-bound the recurrence. The "DTSTART" property value always counts as the first occurrence.
  • WKST {string}, The WKST rule part specifies the day on which the workweek starts. Valid values are MO, TU, WE, TH, FR, SA, and SU. This is significant when a WEEKLY "RRULE" has an interval greater than 1, and a BYDAY rule part is specified. This is also significant when in a YEARLY "RRULE" when a BYWEEKNO rule part is specified. The default value is MO.
  • UNTIL {Date}, The UNTIL rule part defines a DATE or DATE-TIME value that bounds the recurrence rule in an inclusive manner. If the value specified by UNTIL is synchronized with the specified recurrence, this DATE or DATE-TIME becomes the last instance of the recurrence. The value of the UNTIL rule part MUST have the same value type as the "DTSTART" property.
  • BYWEEKNO {string}, The BYWEEKNO rule part specifies a COMMA-separated list of ordinals specifying weeks of the year. Valid values are 1 to 53 or -53 to -1.
  • BYDAY {string}, The BYDAY rule part specifies a COMMA-separated list of days of the week; SU indicates Sunday; MO indicates Monday; TU indicates Tuesday; WE indicates Wednesday; TH indicates Thursday; FR indicates Friday; and SA indicates Saturday.
  • BYMONTHDAY {string}, The BYMONTHDAY rule part specifies a COMMA-separated list of days of the month. Valid values are 1 to 31 or -31 to -1. For example, -10 represents the tenth to the last day of the month. The BYMONTHDAY rule part MUST NOT be specified when the FREQ rule part is set to WEEKLY.
  • BYYEARDAY {string}, The BYYEARDAY rule part specifies a COMMA-separated list of days of the year. Valid values are 1 to 366 or -366 to -1. For example, -1 represents the last day of the year (December 31st) and -306 represents the 306th to the last day of the year (March 1st). The BYYEARDAY rule part MUST NOT be specified when the FREQ rule part is set to DAILY, WEEKLY, or MONTHLY.
  • BYSETPOS {string}, The BYSETPOS rule part specifies a COMMA-separated list of values that corresponds to the nth occurrence within the set of recurrence instances specified by the rule. BYSETPOS operates on a set of recurrence instances in one interval of the recurrence rule. For example, in a WEEKLY rule, the interval would be one week A set of recurrence instances starts at the beginning of the interval defined by the FREQ rule part. Valid values are 1 to 366 or -366 to -1. It MUST only be used in conjunction with another BYxxx rule part. For example "the last work day of the month" could be represented as: FREQ=MONTHLY;BYDAY=MO,TU,WE,TH,FR;BYSETPOS=-1 Each BYSETPOS value can include a positive (+n) or negative (-n) integer. If present, this indicates the nth occurrence of the specific occurrence within the set of occurrences specified by the rule.
  • BYMONTH {string}, The BYMONTH rule part specifies a COMMA-separated list of months of the year. Valid values are 1 to 12.
  • BYHOUR {string}, The BYHOUR rule part specifies a COMMA-separated list of hours of the day. Valid values are 0 to 23.
  • BYMINUTE {string}, The BYMINUTE rule part specifies a COMMA-separated list of minutes within an hour. Valid values are 0 to 59.
  • BYSECOND {string}, The BYSECOND rule part specifies a COMMA-separated list of seconds within a minute. Valid values are 0 to 60.
Returns:
Returns a truly value that specifies whether the rule exists
Type
boolean

parse(expression) → {IRecur}

The parse() method parses the recurrence-rules to an IRecur object
Parameters:
Name Type Description
expression string Indicates the recurrence-expression to parse. The expression may include any of the following fields:
  • FREQ, {string} The FREQ rule part identifies the type of recurrence rule. This rule part MUST be specified in the recurrence rule. Valid values include SECONDLY, to specify repeating events based on an interval of a second or more; MINUTELY, to specify repeating events based on an interval of a minute or more; HOURLY, to specify repeating events based on an interval of an hour or more; DAILY, to specify repeating events based on an interval of a day or more; WEEKLY, to specify repeating events based on an interval of a week or more; MONTHLY, to specify repeating events based on an interval of a month or more; and YEARLY, to specify repeating events based on an interval of a year or more. The valid values are "SECONDLY", "MINUTELY", "HOURLY", "DAILY", "WEEKLY", "MONTHLY" and "YEARLY".
  • DTSTART {Date}, The DTSTART rule specifies the date the recurrence starts from, in YYYYMMDD[THHNNSS[Z]] format. If missing the current date and time is used.
  • INTERVAL {number}, The INTERVAL rule part contains a positive integer representing at which intervals the recurrence rule repeats. The default value is "1", meaning every second for a SECONDLY rule, every minute for a MINUTELY rule, every hour for an HOURLY rule, every day for a DAILY rule, every week for a WEEKLY rule, every month for a MONTHLY rule, and every year for a YEARLY rule. For example, within a DAILY rule, a value of "8" means every eight days.
  • COUNT {number}, The COUNT rule part defines the number of occurrences at which to range-bound the recurrence. The "DTSTART" property value always counts as the first occurrence.
  • WKST {string}, The WKST rule part specifies the day on which the workweek starts. Valid values are MO, TU, WE, TH, FR, SA, and SU. This is significant when a WEEKLY "RRULE" has an interval greater than 1, and a BYDAY rule part is specified. This is also significant when in a YEARLY "RRULE" when a BYWEEKNO rule part is specified. The default value is MO.
  • UNTIL {Date}, The UNTIL rule part defines a DATE or DATE-TIME value that bounds the recurrence rule in an inclusive manner. If the value specified by UNTIL is synchronized with the specified recurrence, this DATE or DATE-TIME becomes the last instance of the recurrence. The value of the UNTIL rule part MUST have the same value type as the "DTSTART" property.
  • BYWEEKNO {string}, The BYWEEKNO rule part specifies a COMMA-separated list of ordinals specifying weeks of the year. Valid values are 1 to 53 or -53 to -1.
  • BYDAY {string}, The BYDAY rule part specifies a COMMA-separated list of days of the week; SU indicates Sunday; MO indicates Monday; TU indicates Tuesday; WE indicates Wednesday; TH indicates Thursday; FR indicates Friday; and SA indicates Saturday.
  • BYMONTHDAY {string}, The BYMONTHDAY rule part specifies a COMMA-separated list of days of the month. Valid values are 1 to 31 or -31 to -1. For example, -10 represents the tenth to the last day of the month. The BYMONTHDAY rule part MUST NOT be specified when the FREQ rule part is set to WEEKLY.
  • BYYEARDAY {string}, The BYYEARDAY rule part specifies a COMMA-separated list of days of the year. Valid values are 1 to 366 or -366 to -1. For example, -1 represents the last day of the year (December 31st) and -306 represents the 306th to the last day of the year (March 1st). The BYYEARDAY rule part MUST NOT be specified when the FREQ rule part is set to DAILY, WEEKLY, or MONTHLY.
  • BYSETPOS {string}, The BYSETPOS rule part specifies a COMMA-separated list of values that corresponds to the nth occurrence within the set of recurrence instances specified by the rule. BYSETPOS operates on a set of recurrence instances in one interval of the recurrence rule. For example, in a WEEKLY rule, the interval would be one week A set of recurrence instances starts at the beginning of the interval defined by the FREQ rule part. Valid values are 1 to 366 or -366 to -1. It MUST only be used in conjunction with another BYxxx rule part. For example "the last work day of the month" could be represented as: FREQ=MONTHLY;BYDAY=MO,TU,WE,TH,FR;BYSETPOS=-1 Each BYSETPOS value can include a positive (+n) or negative (-n) integer. If present, this indicates the nth occurrence of the specific occurrence within the set of occurrences specified by the rule.
  • BYMONTH {string}, The BYMONTH rule part specifies a COMMA-separated list of months of the year. Valid values are 1 to 12.
  • BYHOUR {string}, The BYHOUR rule part specifies a COMMA-separated list of hours of the day. Valid values are 0 to 23.
  • BYMINUTE {string}, The BYMINUTE rule part specifies a COMMA-separated list of minutes within an hour. Valid values are 0 to 59.
  • BYSECOND {string}, The BYSECOND rule part specifies a COMMA-separated list of seconds within a minute. Valid values are 0 to 60.
Returns:
Returns the object itself, as an object of IRecur type
Type
IRecur

valid() → {boolean}

The valid() method checks whether the current recurrence-expression is valid
Returns:
Returns true if the recurrence-expression is valid, else returns false
Type
boolean