icalrecur.h File Reference

Routines for dealing with recurring time. More...

Go to the source code of this file.

Data Structures
struct	icalrecurrence_by_data
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 enum ical_invalid_rrule_handling	ical_invalid_rrule_handling
typedef struct icalrecur_iterator_impl	icalrecur_iterator
typedef enum icalrecurrencetype_byrule	icalrecurrencetype_byrule
typedef enum icalrecurrencetype_frequency	icalrecurrencetype_frequency
typedef enum icalrecurrencetype_skip	icalrecurrencetype_skip
typedef enum icalrecurrencetype_weekday	icalrecurrencetype_weekday

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 }

Functions
ical_invalid_rrule_handling	ical_get_invalid_rrule_handling_setting (void)
void	ical_set_invalid_rrule_handling_setting (ical_invalid_rrule_handling newSetting)
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.
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 *)
struct icaltimetype	icalrecur_iterator_prev (icalrecur_iterator *)
bool	icalrecur_iterator_set_end (icalrecur_iterator *impl, struct icaltimetype end)
bool	icalrecur_iterator_set_range (icalrecur_iterator *impl, struct icaltimetype from, struct icaltimetype to)
bool	icalrecur_iterator_set_start (icalrecur_iterator *impl, struct icaltimetype start)
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.
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)
struct icalrecurrencetype *	icalrecurrencetype_clone (struct icalrecurrencetype *r)
	Creates a deep copy of the given recurrence rule. The new instance is returned with a refcount of 1.
enum icalrecurrencetype_weekday	icalrecurrencetype_day_day_of_week (short day)
	Decodes a day to a weekday.
int	icalrecurrencetype_day_position (short day)
	Decodes a day to a position of the weekday.
short	icalrecurrencetype_encode_day (enum icalrecurrencetype_weekday weekday, int position)
short	icalrecurrencetype_encode_month (int month, bool is_leap)
bool	icalrecurrencetype_month_is_leap (short month)
int	icalrecurrencetype_month_month (short month)
struct icalrecurrencetype *	icalrecurrencetype_new (void)
	Allocates and initializes a new instance of icalrecurrencetype. The new instance is returned with a refcount of 1.
struct icalrecurrencetype *	icalrecurrencetype_new_from_string (const char *str)
void	icalrecurrencetype_ref (struct icalrecurrencetype *recur)
	Increases the reference counter by 1.
bool	icalrecurrencetype_rscale_is_supported (void)
icalarray *	icalrecurrencetype_rscale_supported_calendars (void)
void	icalrecurrencetype_unref (struct icalrecurrencetype *recur)
	Decreases the reference counter by 1. If it goes to 0, the instance and all referenced memory (i.e. rscale and 'by' arrays) are deallocated.

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_new_from_string("FREQ=YEARLY;BYDAY=SU,WE");
dtstart = icaltime_from_string("19970101T123000")

2) Create an iterator

icalrecur_iterator *ritr;
ritr = icalrecur_iterator_new(recur, start);

3) Iterator over the occurrences

struct icaltimetype next;
while (next = icalrecur_iterator_next(ritr)
       && !icaltime_is_null_time(next){
        Do something with next
}

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

4) Deallocate a rule

icalrecurrencetype_unref(recur);

The icalrecurrencetype object is reference counted. It will automatically be deallocated when the reference count goes to zero.

Macro Definition Documentation

ICAL_BY_SECOND_SIZE

#define ICAL_BY_SECOND_SIZE   62 /* 0 to 60 */

Recurrence type routines

Function Documentation

icalrecur_expand_recurrence()

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 array up with at most 'count' icaltime_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.

NOTE: The new iterator may keep a reference to the passed rule. It must not be modified as long as the iterator is in use.

icalrecur_iterator_next()

struct icaltimetype icalrecur_iterator_next

(

icalrecur_iterator *

impl

)

Gets the next occurrence from an iterator.

icalrecur_iterator_prev()

struct icaltimetype icalrecur_iterator_prev

(

icalrecur_iterator *

impl

)

Gets the previous occurrence from an iterator.

Since

4.0

icalrecur_iterator_set_end()

bool icalrecur_iterator_set_end	(	icalrecur_iterator *	impl,
		struct icaltimetype	end )

Set the date-time at which the iterator will stop at the latest. Values equal to or greater than end will not be returned by the iterator.

icalrecur_iterator_set_range()

bool icalrecur_iterator_set_range	(	icalrecur_iterator *	impl,
		struct icaltimetype	from,
		struct icaltimetype	to )

Sets the date-times over which the iterator will run, where from is a value between DTSTART 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.

Since

4.0

icalrecur_iterator_set_start()

bool 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

icalrecur_resize_by()

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.

Returns

true on success, false on failure.

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.

A position of 0 means 'any' or 'every'.

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_encode_day()

short icalrecurrencetype_encode_day	(	enum icalrecurrencetype_weekday	weekday,
		int	position )

Encodes the weekday and position into a form, which can be stored to icalrecurrencetype::by[ICAL_BY_DAY] array. Use icalrecurrencetype_day_day_of_week() and icalrecurrencetype_day_position() to split the encoded value back into the parts.

Since

4.0

icalrecurrencetype_encode_month()

short icalrecurrencetype_encode_month	(	int	month,
		bool	is_leap )

Encodes the month and the is_leap into a form, which can be stored to icalrecurrencetype::by[ICAL_BY_MONTH] array. Use icalrecurrencetype_month_is_leap() and icalrecurrencetype_month_month() to split the encoded value back into the parts

Since

4.0

icalrecurrencetype_month_is_leap()

bool icalrecurrencetype_month_is_leap

(

short

month

)

The month element of the by[ICAL_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.

icalrecurrencetype_new()

struct icalrecurrencetype * icalrecurrencetype_new

(

void

)

Allocates and initializes a new instance of icalrecurrencetype. The new instance is returned with a refcount of 1.

Returns

A pointer to the new instance, of NULL if allocation failed.

icalrecurrencetype_new_from_string()

struct icalrecurrencetype * icalrecurrencetype_new_from_string

(

const char *

str

)

Convert between strings and recurrencetype structures.