|
Libical API Documentation 4.0 UNRELEASED Go to the stable 3.0 documentation
|
Routines for dealing with recurring time. More...
Go to the source code of this file.
Data Structures | |
| struct | icalrecurrencetype |
Enumerations | |
| enum | ical_invalid_rrule_handling { ICAL_RRULE_TREAT_AS_ERROR = 0 , ICAL_RRULE_IGNORE_INVALID = 1 } |
| enum | icalrecurrencetype_byrule { ICAL_BYRULE_NO_CONTRACTION = -1 , ICAL_BY_MONTH = 0 , ICAL_BY_WEEK_NO = 1 , ICAL_BY_YEAR_DAY = 2 , ICAL_BY_MONTH_DAY = 3 , ICAL_BY_DAY = 4 , ICAL_BY_HOUR = 5 , ICAL_BY_MINUTE = 6 , ICAL_BY_SECOND = 7 , ICAL_BY_SET_POS = 8 , ICAL_BY_NUM_PARTS = 9 } |
| enum | icalrecurrencetype_frequency { ICAL_SECONDLY_RECURRENCE = 0 , ICAL_MINUTELY_RECURRENCE = 1 , ICAL_HOURLY_RECURRENCE = 2 , ICAL_DAILY_RECURRENCE = 3 , ICAL_WEEKLY_RECURRENCE = 4 , ICAL_MONTHLY_RECURRENCE = 5 , ICAL_YEARLY_RECURRENCE = 6 , ICAL_NO_RECURRENCE = 7 } |
| enum | icalrecurrencetype_skip { ICAL_SKIP_BACKWARD = 0 , ICAL_SKIP_FORWARD , ICAL_SKIP_OMIT , ICAL_SKIP_UNDEFINED } |
| enum | icalrecurrencetype_weekday { ICAL_NO_WEEKDAY , ICAL_SUNDAY_WEEKDAY , ICAL_MONDAY_WEEKDAY , ICAL_TUESDAY_WEEKDAY , ICAL_WEDNESDAY_WEEKDAY , ICAL_THURSDAY_WEEKDAY , ICAL_FRIDAY_WEEKDAY , ICAL_SATURDAY_WEEKDAY } |
Routines for dealing with recurring time.
How to use:
1) Get a rule and a start time from a component
Or, just make them up:
2) Create an iterator
3) Iterator over the occurrences
Note that the time returned by icalrecur_iterator_next is in whatever timezone that dtstart is in.
4) Deallocate a rule
The icalrecurrencetype object is reference counted. It will automatically be deallocated when the reference count goes to zero.
Definition in file icalrecur.h.
How the library handles RRULEs with invalid BYxxx part combos.
| Enumerator | |
|---|---|
| ICAL_RRULE_TREAT_AS_ERROR | treat as a error; the internal icalerror to :ICAL_MALFORMEDDATA_ERROR |
| ICAL_RRULE_IGNORE_INVALID | discard and continue normally |
Definition at line 616 of file icalrecur.h.
Recurrence byrule types.
Definition at line 125 of file icalrecur.h.
Recurrence frequencies.
Definition at line 84 of file icalrecur.h.
Recurrence skip types.
Definition at line 114 of file icalrecur.h.
Weekly recurrences days.
Definition at line 99 of file icalrecur.h.
| ical_invalid_rrule_handling ical_get_invalid_rrule_handling_setting | ( | void | ) |
Gets how the library should handle invalid RRULEs.
The default library setting is ICAL_RRULE_TREAT_AS_ERROR.
Definition at line 4252 of file icalrecur.c.
| void ical_set_invalid_rrule_handling_setting | ( | ical_invalid_rrule_handling | newSetting | ) |
Sets how the library should handle invalid RRULEs.
| newSetting | the ical_invalid_rrule_handling to use. |
Definition at line 4269 of file icalrecur.c.
| bool icalrecur_expand_recurrence | ( | const char * | rule, |
| icaltime_t | start, | ||
| int | count, | ||
| icaltime_t * | array ) |
Fills an array with the 'count' number of occurrences generated by the rrule.
Specifically, this fills an array up with at most 'count' icaltime_t values, each representing an occurrence time in seconds past the POSIX epoch.
| rule | a pointer to a char string containing the RRULE to use |
| start | a valid starting date-time |
| count | the length of the provided icalarray |
| array | a pointer to an array of count icaltime_t values resulting from expanding the specified RRULE rule. |
rule could be converted to a string; false otherwise. Definition at line 4216 of file icalrecur.c.
| const char * icalrecur_freq_to_string | ( | icalrecurrencetype_frequency | kind | ) |
Stringifies a icalrecurrencetype_frequency.
| kind | a icalrecurrencetype_frequency to convert |
kind. If kind is invalid then NULL is returned.Definition at line 213 of file icalrecur.c.
| void icalrecur_iterator_free | ( | icalrecur_iterator * | impl | ) |
Frees the specified icalrecur_iterator.
| impl | a pointer to a valid icalrecur_iterator |
Definition at line 2408 of file icalrecur.c.
| icalrecur_iterator * icalrecur_iterator_new | ( | struct icalrecurrencetype * | rule, |
| struct icaltimetype | dtstart ) |
Creates a new recurrence rule iterator starting at DTSTART.
| rule | a pointer to a valid icalrecurrencetype |
| dtstart | a valid icaltimetype to use for the DTSART |
Definition at line 2280 of file icalrecur.c.
| struct icaltimetype icalrecur_iterator_next | ( | icalrecur_iterator * | impl | ) |
Gets the next occurrence from an icalrecur_iterator.
| impl | a pointer to a valid icalrecur_iterator |
Definition at line 3651 of file icalrecur.c.
| struct icaltimetype icalrecur_iterator_prev | ( | icalrecur_iterator * | impl | ) |
Gets the previous occurrence from an icalrecur_iterator.
| impl | a pointer to a valid icalrecur_iterator |
Definition at line 3768 of file icalrecur.c.
| bool icalrecur_iterator_set_end | ( | icalrecur_iterator * | impl, |
| struct icaltimetype | end ) |
Sets the date-time at which the iterator will stop at the latest.
| impl | is a pointer to a valid icalrecur_iterator |
| end | is the ending icaltimetype |
Values equal to or greater than end will not be returned by the iterator.
Definition at line 4087 of file icalrecur.c.
| bool icalrecur_iterator_set_range | ( | icalrecur_iterator * | impl, |
| struct icaltimetype | from, | ||
| struct icaltimetype | to ) |
Sets the date-times over which the iterator will run,
| impl | is a pointer to a valid icalrecur_iterator |
| to | is the starting icaltimetype |
| from | is the ending icaltimetype that must be between DSTART and UNTIL |
If to is null time, the forward iterator will return values up to and including UNTIL (if present), otherwise up to the year 2582.
if to is non-null time and later than from, the forward iterator will return values up to and including 'to'.
If to is non-null time and earlier than from, the reverse iterator will be set to start at from and will return values down to and including to.
NOTE: CAN NOT be used with RRULEs that contain COUNT.
Definition at line 4098 of file icalrecur.c.
| bool icalrecur_iterator_set_start | ( | icalrecur_iterator * | impl, |
| struct icaltimetype | start ) |
Sets the date-time at which the iterator will start,
| impl | is a pointer to a valid icalrecur_iterator |
| start | is the starting icaltimetype that must be between DTSTART and UNTIL. |
Definition at line 4062 of file icalrecur.c.
| bool icalrecur_resize_by | ( | icalrecurrence_by_data * | by, |
| short | size ) |
Resizes the buffer backing the 'by' array to the specified size, if different.
Frees the buffer if the new size is 0.
| by | is a pointer to valid icalrecurrence_by_data to use |
| size | is the new size for the array |
Definition at line 306 of file icalrecur.c.
| const char * icalrecur_skip_to_string | ( | icalrecurrencetype_skip | kind | ) |
Stringifies a icalrecurrencetype_skip.
| kind | a icalrecurrencetype_skip to convert |
kind. If kind is invalid then NULL is returned.Definition at line 246 of file icalrecur.c.
| icalrecurrencetype_frequency icalrecur_string_to_freq | ( | const char * | str | ) |
Converts a char string into a icalrecurrencetype_frequency.
| str | a pointer to a char string containing the string representation of an icalrecurrencetype_frequency. |
str. If str is invalid then ICAL_NO_RECURRENCE is returned.Definition at line 201 of file icalrecur.c.
| icalrecurrencetype_skip icalrecur_string_to_skip | ( | const char * | str | ) |
Converts a char string into a icalrecurrencetype_skip.
| str | a pointer t a char string containing the string representation of an icalrecurrencetype_skip. |
str. If str is invalid then ICAL_SKIP_UNDEFINED is returned.Definition at line 234 of file icalrecur.c.
| icalrecurrencetype_weekday icalrecur_string_to_weekday | ( | const char * | str | ) |
Converts a char string into a icalrecurrencetype_weekday.
| str | a pointer to a char string containing the string representation of a icalrecurrencetype_weekday |
str. If str is invalid then :: ICAL_NO_WEEKDAY is returned.Definition at line 284 of file icalrecur.c.
| const char * icalrecur_weekday_to_string | ( | icalrecurrencetype_weekday | kind | ) |
Stringifies a icalrecurrencetype_weekday.
| kind | a icalrecurrencetype_weekday to convert |
kind. If kind is invalid then NULL is returned.Definition at line 271 of file icalrecur.c.
| char * icalrecurrencetype_as_string | ( | struct icalrecurrencetype * | recur | ) |
Represent an icalrecurrencetype as a string.
| recur | a pointer to a valid icalrecurrencetype |
recur. Returns NULL if the conversion was unsuccessful.Definition at line 1009 of file icalrecur.c.
| char * icalrecurrencetype_as_string_r | ( | struct icalrecurrencetype * | recur | ) |
Represent an icalrecurrencetype as a string.
| recur | a pointer to a valid icalrecurrencetype |
recur. Returns NULL if the conversion was unsuccessful.Definition at line 1018 of file icalrecur.c.
| struct icalrecurrencetype * icalrecurrencetype_clone | ( | struct icalrecurrencetype * | r | ) |
Creates a deep copy of the given icalrecurrencetype.
The new instance is returned with a refcount of 1.
| r | is a pointer to a valid icalrecurrencetype |
Definition at line 797 of file icalrecur.c.
| enum icalrecurrencetype_weekday icalrecurrencetype_day_day_of_week | ( | short | day | ) |
Decode the weekday from a "weekday:pos" form.
| day | is the "weekday:pos" to decode (as created by icalrecurrencetype_encode_day()) |
Definition at line 4178 of file icalrecur.c.
| int icalrecurrencetype_day_position | ( | short | day | ) |
Decodes a the position from a "weekday:pos" form.
| day | is the "weekday:pos" to decode (as created by icalrecurrencetype_encode_day()). |
Definition at line 4183 of file icalrecur.c.
| short icalrecurrencetype_encode_day | ( | enum icalrecurrencetype_weekday | weekday, |
| int | position ) |
Encode a weekday and position into a form which can be stored into a icalrecurrencetype::by[ICAL_BY_DAY] array.
The 'day' element of icalrecurrencetype_weekday is encoded to allow representation of both the day of the week ( Monday, Tuesday), but also the Nth day of the week (First tuesday of the month, last thursday of the year) These routines decode the day values.
The day's position in the period (Nth-ness) and the numerical value of the day are encoded together as: pos*7 + dow.
A position of 0 means 'any' or 'every'.
Use icalrecurrencetype_day_day_of_week() and icalrecurrencetype_day_position() to split the encoded value back into the parts.
| weekday | is the weekday to use |
| position | is the positiog to use |
Definition at line 4194 of file icalrecur.c.
| short icalrecurrencetype_encode_month | ( | int | month, |
| bool | is_leap ) |
Encodes a month and leap year indicator into a form which can be stored into a icalrecurrencetype::by[ICAL_BY_MONTH] array.
The month element of the by[ICAL_BY_MONTH] array is encoded to allow representation of the "L" leap suffix (RFC 7529). The "L" suffix is encoded by setting a high-order bit.
Use icalrecurrencetype_month_is_leap() and icalrecurrencetype_month_month() to split the encoded value back into the parts.
| month | is the month to use (1-12) |
| is_leap | is a bool indicating if leap year is to be considered |
Definition at line 4211 of file icalrecur.c.
| bool icalrecurrencetype_month_is_leap | ( | short | month | ) |
Decode the is_leap from a month:leap_year form.
| month | is the month:leap_year to decode (as created by icalrecurrencetype_encode_month()) |
Definition at line 4201 of file icalrecur.c.
| int icalrecurrencetype_month_month | ( | short | month | ) |
Decode the month from a month:leap_year form.
| month | is the month:leap_year to decode (as created by icalrecurrencetype_encode_month()) |
Definition at line 4206 of file icalrecur.c.
| struct icalrecurrencetype * icalrecurrencetype_new | ( | void | ) |
Constructs a new instance of icalrecurrencetype.
The new instance is initialized with a refcount of 1.
Definition at line 708 of file icalrecur.c.
| struct icalrecurrencetype * icalrecurrencetype_new_from_string | ( | const char * | str | ) |
Create a new icalrecurrencetype from a string.
| str | a pointer to a char string containing string version of the recurrence. |
Definition at line 834 of file icalrecur.c.
| void icalrecurrencetype_ref | ( | struct icalrecurrencetype * | recur | ) |
Increases the icalrecurrencetype reference counter by 1.
| recur | is a pointer to a valid icalrecurrencetype |
Definition at line 747 of file icalrecur.c.
| icalarray * icalrecurrencetype_rscale_supported_calendars | ( | void | ) |
Return an array of RSCALE supported calendars.
Definition at line 1966 of file icalrecur.c.
| void icalrecurrencetype_unref | ( | struct icalrecurrencetype * | recur | ) |
Decreases the icalrecurrencetype reference counter by 1.
If the counter reaches 0, the instance and all referenced memory (i.e. rscale and 'by' arrays) are deallocated.
| recur | a pointer to a valid icalrecurrencetype |
Definition at line 755 of file icalrecur.c.