icaltime.h File Reference

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

Go to the source code of this file.

Data Structures
struct	icaltime_span
struct	icaltimetype

Typedefs
typedef struct icaltime_span	icaltime_span
typedef struct icaltimetype	icaltimetype
typedef struct _icaltimezone	icaltimezone

Functions
void	icaltime_adjust (struct icaltimetype *tt, const int days, const int hours, const int minutes, const int seconds)
	Internal, shouldn't be part of the public API. More...
const char *	icaltime_as_ical_string (const struct icaltimetype tt)
char *	icaltime_as_ical_string_r (const struct icaltimetype tt)
time_t	icaltime_as_timet (const struct icaltimetype)
time_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)
	Convert time to a given timezone. More...
struct icaltimetype	icaltime_current_time_with_zone (const icaltimezone *zone)
	Convenience constructor. More...
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)
	Contructor. More...
struct icaltimetype	icaltime_from_string (const char *str)
	Contructor. More...
struct icaltimetype	icaltime_from_timet_with_zone (const time_t tm, const int is_date, const icaltimezone *zone)
	Constructor. More...
const icaltimezone *	icaltime_get_timezone (const struct icaltimetype t)
	Return the timezone.
const char *	icaltime_get_tzid (const struct icaltimetype t)
	Return the tzid, or NULL for a floating time.
int	icaltime_is_date (const struct icaltimetype t)
	Returns true if time is of DATE type, false if DATE-TIME. More...
int	icaltime_is_leap_year (const int year)
int	icaltime_is_null_time (const struct icaltimetype t)
int	icaltime_is_utc (const struct icaltimetype t)
	Returns true if time is relative to UTC zone. More...
int	icaltime_is_valid_time (const struct icaltimetype t)
struct icaltimetype	icaltime_normalize (const struct icaltimetype t)
struct icaltimetype	icaltime_null_date (void)
	Constructor. More...
struct icaltimetype	icaltime_null_time (void)
	Constructor. More...
struct icaltimetype	icaltime_set_timezone (struct icaltimetype *t, const icaltimezone *zone)
	Set the timezone. More...
int	icaltime_span_contains (icaltime_span *s, icaltime_span *container)
	Returns true if the span is totally within the containing span. More...
struct icaltime_span	icaltime_span_new (struct icaltimetype dtstart, struct icaltimetype dtend, int is_busy)
	calculate an icaltimespan given a start and end time. More...
int	icaltime_span_overlaps (icaltime_span *s1, icaltime_span *s2)
	Returns true if the two spans overlap. More...
int	icaltime_start_doy_week (const struct icaltimetype t, int fdow)
struct icaltimetype	icaltime_today (void)
	Convenience constructor. More...
int	icaltime_week_number (const struct icaltimetype t)

Detailed Description

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(time_t tm, int is_date, icaltimezone *zone)
• icaltime_from_day_of_year(int doy, int year)

italtimetype 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)
• icaltime_week_number(struct icaltimetype t)

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);

Function Documentation

icaltime_adjust()

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

Internal, shouldn't be part of the public API.

Adds or subtracts a number of days, hours, minutes and seconds.

Adds (or subtracts) a time from a icaltimetype. NOTE: This function is exactly the same as icaltimezone_adjust_change() except for the type of the first parameter.

icaltime_as_ical_string()

const char* icaltime_as_ical_string

(

const struct icaltimetype

tt

)

Return a string represention of the time, in RFC5545 format.

Return a string represention of the time, in RFC5545 format. The string is owned by libical.

icaltime_as_ical_string_r()

char* icaltime_as_ical_string_r

(

const struct icaltimetype

tt

)

Return a string represention of the time, in RFC5545 format. The string is owned by the caller.

icaltime_as_timet()

time_t icaltime_as_timet

(

const struct icaltimetype

)

Returns 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().

icaltime_as_timet_with_zone()

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

Return the time as seconds past the UNIX epoch, using timezones.

Return 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 time_t in its native timezone.

icaltime_compare()

int icaltime_compare	(	const struct icaltimetype	a_in,
		const struct icaltimetype	b_in
	)

Return -1, 0, or 1 to indicate that a is less than b, a equals b, or a is greater than b

Return -1, 0, or 1 to indicate that a<b, a==b, or a>b. This calls icaltime_compare function after converting them to the utc timezone.

icaltime_compare_date_only()

int icaltime_compare_date_only	(	const struct icaltimetype	a_in,
		const struct icaltimetype	b_in
	)

like icaltime_compare, but only use the date parts.

icaltime_compare_date_only_tz()

int icaltime_compare_date_only_tz	(	const struct icaltimetype	a_in,
		const struct icaltimetype	b_in,
		icaltimezone *	tz
	)

like icaltime_compare, but only use the date parts.

like icaltime_compare, but only use the date parts; accepts timezone.

icaltime_convert_to_zone()

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

Convert time to a given timezone.

convert tt, of timezone tzid, into a utc time. Does nothing if the time is already UTC.

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

If tt is a date, the returned time is an exact copy of the input. If it's a floating time, the returned object represents the same time translated to the given timezone. Otherwise the time will be converted to the new time zone, and its native timezone set to the right timezone.

icaltime_current_time_with_zone()

struct icaltimetype icaltime_current_time_with_zone

(

const icaltimezone *

zone

)

Convenience constructor.

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

icaltime_day_of_week()

int icaltime_day_of_week

(

const struct icaltimetype

t

)

Return the day of the week of the given time. Sunday is 1

icaltime_day_of_year()

int icaltime_day_of_year

(

const struct icaltimetype

t

)

Return the day of the year of the given time

Returns the day of the year, counting from 1 (Jan 1st).

icaltime_days_in_month()

int icaltime_days_in_month	(	const int	month,
		const int	year
	)

Return the number of days in the given month

icaltime_days_in_year()

int icaltime_days_in_year

(

const int

year

)

Return the number of days in this year

icaltime_from_day_of_year()

struct icaltimetype icaltime_from_day_of_year	(	const int	_doy,
		const int	_year
	)

Contructor.

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

icaltime_from_string()

struct icaltimetype icaltime_from_string

(

const char *

str

)

Contructor.

create a time from an ISO format string

Create a time from an ISO format string.

icaltime_from_timet_with_zone()

struct icaltimetype icaltime_from_timet_with_zone	(	const time_t	tm,
		const int	is_date,
		const icaltimezone *	zone
	)

Constructor.

Convert seconds past UNIX epoch to a timetype, using timezones.

Parameters

tm	The time
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

Return a new icaltime instance, initialized to the given time expressed as seconds past UNIX epoch, 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.

icaltime_is_date()

int icaltime_is_date

(

const struct icaltimetype

t

)

Returns true if time is of DATE type, false if DATE-TIME.

Returns true if time is of DATE type, false if DATE-TIME.

icaltime_is_leap_year()

int icaltime_is_leap_year

(

const int

year

)

Return whether you've specified a leapyear or not.

icaltime_is_null_time()

int icaltime_is_null_time

(

const struct icaltimetype

t

)

Return true of the time is null.

Return true if the time is null.

icaltime_is_utc()

int icaltime_is_utc

(

const struct icaltimetype

t

)

Returns true if time is relative to UTC zone.

icaltime_is_valid_time()

int icaltime_is_valid_time

(

const struct icaltimetype

t

)

Returns false if the time is clearly invalid, but is not null. This is usually the result of creating a new time type buy not clearing it, or setting one of the flags to an illegal value.

icaltime_normalize()

struct icaltimetype icaltime_normalize

(

const struct icaltimetype

tt

)

Normalize the icaltime, so that all fields are within the normal range.

Reset all of the time components to be in their normal ranges. For instance, given a time with minutes=70, the minutes will be reduces to 10, and the hour incremented. This allows the caller to do arithmetic on times without worrying about overflow or underflow.

Implementation note: we call icaltime_adjust() with no adjustment.

icaltime_null_date()

struct icaltimetype icaltime_null_date

(

void

)

Constructor.

Return a null date

Return a null date, which indicates no time has been set.

icaltime_null_time()

struct icaltimetype icaltime_null_time

(

void

)

Constructor.

Return a null time, which indicates no time has been set. This time represent the beginning of the epoch

Return a null time, which indicates no time has been set. This time represents the beginning of the epoch.

icaltime_set_timezone()

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

Set the timezone.

Force the icaltime to be interpreted relative to another timezone. If you need to do timezone conversion, applying offset adjustments, then you should use icaltime_convert_to_zone instead.

icaltime_span_contains()

int icaltime_span_contains	(	icaltime_span *	s,
		icaltime_span *	container
	)

Returns true if the span is totally within the containing span.

Parameters

s	The span to test for.
container	The span to test against.

Returns

boolean value.

icaltime_span_new()

struct icaltime_span icaltime_span_new	(	struct icaltimetype	dtstart,
		struct icaltimetype	dtend,
		int	is_busy
	)

calculate an icaltimespan given a start and end time.

calculate an icaltimespan given a start and end time.

Parameters

dtstart	The beginning time of the span, can be a date-time or just a date.
dtend	The end time of the span.
is_busy	A boolean value, 0/1.

Returns

A span using the supplied values.

returned span contains times specified in UTC.

icaltime_span_overlaps()

int icaltime_span_overlaps	(	icaltime_span *	s1,
		icaltime_span *	s2
	)

Returns true if the two spans overlap.

Parameters

s1	1st span to test
s2	2nd span to test

Returns

boolean value

The result is calculated by testing if the start time of s1 is contained by the s2 span, or if the end time of s1 is contained by the s2 span.

Also returns true if the spans are equal.

Note, this will return false if the spans are adjacent.

icaltime_start_doy_week()

int icaltime_start_doy_week	(	const struct icaltimetype	t,
		int	fdow
	)

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

Day of the year that the first day of the week (Sunday) is on.

icaltime_today()

struct icaltimetype icaltime_today

(

void

)

Convenience constructor.

Returns the current day as an icaltimetype, with is_date set.

icaltime_week_number()

int icaltime_week_number

(

const struct icaltimetype

ictt

)

Return the week number for the week the given time is within