Libical API Documentation 3.0

Data Structures | Macros | Typedefs | Enumerations | Functions
icalrecur.h File Reference

Routines for dealing with recurring time. More...

Go to the source code of this file.

## Data Structures
struct | icalrecurrencetype

## Macros
#define | ICAL_BY_DAY_SIZE 7*(ICAL_BY_WEEKNO_SIZE-1)+1 /* 1 to N */
#define | ICAL_BY_HOUR_SIZE 25 /* 0 to 23 */
#define | ICAL_BY_MINUTE_SIZE 61 /* 0 to 59 */
#define | ICAL_BY_MONTH_SIZE 14 /* 1 to 13 */
#define | ICAL_BY_MONTHDAY_SIZE 32 /* 1 to 31 */
#define | ICAL_BY_SECOND_SIZE 62 /* 0 to 60 */
#define | ICAL_BY_SETPOS_SIZE ICAL_BY_YEARDAY_SIZE /* 1 to N */
#define | ICAL_BY_WEEKNO_SIZE 56 /* 1 to 55 */
#define | ICAL_BY_YEARDAY_SIZE 386 /* 1 to 385 */

## Typedefs
typedef struct icalrecur_iterator_impl | icalrecur_iterator
typedef enum icalrecurrencetype_frequency | icalrecurrencetype_frequency
typedef enum icalrecurrencetype_skip | icalrecurrencetype_skip
typedef enum icalrecurrencetype_weekday | icalrecurrencetype_weekday

## Enumerations
enum | icalrecurrence_array_max_values { ICAL_RECURRENCE_ARRAY_MAX = 0x7f7f , ICAL_RECURRENCE_ARRAY_MAX_BYTE = 0x7f }
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 }

## Functions
int | icalrecur_expand_recurrence (const char *rule, time_t start, int count, time_t *array)
| Fills an array with the 'count' number of occurrences generated by the rrule. More...
const char * | icalrecur_freq_to_string (icalrecurrencetype_frequency kind)
void | icalrecur_iterator_free (icalrecur_iterator *)
icalrecur_iterator * | icalrecur_iterator_new (struct icalrecurrencetype rule, struct icaltimetype dtstart)
struct icaltimetype | icalrecur_iterator_next (icalrecur_iterator *)
int | icalrecur_iterator_set_start (icalrecur_iterator *impl, struct icaltimetype start)
const char * | icalrecur_skip_to_string (icalrecurrencetype_skip kind)
icalrecurrencetype_frequency | icalrecur_string_to_freq (const char *str)
icalrecurrencetype_skip | icalrecur_string_to_skip (const char *str)
icalrecurrencetype_weekday | icalrecur_string_to_weekday (const char *str)
const char * | icalrecur_weekday_to_string (icalrecurrencetype_weekday kind)
char * | icalrecurrencetype_as_string (struct icalrecurrencetype *recur)
char * | icalrecurrencetype_as_string_r (struct icalrecurrencetype *recur)
void | icalrecurrencetype_clear (struct icalrecurrencetype *r)
enum icalrecurrencetype_weekday | icalrecurrencetype_day_day_of_week (short day)
| Decodes a day to a weekday. More...
int | icalrecurrencetype_day_position (short day)
| Decodes a day to a position of the weekday. More...
struct icalrecurrencetype | icalrecurrencetype_from_string (const char *str)
int | icalrecurrencetype_month_is_leap (short month)
int | icalrecurrencetype_month_month (short month)
int | icalrecurrencetype_rscale_is_supported (void)
icalarray * | icalrecurrencetype_rscale_supported_calendars (void)

## Detailed Description

Routines for dealing with recurring time.

How to use:

1) Get a rule and a start time from a component

icalproperty rrule;
struct icalrecurrencetype recur;
struct icaltimetype dtstart;
rrule = icalcomponent_get_first_property(comp,ICAL_RRULE_PROPERTY);
recur = icalproperty_get_rrule(rrule);
start = icalproperty_get_dtstart(dtstart);
icalrecurrencetype
Definition: icalrecur.h:152
icaltimetype
Definition: icaltime.h:105

Or, just make them up:

recur = icalrecurrencetype_from_string("FREQ=YEARLY;BYDAY=SU,WE");
dtstart = icaltime_from_string("19970101T123000")
icalrecurrencetype_from_string
struct icalrecurrencetype icalrecurrencetype_from_string(const char *str)
Definition: icalrecur.c:555
icaltime_from_string
struct icaltimetype icaltime_from_string(const char *str)
Contructor.
Definition: icaltime.c:339

2) Create an iterator

icalrecur_iterator *ritr;
ritr = icalrecur_iterator_new(recur,start);
icalrecur_iterator_new
icalrecur_iterator * icalrecur_iterator_new(struct icalrecurrencetype rule, struct icaltimetype dtstart)
Definition: icalrecur.c:1918
icalrecur_iterator_impl
Definition: icalrecur.c:925

3) Iterator over the occurrences

struct icaltimetype next;
while (next = icalrecur_iterator_next(ritr)
&& !icaltime_is_null_time(next){
Do something with next
}
icalrecur_iterator_next
struct icaltimetype icalrecur_iterator_next(icalrecur_iterator *)
Definition: icalrecur.c:2900
icaltime_is_null_time
int icaltime_is_null_time(const struct icaltimetype t)
Returns true if the time is null.
Definition: icaltime.c:609

Note that the time returned by icalrecur_iterator_next is in whatever timezone that dtstart is in.

## Macro Definition Documentation

## ◆ ICAL_BY_SECOND_SIZE

#define ICAL_BY_SECOND_SIZE 62 /* 0 to 60 */

Recurrence type routines

## Function Documentation

## ◆ icalrecur_expand_recurrence()

int icalrecur_expand_recurrence | ( | const char * | rule,
|  | time_t | start,
|  | int | count,
|  | time_t * | array
| ) |  |

Fills an array with the 'count' number of occurrences generated by the rrule.

Specifically, this fills `array` up with at most 'count' time_t values, each representing an occurrence time in seconds past the POSIX epoch.

Note that the times are returned in UTC, but the times are calculated in local time. You will have to convert the results back into local time before using them.

## ◆ icalrecur_iterator_free()

void icalrecur_iterator_free | ( | icalrecur_iterator * | i | ) |

Frees the iterator.

## ◆ icalrecur_iterator_new()

icalrecur_iterator * icalrecur_iterator_new | ( | struct icalrecurrencetype | rule,
|  | struct icaltimetype | dtstart
| ) |  |

Creates a new recurrence rule iterator, starting at DTSTART.

## ◆ icalrecur_iterator_next()

struct icaltimetype icalrecur_iterator_next | ( | icalrecur_iterator * | impl | ) |

Gets the next occurrence from an iterator.

## ◆ icalrecur_iterator_set_start()

int icalrecur_iterator_set_start | ( | icalrecur_iterator * | impl,
|  | struct icaltimetype | start
| ) |  |

Sets the date-time at which the iterator will start, where `start` is a value between DTSTART and UNTIL.

NOTE: CAN NOT be used with RRULEs that contain COUNT.

Since
  3.0

## ◆ icalrecurrencetype_day_day_of_week()

enum icalrecurrencetype_weekday icalrecurrencetype_day_day_of_week | ( | short | day | ) |

Decodes a day to a weekday.

Returns
  The decoded day of the week. 1 is Monday, 2 is Tuesday, etc. A position of 0 means 'any' or 'every'.

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.

## ◆ icalrecurrencetype_day_position()

int icalrecurrencetype_day_position | ( | short | day | ) |

Decodes a day to a position of the weekday.

Returns
  The position of the day in the week. 0 == any of day of week. 1 == first, 2 = second, -2 == second to last, etc. 0 means 'any' or 'every'.

## ◆ icalrecurrencetype_from_string()

struct icalrecurrencetype icalrecurrencetype_from_string | ( | const char * | str | ) |

Convert between strings and recurrencetype structures.