Defines the data structure for representing date-times. More...

Data Structures
struct	icaltimetype

Functions
void	icaltime_adjust (struct icaltimetype *tt, const int days, const int hours, const int minutes, const int seconds)
const char *	icaltime_as_ical_string (const struct icaltimetype tt)
char *	icaltime_as_ical_string_r (const struct icaltimetype tt)
icaltime_t	icaltime_as_timet (const struct icaltimetype tt)
icaltime_t	icaltime_as_timet_with_zone (const struct icaltimetype tt, const icaltimezone *zone)
int	icaltime_compare (const struct icaltimetype a, const struct icaltimetype b)
int	icaltime_compare_date_only (const struct icaltimetype a, const struct icaltimetype b)
int	icaltime_compare_date_only_tz (const struct icaltimetype a, const struct icaltimetype b, icaltimezone *tz)
struct icaltimetype	icaltime_convert_to_zone (const struct icaltimetype tt, icaltimezone *zone)
struct icaltimetype	icaltime_current_time_with_zone (const icaltimezone *zone)
int	icaltime_day_of_week (const struct icaltimetype t)
int	icaltime_day_of_year (const struct icaltimetype t)
int	icaltime_days_in_month (const int month, const int year)
int	icaltime_days_in_year (const int year)
struct icaltimetype	icaltime_from_day_of_year (const int doy, const int year)
struct icaltimetype	icaltime_from_string (const char *str)
struct icaltimetype	icaltime_from_timet_with_zone (const icaltime_t tm, const bool is_date, const icaltimezone *zone)
	Constructor.
const icaltimezone *	icaltime_get_timezone (const struct icaltimetype t)
const char *	icaltime_get_tzid (const struct icaltimetype t)
bool	icaltime_is_date (const struct icaltimetype t)
bool	icaltime_is_leap_year (const int year)
bool	icaltime_is_null_time (const struct icaltimetype t)
bool	icaltime_is_utc (const struct icaltimetype t)
bool	icaltime_is_valid_time (const struct icaltimetype t)
struct icaltimetype	icaltime_normalize (const struct icaltimetype tt)
struct icaltimetype	icaltime_null_date (void)
struct icaltimetype	icaltime_null_time (void)
struct icaltimetype	icaltime_set_timezone (struct icaltimetype t, const icaltimezone zone)
int	icaltime_start_doy_week (const struct icaltimetype t, int fdow)
struct icaltimetype	icaltime_today (void)
	Convenience constructor.

Detailed Description

Defines the data structure for representing date-times.

struct icaltimetype is a pseudo-object that abstracts time handling.

It can represent either a DATE or a DATE-TIME (floating, UTC or in a given timezone), and it keeps track internally of its native timezone.

The typical usage is to call the correct constructor specifying the desired timezone. If this is not known until a later time, the correct behavior is to specify a NULL timezone and call icaltime_convert_to_zone() at a later time.

There are several ways to create a new icaltimetype:

icaltime_null_time()
icaltime_null_date()
icaltime_current_time_with_zone()
icaltime_today()
icaltime_from_timet_with_zone(icaltime_t tm, int is_date, icaltimezone *zone)
icaltime_from_day_of_year(int doy, int year)

icaltimetype objects can be converted to different formats:

icaltime_as_timet(struct icaltimetype tt)
icaltime_as_timet_with_zone(struct icaltimetype tt, icaltimezone *zone)
icaltime_as_ical_string(struct icaltimetype tt)

Accessor methods include:

icaltime_get_timezone(struct icaltimetype t)
icaltime_get_tzid(struct icaltimetype t)
icaltime_set_timezone(struct icaltimetype t, const icaltimezone *zone)
icaltime_day_of_year(struct icaltimetype t)
icaltime_day_of_week(struct icaltimetype t)
icaltime_start_doy_week(struct icaltimetype t, int fdow)

Query methods include:

icaltime_is_null_time(struct icaltimetype t)
icaltime_is_valid_time(struct icaltimetype t)
icaltime_is_date(struct icaltimetype t)
icaltime_is_utc(struct icaltimetype t)

Modify, compare and utility methods include:

icaltime_compare(struct icaltimetype a,struct icaltimetype b)
icaltime_compare_date_only(struct icaltimetype a, struct icaltimetype b)
icaltime_adjust(struct icaltimetype *tt, int days, int hours, int minutes, int seconds);
icaltime_normalize(struct icaltimetype t);
icaltime_convert_to_zone(const struct icaltimetype tt, icaltimezone *zone);

Definition in file icaltime.h.

Function Documentation

◆ icaltime_adjust()

void icaltime_adjust	(	struct icaltimetype *	tt,
		const int	days,
		const int	hours,
		const int	minutes,
		const int	seconds )

Adds or subtracts time from an icaltimetype.

Adds or subtracts a time from an icaltimetype. This time is given as a number of days, hours, minutes and seconds.

Parameters

tt	is a pointer to a valid icaltimetype
days	is the number of days adjustment
hours	is the number of hours adjustment
minutes	is the number of minutes adjustment
seconds	is the number of seconds adjustment

Note: This function is identical to the static icaltimezone_adjust_change() except for the type of the first parameter.

Definition at line 764 of file icaltime.c.

◆ icaltime_as_ical_string()

const char * icaltime_as_ical_string ( const struct icaltimetype tt )

Returns a string representation of the time, in RFC5545 format.

Parameters

tt	an icaltimetype, presumably containing valid data.

Note: The string is owned by the caller and must be freed accordingly.; No sanity or error checking is performed on the input time tt.

Returns: a string representation of the tt in RFC5545 format.

See also: icaltime_as_ical_string_r

Definition at line 332 of file icaltime.c.

◆ icaltime_as_ical_string_r()

char * icaltime_as_ical_string_r ( const struct icaltimetype tt )

Returns a string representation of the time, in RFC5545 format.

Parameters

tt	an icaltimetype, presumably containing valid data.

Note: The string is owned by the caller and must be freed accordingly.; No sanity or error checking is performed on the input time tt.

Returns: a string representation of the time, in RFC5545 format.

See also: icaltime_as_ical_string

Definition at line 341 of file icaltime.c.

◆ icaltime_as_timet()

icaltime_t icaltime_as_timet ( const struct icaltimetype tt )

Compute the time as seconds past the UNIX epoch.

This function probably won't do what you expect. In particular, you should only pass an icaltime in UTC, since no conversion is done. Even in that case, it's probably better to just use icaltime_as_timet_with_zone().

Parameters

tt	is the icaltimetype

The return value is defined for dates ranging from 1902-01-01 (incl.) up to 10000-01-01 (excl.) if time_t has a size of 64 bit and up to 2038-01-18 (excl.) if it has a size of 32 bit.

Returns: the time as seconds past the UNIX epoch.

Definition at line 259 of file icaltime.c.

◆ icaltime_as_timet_with_zone()

icaltime_t icaltime_as_timet_with_zone	(	const struct icaltimetype	tt,
		const icaltimezone *	zone )

Computes the time as seconds past the UNIX epoch, using the given timezone.

This convenience method combines a call to icaltime_convert_to_zone() with a call to icaltime_as_timet().

If the input timezone is null, no conversion is done; that is, the time is simply returned as icaltime_t in its native timezone.

Parameters

tt	the time to convert
zone	The timezone to use. NULL means no conversion.

Returns: the time as seconds past the UNIX epoch, using the given timezone.

Definition at line 292 of file icaltime.c.

◆ icaltime_compare()

int icaltime_compare	(	const struct icaltimetype	a,
		const struct icaltimetype	b )

Compares to icaltimetypes for equality. This converts both times to the UTC timezone and compares them.

Parameters

a	is the first icaltimetype to compare
b	is the second icaltimetype to compare

Returns: -1, 0, or 1 to indicate that a is less than b, a equals b, or a is greater than b, respectively.

See also: icaltime_compare_date_only, icaltime_compare_date_only_tz

Definition at line 635 of file icaltime.c.

◆ icaltime_compare_date_only()

int icaltime_compare_date_only	(	const struct icaltimetype	a,
		const struct icaltimetype	b )

Like icaltime_compare, but only use the date parts. This converts both times to the UTC timezone and compares their date components.

Parameters

a	is the first icaltimetype to compare
b	is the second icaltimetype to compare

Returns: -1, 0, or 1 to indicate that a is less than b, a equals b, or a is greater than b, respectively.

See also: icaltime_compare, icaltime_compare_date_only_tz

Definition at line 704 of file icaltime.c.

◆ icaltime_compare_date_only_tz()

int icaltime_compare_date_only_tz	(	const struct icaltimetype	a,
		const struct icaltimetype	b,
		icaltimezone *	tz )

Like icaltime_compare, but only use the date parts; accepts timezone. This converts both times to the given timezone and compares their date components.

Parameters

a	is the first icaltimetype to compare
b	is the second icaltimetype to compare
tz	is the timezone to use

Returns: -1, 0, or 1 to indicate that a is less than b, a equals b, or a is greater than b, respectively.

See also: icaltime_compare, icaltime_compare_date_only

Definition at line 734 of file icaltime.c.

◆ icaltime_convert_to_zone()

struct icaltimetype icaltime_convert_to_zone	(	const struct icaltimetype	tt,
		icaltimezone *	zone )

Converts a time from its native timezone to a given timezone.

Parameters

tt	is the icaltimetype to convert
zone	is the timezone to use

If tt is a date, the timezone is not converted and the returned time is an exact copy of tt.

If it's a floating time, the returned object represents the same time relative to zone. For example, if tt represents 9:30 AM floating and zone is the GMT timezone, the returned object will represent 9:30 AM GMT.

Otherwise, the time will be converted to zone, and its timezone property updated to zone.

For example, July 20 1969, 8:17 PM UTC would be converted to July 20 1969, 4:17 PM EDT.

Returns: an icaltimetype containing the timezone shifted tt.

Definition at line 855 of file icaltime.c.

◆ icaltime_current_time_with_zone()

struct icaltimetype icaltime_current_time_with_zone ( const icaltimezone * zone )

Construct an icaltimeype with the current time in the specified timezone.

Parameters

zone	is the timezone to use

Returns: The current time in the given timezone, as an icaltimetype.

Definition at line 249 of file icaltime.c.

◆ icaltime_day_of_week()

int icaltime_day_of_week ( const struct icaltimetype t )

Computes the day of the week for the specified icaltimetype.

Parameters

t	is the icaltimetype

Returns: the day of the week (Sunday is 1, and Saturday is 7) for the time t.

Definition at line 497 of file icaltime.c.

◆ icaltime_day_of_year()

int icaltime_day_of_year ( const struct icaltimetype t )

Computes the day of the year for the specified icaltimetype, counting from 1 (Jan 1st).

Parameters

t	is the icaltimetype

Returns: the day of the year for t (1-366).

Definition at line 533 of file icaltime.c.

◆ icaltime_days_in_month()

int icaltime_days_in_month	(	const int	month,
		const int	year )

Returns the number of days in the given month.

Parameters

month	is a month number (1-12)
year	is the year (e.g. 2001)

Returns: the number of days in the specified month.

Definition at line 471 of file icaltime.c.

◆ icaltime_days_in_year()

int icaltime_days_in_year ( const int year )

Returns the number of days in a specified year.

Parameters

year	is year (e.g. 2001)

Returns: the number of days in the specified year; ie, 365 unless year is a leap year.

Definition at line 460 of file icaltime.c.

◆ icaltime_from_day_of_year()

struct icaltimetype icaltime_from_day_of_year	(	const int	doy,
		const int	year )

Creates a new time, given a day of year and a year.

Parameters

doy	in integer day of the year. Zero and negative numbers represent days of the previous year.
year	the year

Note: that Jan 1 is day 1, not 0.; no sanity or error checking is done for the inputs; it's up to the caller to provide reasonable values.

Returns: a new time, given the day of year and a year.

Definition at line 540 of file icaltime.c.

◆ icaltime_from_string()

struct icaltimetype icaltime_from_string ( const char * str )

Creates a time from a ISO-8601-2004 string, per https://tools.ietf.org/html/rfc5545#section-3.3.5.

Parameters

str	is a string containing a valid DATE-TIME per rfc5545 [ISO-8601-2004]

The string format is based on the [ISO.8601.2004] spec in one of 3 legal forms:

DATE WITH LOCAL TIME "19980118T230000"
DATE WITH UTC TIME "19980119T070000Z"
DATE WITH LOCAL TIME AND TIME ZONE REFERENCE "TZID=America/New_York:19980119T020000"

That is to say, the basic format for time is T[hh][mm][ss] per ISO-8601-2004

Returns: the icaltimetype representation of the specified date or date-time string.

Definition at line 374 of file icaltime.c.

◆ icaltime_from_timet_with_zone()

struct icaltimetype icaltime_from_timet_with_zone	(	const icaltime_t	tm,
		const bool	is_date,
		const icaltimezone *	zone )

Constructor.

Parameters

tm	The time expressed as seconds past UNIX epoch
is_date	Boolean: 1 means we should treat tm as a DATE
zone	The timezone tm is in, NULL means to treat tm as a floating time

Returns: a new icaltime instance, initialized to the given time, optionally using the given timezone.

If the caller specifies the is_date param as TRUE, the returned object is of DATE type, otherwise the input is meant to be of DATE-TIME type. If the zone is not specified (NULL zone param) the time is taken to be floating, that is, valid in any timezone. Note that, in addition to the uses specified in [RFC5545], this can be used when doing simple math on couples of times. If the zone is specified (UTC or otherwise), it's stored in the object and it's used as the native timezone for this object. This means that the caller can convert this time to a different target timezone with no need to store the source timezone.

Definition at line 209 of file icaltime.c.

◆ icaltime_get_timezone()

const icaltimezone * icaltime_get_timezone ( const struct icaltimetype t )

Return the timezone for an icaltimetype.

Parameters

t	is the icaltimetype

Returns: a pointer to the t timezone.

Definition at line 878 of file icaltime.c.

◆ icaltime_get_tzid()

const char * icaltime_get_tzid ( const struct icaltimetype t )

Returns the tzid for an icaltimetype.

Parameters

t	is the icaltimetype

Returns: a string containing the tzid, or NULL for a floating time.

Definition at line 883 of file icaltime.c.

◆ icaltime_is_date()

bool icaltime_is_date ( const struct icaltimetype t )

Determine if the specified icaltimetype is a DATE.

Parameters

t	is the icaltimetype

Returns: true if the t is a DATE (rather than a DATE-TIME); false otherwise.

Definition at line 616 of file icaltime.c.

◆ icaltime_is_leap_year()

bool icaltime_is_leap_year ( const int year )

Returns whether the specified year is a leap year.

Parameters

year	is the year (e.g. 2001)

Returns: true if the year is a leap year; false otherwise.

Definition at line 451 of file icaltime.c.

◆ icaltime_is_null_time()

bool icaltime_is_null_time ( const struct icaltimetype t )

Determine if the specified icaltimetype contain "null" time, where "null" time means that all the contents are 0.

Parameters

t	is the icaltimetype

Returns: true if t represents "null" time; false otherwise.

Definition at line 626 of file icaltime.c.

◆ icaltime_is_utc()

bool icaltime_is_utc ( const struct icaltimetype t )

Determine if the specified icaltimetype is relative to the UTC zone.

Parameters

t	is the icaltimetype

Returns: true if t is relative to UTC zone; false otherwise.

Definition at line 621 of file icaltime.c.

◆ icaltime_is_valid_time()

bool icaltime_is_valid_time ( const struct icaltimetype t )

Determine if the specified icaltimetype is a valid DATE.

Parameters

t	is the icaltimetype

This is usually the result of creating a new time type but not clearing it, or setting one of the flags to an illegal value.

Returns: true if contents of t are valid; false otherwise.

Definition at line 603 of file icaltime.c.

◆ icaltime_normalize()

struct icaltimetype icaltime_normalize ( const struct icaltimetype tt )

Normalizes the icaltime, so all of the time components are in their normal ranges.

Parameters

tt	is the icaltimetype to normalize

For instance, given a time with minutes=70, the minutes will be reduced to 10 and the hour incremented. This allows the caller to do arithmetic on times without worrying about overflow or underflow.

Returns: an icaltimetype containing the normalized tt.

Definition at line 366 of file icaltime.c.

◆ icaltime_null_date()

struct icaltimetype icaltime_null_date ( void )

Construct an icaltimetype with null date.

Returns: A null date icaltimetype, which indicates no time has been set.

Definition at line 584 of file icaltime.c.

◆ icaltime_null_time()

struct icaltimetype icaltime_null_time ( void )

Construct an icaltimetype with null time.

Returns: A null time icaltimetype, which indicates no time has been set. This time represents the beginning of the epoch.

Definition at line 575 of file icaltime.c.

◆ icaltime_set_timezone()

struct icaltimetype icaltime_set_timezone	(	struct icaltimetype *	t,
		const icaltimezone *	zone )

Sets the timezone for an icaltimetype.

Parameters

t	is the icaltimetype
zone	is the timezone to use

Forces the icaltime to be interpreted relative to another timezone. The returned time represents the same time as t, but relative to the new zone.

For example, modifying July 20 1969, 8:17 PM UTC to the EDT time zone would return a time representing July 20 1969, 8:17 PM EDT.

If you need to do timezone conversion, applying offset adjustments, then you should use icaltime_convert_to_zone instead.

If t is of type DATE, its timezone is not modified and the returned time is an exact copy of t.

Returns: a icaltimetype computed from t with the timezone zone.

Definition at line 892 of file icaltime.c.

◆ icaltime_start_doy_week()

int icaltime_start_doy_week	(	const struct icaltimetype	t,
		int	fdow )

Returns the day of the year for the first day of the week that the given time is within.

This uses the first day of the week that contains the given time, which is a Sunday. It returns the day of the year for the resulting day.

Parameters

t	is the icaltimetype
fdow	is the first day of the week expressed as an integer (1-7)

Returns: the day of the year for the Sunday of the week that the given t is within.

Definition at line 512 of file icaltime.c.

◆ icaltime_today()

struct icaltimetype icaltime_today ( void )

Convenience constructor.

Returns: The current day as an icaltimetype, with is_date set.

Definition at line 254 of file icaltime.c.

Data Structures

Functions

Detailed Description

Function Documentation

◆ icaltime_adjust()

◆ icaltime_as_ical_string()

◆ icaltime_as_ical_string_r()

◆ icaltime_as_timet()

◆ icaltime_as_timet_with_zone()

◆ icaltime_compare()

◆ icaltime_compare_date_only()

◆ icaltime_compare_date_only_tz()

◆ icaltime_convert_to_zone()

◆ icaltime_current_time_with_zone()

◆ icaltime_day_of_week()

◆ icaltime_day_of_year()

◆ icaltime_days_in_month()

◆ icaltime_days_in_year()

◆ icaltime_from_day_of_year()

◆ icaltime_from_string()

◆ icaltime_from_timet_with_zone()

◆ icaltime_get_timezone()

◆ icaltime_get_tzid()

◆ icaltime_is_date()

◆ icaltime_is_leap_year()

◆ icaltime_is_null_time()

◆ icaltime_is_utc()

◆ icaltime_is_valid_time()

◆ icaltime_normalize()

◆ icaltime_null_date()

◆ icaltime_null_time()

◆ icaltime_set_timezone()

◆ icaltime_start_doy_week()

◆ icaltime_today()