Libical API Documentation 3.0
Loading...
Searching...
No Matches
Data Structures | Macros | Typedefs | Functions
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
 

Macros

#define ICALTIMETYPE_INITIALIZER   { 0, 0, 0, 0, 0, 0, 0, 0, 0}
 
#define ICALTIMEZONE_DEFINED
 

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.
 
const char * icaltime_as_ical_string (const struct icaltimetype tt)
 Returns a string representation of the time, in RFC5545 format.
 
char * icaltime_as_ical_string_r (const struct icaltimetype tt)
 Returns a string representation of the time, in RFC5545 format.
 
time_t icaltime_as_timet (const struct icaltimetype)
 
time_t icaltime_as_timet_with_zone (const struct icaltimetype tt, const icaltimezone *zone)
 Returns the time as seconds past the UNIX epoch, using the given timezone.
 
int icaltime_compare (const struct icaltimetype a, const struct icaltimetype b)
 Returns -1, 0, or 1 to indicate that a is less than b, a equals b, or a is greater than b.
 
int icaltime_compare_date_only (const struct icaltimetype a, const struct icaltimetype b)
 Like icaltime_compare, but only use the date parts.
 
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.
 
struct icaltimetype icaltime_convert_to_zone (const struct icaltimetype tt, icaltimezone *zone)
 Converts time to a given timezone.
 
struct icaltimetype icaltime_current_time_with_zone (const icaltimezone *zone)
 Convenience constructor.
 
int icaltime_day_of_week (const struct icaltimetype t)
 Returns the day of the week of the given time.
 
int icaltime_day_of_year (const struct icaltimetype t)
 Returns the day of the year, counting from 1 (Jan 1st).
 
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)
 Constructor.
 
struct icaltimetype icaltime_from_string (const char *str)
 Constructor.
 
struct icaltimetype icaltime_from_timet_with_zone (const time_t tm, const int is_date, const icaltimezone *zone)
 Constructor.
 
const icaltimezoneicaltime_get_timezone (const struct icaltimetype t)
 Returns the timezone.
 
const char * icaltime_get_tzid (const struct icaltimetype t)
 Returns the tzid, or NULL for a floating time.
 
int icaltime_is_date (const struct icaltimetype t)
 Returns true if time is a DATE.
 
int icaltime_is_leap_year (const int year)
 Returns whether the specified year is a leap year.
 
int icaltime_is_null_time (const struct icaltimetype t)
 Returns true if the time is null.
 
int icaltime_is_utc (const struct icaltimetype t)
 Returns true if the time is relative to UTC zone.
 
int icaltime_is_valid_time (const struct icaltimetype t)
 Returns false if the time is clearly invalid, but is not null.
 
struct icaltimetype icaltime_normalize (const struct icaltimetype tt)
 Normalizes the icaltime, so all of the time components are in their normal ranges.
 
struct icaltimetype icaltime_null_date (void)
 Constructor.
 
struct icaltimetype icaltime_null_time (void)
 Constructor.
 
struct icaltimetype icaltime_set_timezone (struct icaltimetype *t, const icaltimezone *zone)
 Sets the timezone.
 
int icaltime_span_contains (icaltime_span *s, icaltime_span *container)
 Returns true if the span is totally within the containing span.
 
struct icaltime_span icaltime_span_new (struct icaltimetype dtstart, struct icaltimetype dtend, int is_busy)
 Builds an icaltimespan given a start time, end time and busy value.
 
int icaltime_span_overlaps (icaltime_span *s1, icaltime_span *s2)
 Returns true if the two spans overlap.
 
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.
 
struct icaltimetype icaltime_today (void)
 Convenience constructor.
 
int icaltime_week_number (const struct icaltimetype t)
 Returns the week number for the week the given time is within.
 

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:

italtimetype objects can be converted to different formats:

Accessor methods include:

Query methods include:

Modify, compare and utility methods include:

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. This time is given as a number of days, hours, minutes and seconds.

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)

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

Ownership
The created string is owned by libical.

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

Ownership
The string is owned by the caller.

◆ icaltime_as_timet()

time_t icaltime_as_timet ( const struct icaltimetype  tt)

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

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.

◆ icaltime_as_timet_with_zone()

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

Returns 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,
const struct icaltimetype  b 
)

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

This converts both times to the UTC timezone and compares them.

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

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

◆ icaltime_convert_to_zone()

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

Converts time to a given timezone.

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

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.

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

Returns the day of the week of the given time.

Sunday is 1, and Saturday is 7.

◆ icaltime_days_in_month()

int icaltime_days_in_month ( const int  month,
const int  year 
)

Returns the number of days in the given month.

◆ icaltime_days_in_year()

int icaltime_days_in_year ( const int  year)

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

Constructor.

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

Note that Jan 1 is day #1, not 0.

◆ icaltime_from_string()

struct icaltimetype icaltime_from_string ( const char *  str)

Constructor.

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

Parameters
tmThe time expressed as seconds past UNIX epoch
is_dateBoolean: 1 means we should treat tm as a DATE
zoneThe 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.

◆ icaltime_is_date()

int icaltime_is_date ( const struct icaltimetype  t)

Returns true if time is a DATE.

The options are DATE type, which returns true, or DATE-TIME, which returns false.

◆ icaltime_is_leap_year()

int icaltime_is_leap_year ( const int  year)

Returns whether the specified year is a leap year.

Year is the normal year, e.g. 2001.

◆ icaltime_is_utc()

int icaltime_is_utc ( const struct icaltimetype  t)

Returns true if the 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 but not clearing it, or setting one of the flags to an illegal value.

◆ icaltime_normalize()

struct icaltimetype icaltime_normalize ( const struct icaltimetype  tt)

Normalizes the icaltime, so all of the time components are 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.

◆ icaltime_null_date()

struct icaltimetype icaltime_null_date ( void  )

Constructor.

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

◆ icaltime_null_time()

struct icaltimetype icaltime_null_time ( void  )

Constructor.

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

Sets the timezone.

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.

◆ 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
sThe span to test for.
containerThe 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 
)

Builds an icaltimespan given a start time, end time and busy value.

Parameters
dtstartThe beginning time of the span, can be a date-time or just a date.
dtendThe end time of the span.
is_busyA boolean value, 0/1.
Returns
A span using the supplied values. The times are specified in UTC.

◆ icaltime_span_overlaps()

int icaltime_span_overlaps ( icaltime_span s1,
icaltime_span s2 
)

Returns true if the two spans overlap.

Parameters
s1First span to test
s2Second 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 
)

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

Returns the day of the year for the first day of the week .

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.

◆ 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  t)

Returns the week number for the week the given time is within.