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)
 
const char * icalrecur_freq_to_string (icalrecurrencetype_frequency kind)
 
void icalrecur_iterator_free (icalrecur_iterator *)
 
icalrecur_iteratoricalrecur_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)
 
int icalrecurrencetype_day_position (short day)
 
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)
 
icalarrayicalrecurrencetype_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);

Or, just make them up:

recur = icalrecurrencetype_from_string("FREQ=YEARLY;BYDAY=SU,WE");
dtstart = icaltime_from_string("19970101T123000")

2) Create an iterator

ritr = icalrecur_iterator_new(recur,start);

3) Iterator over the occurrences

struct icaltimetype next;
while (next = icalrecur_iterator_next(ritr)
Do something with next
}

Note that 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

Typedef Documentation

◆ icalrecur_iterator

Recurrence iteration routines

Function Documentation

◆ icalrecur_expand_recurrence()

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

Fills array up with at most 'count' time_t values, each representing an occurrence time in seconds past the POSIX epoch

Fill an array with the 'count' number of occurrences generated by the rrule. 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 )

Free the iterator

◆ icalrecur_iterator_new()

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

Create a new recurrence rule iterator, starting at DTSTART

◆ icalrecur_iterator_next()

struct icaltimetype icalrecur_iterator_next ( icalrecur_iterator )

Get the next occurrence from an iterator

◆ icalrecur_iterator_set_start()

int icalrecur_iterator_set_start ( icalrecur_iterator impl,
struct icaltimetype  start 
)

Set 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.

◆ icalrecurrencetype_day_day_of_week()

enum icalrecurrencetype_weekday icalrecurrencetype_day_day_of_week ( short  day)

Array Encoding

The 'day' element of the by_day array is encoded to allow representation of both the day of the week ( Monday, Tueday), but also the Nth day of the week ( First tuesday of the month, last thursday of the year) These routines decode the day values1 == Monday, etc.

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'

◆ icalrecurrencetype_day_position()

int icalrecurrencetype_day_position ( short  day)

0 == any of day of week. 1 == first, 2 = second, -2 == second to last, etc

◆ icalrecurrencetype_from_string()

struct icalrecurrencetype icalrecurrencetype_from_string ( const char *  str)

Recurrance rule parser Convert between strings and recurrencetype structures.

◆ icalrecurrencetype_month_is_leap()

int icalrecurrencetype_month_is_leap ( short  month)

The 'month' element of the by_month array is encoded to allow representation of the "L" leap suffix (RFC 7529). These routines decode the month values.

The 'month' element of the by_month array is encoded to allow representation of the "L" leap suffix (RFC 7529). These routines decode the month values.

The "L" suffix is encoded by setting a high-order bit