new IRecur(optionsopt)
The IRecur object (part of ExICalendar/JS) defines recurrence rules (RRULE) in accordance with the Internet Calendaring and Scheduling Core Object Specification (RFC 5545). It allows you to parse RRULE expressions and generate the corresponding occurrences.
For example, the RRULE expression "FREQ=DAILY;INTERVAL=2" defines a recurrence that repeats every two days. Calling IRecur.Parse("FREQ=DAILY;INTERVAL=2").all() returns all occurrences generated by this rule.
The IRecur.Parse(expression) method parses the specified recurrence rule string and returns an object of type IRecur. Once parsed, you can use the IRecur.all(options) method to retrieve either all occurrences or a limited set of occurrences, depending on the provided options (such as date range or maximum count).
The IRecur object supports common RRULE components such as FREQ, INTERVAL, COUNT, UNTIL, BYDAY, BYMONTH, BYMONTHDAY, and others, allowing you to define complex recurrence patterns like weekly events on specific days, monthly events on a certain weekday, or yearly events on a specific date.
Parameters:
| Name | Type | Attributes | Description |
|---|---|---|---|
options |
IRecurOptions |
<optional> |
Specifies the options to create the parsing object, as an object of exontrol.ICalendar.IRecurOptions type. |
Requires:
- module:exontrol.commmon.min.js
Example
The following samples are equivalent, as they both parse the same RRULE expression "FREQ=WEEKLY;BYDAY=MO;INTERVAL=2" to create an IRecur object that defines a recurrence rule for an event that occurs every two weeks on Monday:
var oRecur = exontrol.ICalendar.IRecur.Parse("FREQ=WEEKLY;BYDAY=MO;INTERVAL=2");
and
var oRecur = new exontrol.ICalendar.IRecur();
oRecur.parse("FREQ=WEEKLY;BYDAY=MO;INTERVAL=2");
Once you have the IRecur object, you can call the all() method to get the occurrences generated by the rule. For example, to get the first 10 occurrences of the rule, you can use the following code:
oRecur.all({count: 10, asDate: true}).forEach(function(element)
{
console.log(element);
});Requires
- module:exontrol.commmon.min.js
Members
(static, readonly) type :string
The type field holds the full name of the object, since constructor.name can differ in minimized or obfuscated code. This field is never altered by the control itself, so it can be reliably used to verify the object's type. It is particularly useful when multiple versions of a control exist or when you need to check the type without depending on constructor.name, which may be inconsistent in some scenarios, such as minified code.
The IRecur.type member always returns "IRecur"
Type:
- string
- Since:
- 1.8
Example
console.log(exontrol.IRecur.type); // logs "IRecur"(static, readonly) version :string
The version field defines the version of the control. Each release of the control has a different version number, so you can use this field to check the control's version and ensure that it supports the features you want to use. The version field is especially useful when you have multiple versions of the control, or when you want to check the version of the control without relying on other properties or methods that may differ between versions.
The current version is 3.2
Type:
- string
Example
console.log(exontrol.IRecur.version); // displays the version of the control, for instance "3.2"(static) count :number
The count field defines the number of recurrences to get if no UNTIL or COUNT part rule. The default value is 256, which means that if the recurrence rule does not specify an UNTIL or COUNT part, the IRecur.all() method will return up to 256 occurrences. This field can be adjusted based on your needs, but it is important to note that setting it too high may lead to performance issues if the recurrence rule generates a large number of occurrences. The count field serves as a safeguard to prevent infinite loops or excessive memory usage when dealing with recurrence rules that could potentially generate an unbounded number of occurrences.
Type:
- number
Example
10 {number}, limits the number of occurrences to get to 10, since no UNTIL or COUNT part rule is specified in the RRULE expressionMethods
all(optionsopt) → {object}
The all() method retrieves all recurrences or only a subset of them, depending on the specified options. It generates occurrences based on the FREQ, INTERVAL, BYDAY, BYMONTHDAY, BYYEARDAY, BYWEEKNO, and BYMONTH rule components, as well as the values provided through the options parameter.
The method returns undefined if the rule expression is invalid. Otherwise, it returns an object of type exontrol.Arr([dateTimeN]), where each dateTimeN represents the value returned by JavaScript's Date.getTime() method (the number of milliseconds since January 1, 1970, 00:00:00 UTC).
- If options.asDate is set to true (since 5.2), the method returns an exontrol.Arr({Date}) object, where each item is a JavaScript Date object
- If options.asArray is set to true (since 5.2), the method returns a standard JavaScript array instead of exontrol.Arr, containing either date-time numbers or Date objects (when options.asDate is also true)
The valid() method checks whether the current recurrence-expression is valid. If the expression is invalid, the all() method returns undefined. Otherwise, it returns the recurrences based on the rules and options.
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
|
Returns:
Returns one of the following:
- undefined, if the rules-expression is not valid
- 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)
- (options.asArray) an array or of [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) (@since 5.2)
- (options.asDate) an object of exontrol.Arr({Date}) type, where each Date is an object of Date type (@since 5.2)
- (options.asDate and options.asArray) an array of {Date} type, where each Date is an object of Date type (@since 5.2)
- 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]) typeerror() → {string}
The error() method describes the parsing error. The method returns an empty string if there is no parsing error, or a string that describes the parsing error if there is a parsing error. The valid() method can be used to check whether there is a parsing error or not. The get() method can be used to get the value of a rule, if there is no parsing error. The has() method can be used to check whether a rule exists, if there is no parsing error.
The parsing error shows as one of the following:
- Error: Empty or Invalid recurrence
- Error: The FREQ rule is missing or invalid
- ...
- Error: The UNTIL rule is invalid
- Error: Unknown RRULE property '...'
Returns:
Returns the description of the parsing error.
- Type
- string
get(rule) → {any}
The get() method requests the value of specified rule. The method returns undefined if there is a parsing error or if the rule is not found, or returns the value of the rule if there is no parsing error and the rule is found. The valid() method can be used to check whether there is a parsing error or not. The has() method can be used to check whether a rule exists, if there is no parsing error.
Parameters:
| Name | Type | Description |
|---|---|---|
rule |
string | Indicates the name of the rule to request as one of the following (case insensitive):
|
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. The method returns a truthy value if the rule exists, or returns undefined if the rule does not exist. The valid() method can be used to check whether there is a parsing error or not. The get() method can be used to get the value of a rule, if there is no parsing error and the rule exists.
Parameters:
| Name | Type | Description |
|---|---|---|
rule |
string | Indicates the name of the rule to request (case insensitive). Valid values are:
|
Returns:
Returns a truthy value that specifies whether the rule exists
- Type
- boolean
parse(expression) → {IRecur}
The parse() method parses the giving expression and sets the rules and values of the IRecur object accordingly. The valid() method can be called after this method to check if the parsing is successful and the rules are valid. The error() method can also be called to get the parsing error details if the parsing is not successful.
Parameters:
| Name | Type | Description |
|---|---|---|
expression |
string | Indicates the expression as a string of "rule=value;..." RRULE format, as defined in RFC 5545. The rules can be in any order, separated by ; (semi-colon) character and could be as follows:
|
Returns:
Returns the object itself, as an object of IRecur type
- Type
- IRecur
Example
The following code parses the expression of "FREQ=WEEKLY;BYDAY=MO,WE" and checks if the parsing is successful and the rules are valid. If not, it gets the parsing error details:
var oRecur = exontrol.ICalendar.IRecur.Parse("FREQ=WEEKLY;BYDAY=MO,WE");
if ( oRecur.valid() )
{
// the parsing is successful and the rules are valid, do something with oRecur
}valid() → {boolean}
The valid() method checks whether the current recurrence-expression is valid. The method returns true if the expression is valid, or false if the expression is invalid. An invalid expression includes an empty expression, missing FREQ rule, invalid FREQ value, unknown rule or invalid rule value. The error() method can be used to get the description of the parsing error. The valid() method should be used after the IRecur object is created, to check whether the expression is valid or not. The get() method can be used to get the value of a rule, if the expression is valid. The has() method can be used to check whether a rule exists, if the expression is valid.
Returns:
Returns true if the recurrence-expression is valid, else returns false
- Type
- boolean
Example
The following example creates a recurrence rule with "FREQ=DAILY;INTERVAL=2;COUNT=5" expression, checks whether the expression is valid and gets the error description if the expression is invalid:
var oRecur = new IRecur("FREQ=DAILY;INTERVAL=2;COUNT=5");
if ( oRecur.valid() )
console.log("The expression is valid.");
else
console.log("The expression is invalid. Error: " + oRecur.error());
The sample output of the above code is:
The expression is valid.(static) Parse(expression, optionsopt) → {IRecur}
The Parse() method parses the giving recurrence-rules and returns an object of IRecur type. The Parse() method also caches the parsed expression, so if the same expression is parsed again, the cached IRecur object is returned instead of parsing the expression again. This caching mechanism improves performance when the same recurrence rules are used multiple times. The valid() method can be used to check if the parsing was successful or if there were any errors in the RRULE expression. If the expression is valid, you can then call the all() method to retrieve the occurrences generated by the rule.
Parameters:
| Name | Type | Attributes | Description |
|---|---|---|---|
expression |
string | object | Indicates the recurrence-expression to parse, as:
|
|
options |
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