diff options
Diffstat (limited to 'src/libical/icalrecur.h')
| -rw-r--r-- | src/libical/icalrecur.h | 84 |
1 files changed, 60 insertions, 24 deletions
diff --git a/src/libical/icalrecur.h b/src/libical/icalrecur.h index ae11a9ae..65b50e50 100644 --- a/src/libical/icalrecur.h +++ b/src/libical/icalrecur.h @@ -58,7 +58,7 @@ Or, just make them up: } @endcode -Note that that the time returned by icalrecur_iterator_next is in +Note that the time returned by icalrecur_iterator_next is in whatever timezone that dtstart is in. */ @@ -172,11 +172,27 @@ struct icalrecurrencetype short by_second[ICAL_BY_SECOND_SIZE]; short by_minute[ICAL_BY_MINUTE_SIZE]; short by_hour[ICAL_BY_HOUR_SIZE]; - short by_day[ICAL_BY_DAY_SIZE]; /* Encoded value, see below */ + short by_day[ICAL_BY_DAY_SIZE]; /**< @brief Encoded value + * + * 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 values are decoded by icalrecurrencetype_day_day_of_week() and + * icalrecurrencetype_day_position(). + */ short by_month_day[ICAL_BY_MONTHDAY_SIZE]; short by_year_day[ICAL_BY_YEARDAY_SIZE]; short by_week_no[ICAL_BY_WEEKNO_SIZE]; - short by_month[ICAL_BY_MONTH_SIZE]; + short by_month[ICAL_BY_MONTH_SIZE]; /**< @brief Encoded value + * + * The 'month' element of the by_month array is encoded to allow + * representation of the "L" leap suffix (RFC 7529). + * + * These values are decoded by icalrecurrencetype_month_is_leap() + * and icalrecurrencetype_month_month(). + */ short by_set_pos[ICAL_BY_SETPOS_SIZE]; /* For RSCALE extension (RFC 7529) */ @@ -190,32 +206,44 @@ LIBICAL_ICAL_EXPORT icalarray *icalrecurrencetype_rscale_supported_calendars(voi LIBICAL_ICAL_EXPORT void icalrecurrencetype_clear(struct icalrecurrencetype *r); -/** - * 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 values +/* + * Routines to decode the day values of the by_day array */ -/** 1 == Monday, etc. */ +/** @brief 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. + */ LIBICAL_ICAL_EXPORT enum icalrecurrencetype_weekday icalrecurrencetype_day_day_of_week(short day); -/** 0 == any of day of week. 1 == first, 2 = second, -2 == second to last, etc */ +/** @brief 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'. + */ LIBICAL_ICAL_EXPORT int icalrecurrencetype_day_position(short day); -/** - * 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. +/* + * Routines to decode the 'month' element of the by_month array */ LIBICAL_ICAL_EXPORT int icalrecurrencetype_month_is_leap(short month); LIBICAL_ICAL_EXPORT int icalrecurrencetype_month_month(short month); -/** Recurrance rule parser */ +/* + * Recurrence rule parser + */ /** Convert between strings and recurrencetype structures. */ LIBICAL_ICAL_EXPORT struct icalrecurrencetype icalrecurrencetype_from_string(const char *str); @@ -224,11 +252,13 @@ LIBICAL_ICAL_EXPORT char *icalrecurrencetype_as_string(struct icalrecurrencetype LIBICAL_ICAL_EXPORT char *icalrecurrencetype_as_string_r(struct icalrecurrencetype *recur); -/** Recurrence iteration routines */ +/* + * Recurrence iteration routines + */ typedef struct icalrecur_iterator_impl icalrecur_iterator; -/** Create a new recurrence rule iterator, starting at DTSTART */ +/** Creates a new recurrence rule iterator, starting at DTSTART. */ LIBICAL_ICAL_EXPORT icalrecur_iterator *icalrecur_iterator_new(struct icalrecurrencetype rule, struct icaltimetype dtstart); @@ -242,15 +272,21 @@ LIBICAL_ICAL_EXPORT icalrecur_iterator *icalrecur_iterator_new(struct icalrecurr LIBICAL_ICAL_EXPORT int icalrecur_iterator_set_start(icalrecur_iterator *impl, struct icaltimetype start); -/** Get the next occurrence from an iterator */ +/** Gets the next occurrence from an iterator. */ LIBICAL_ICAL_EXPORT struct icaltimetype icalrecur_iterator_next(icalrecur_iterator *); -/** Free the iterator */ +/** Frees the iterator. */ LIBICAL_ICAL_EXPORT void icalrecur_iterator_free(icalrecur_iterator *); -/** - * Fills array up with at most 'count' time_t values, each - * representing an occurrence time in seconds past the POSIX epoch +/** @brief Fills an array with the 'count' number of occurrences generated by + * the rrule. + * + * Specifically, this fills @p 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. */ LIBICAL_ICAL_EXPORT int icalrecur_expand_recurrence(const char *rule, time_t start, int count, time_t *array); |