icalduration.h File Reference

Defines the data structure for time durations. More...

Go to the source code of this file.

Data Structures
struct	icaldurationtype

Functions
struct icaltimetype	icalduration_extend (struct icaltimetype t, struct icaldurationtype d)
	Extends a time duration. More...
struct icaldurationtype	icalduration_from_times (struct icaltimetype t1, struct icaltimetype t2)
	Creates a duration from two icaltimetype endpoints. More...
char *	icaldurationtype_as_ical_string (struct icaldurationtype d)
char *	icaldurationtype_as_ical_string_r (struct icaldurationtype d)
int	icaldurationtype_as_seconds (struct icaldurationtype duration)
	Extracts the duration in integer seconds from an icaldurationtype. More...
int	icaldurationtype_as_utc_seconds (struct icaldurationtype duration)
	Extracts the duration in integer seconds from an icaldurationtype in UTC time. More...
struct icaldurationtype	icaldurationtype_bad_duration (void)
	Creates a bad duration (used to indicate error). More...
struct icaldurationtype	icaldurationtype_from_seconds (int seconds)
	Creates a new icaldurationtype from a duration in seconds. More...
struct icaldurationtype	icaldurationtype_from_string (const char *str)
	Creates a new icaldurationtype from a duration given as a string. More...
bool	icaldurationtype_is_bad_duration (struct icaldurationtype d)
	Checks if a duration is a bad duration. More...
bool	icaldurationtype_is_null_duration (struct icaldurationtype d)
	Checks if a duration is a null duration. More...
struct icaldurationtype	icaldurationtype_normalize (struct icaldurationtype dur)
	Create a normalized duration from another duration. More...
struct icaldurationtype	icaldurationtype_null_duration (void)
	Creates a duration with zero length. More...

Detailed Description

Defines the data structure for time durations.

Definition in file icalduration.h.

Function Documentation

struct icaltimetype icalduration_extend	(	struct icaltimetype	t,
		struct icaldurationtype	d
	)

Extends a time duration.

Parameters

t	The time object to add the duration to
d	The duration to add to the time object

Returns

The new icaltimetype which has been added the duration to

Example

• ```c struct icaltimetype time; struct icaldurationtype duration;

  // create time and duration objects time = icaltime_today(); duration = icaldurationtype_from_seconds(60);

  // add the duration to the time object time = icalduration_extend(time, duration);

• ```

Since

4.0 previously known as icaltime_add

Definition at line 297 of file icalduration.c.

struct icaldurationtype icalduration_from_times	(	struct icaltimetype	t1,
		struct icaltimetype	t2
	)

Creates a duration from two icaltimetype endpoints.

Parameters

t1	The first point in time
t2	The second point in time

Returns

An icaldurationtype representing the duration elapsed between t1 and t2

Usage

• ```c struct icaltimetype t1 = icaltime_from_day_of_year(111, 2018); struct icaltimetype t2 = icaltime_from_day_of_year(112, 2018); struct icaldurationtype duration;

  // calculate duration between time points duration = icalduration_from_times(t1, t2);

• ```

Since

4.0 previously known as icaltime_subtract

Definition at line 346 of file icalduration.c.

char* icaldurationtype_as_ical_string

(

struct icaldurationtype

d

)

Converts an icaldurationtype into the iCal format as string.

Parameters

d	is the icaldurationtype to convert to iCal format

Returns

A string representing duration d in iCal format

See also

icaldurationtype_as_ical_string_r()

Ownership

The string returned by this function is owned by the caller and needs to be released with icalmemory_free_buffer() after it's no longer needed.

Usage

• ```c // create new duration struct icaldurationtype duration; duration = icaldurationtype_from_seconds(3424224);

  // print as ical-formatted string char *ical = icaldurationtype_as_ical_string(duration); printf("%s\n", ical);

  // release string icalmemory_free_buffer(ical);

• ```

Definition at line 181 of file icalduration.c.

char* icaldurationtype_as_ical_string_r

(

struct icaldurationtype

d

)

Converts an icaldurationtype into the iCal format as string.

Parameters

d	is the icaldurationtype to convert to iCal format

Returns

A string representing duration d in iCal format

See also

icaldurationtype_as_ical_string()

Ownership

The string returned by this function is owned by libical and must not be released by the caller of the function.

Usage

• ```c // create new duration struct icaldurationtype duration; duration = icaldurationtype_from_seconds(3424224);

  // print as ical-formatted string printf("%s\n", icaldurationtype_as_ical_string(duration));

• ```

Definition at line 190 of file icalduration.c.

int icaldurationtype_as_seconds

(

struct icaldurationtype

duration

)

Extracts the duration in integer seconds from an icaldurationtype.

Does not consider negative durations. Does not support days and weeks.

Parameters

duration

A valid duration type.

Returns

An int representing the number of seconds in the duration.

The number of seconds returned from the specified icaldurationtype can be a positive or negative integer depending if the duration points forward or backward in time.

Additionally, a icaldurationtype that has a non-zero days or weeks value is considered an error. ie. only the icaldurationtype seconds, minutes and hours structure members are converted. Also

See also

icaldurationtype_as_utc_seconds.

Usage

• ```c // create icaldurationtype with given duration struct icaldurationtype duration; duration = icaldurationtype_from_seconds(3532342);

  // get the duration in seconds and verify it assert(icaldurationtype_as_seconds(duration) == 3532342);

• ```

Since

4.0 previously known as icaldurationtype_as_int

Definition at line 238 of file icalduration.c.

int icaldurationtype_as_utc_seconds

(

struct icaldurationtype

duration

)

Extracts the duration in integer seconds from an icaldurationtype in UTC time.

Parameters

duration

A valid duration type.

Returns

An int representing the number of seconds in the duration.

The number of seconds returned from the specified icaldurationtype can be a positive or negative integer depending if the duration points forward or backward in time.

Days are fixed to have 24 hours.

Definition at line 251 of file icalduration.c.

struct icaldurationtype icaldurationtype_bad_duration

(

void

)

Creates a bad duration (used to indicate error).

Returns

A bad duration

See also

icaldurationtype_is_bad_duration()

Usage

• ```c // create bad duration struct icaldurationtype duration; duration = icaldurationtype_bad_duration();

  // make sure it's bad assert(icaldurationtype_is_bad_duration(duration));

• ```

Definition at line 283 of file icalduration.c.

struct icaldurationtype icaldurationtype_from_seconds

(

int

seconds

)

Creates a new icaldurationtype from a duration in seconds.

Parameters

seconds

The duration in seconds

Returns

An icaldurationtype representing the duration t in seconds

The number of seconds stored in the icaldurationtype structure is always a positive integer. If the seconds argument is negative, then the is_neg structure member is set to 1 (true).

Also note that the number of seconds is not in any way refactored into days, hours, or minutes. This function simply assigns the icaldurationtype seconds structure member from the integer provided.

Example

• ```c // create a new icaldurationtype with a duration of 60 seconds struct icaldurationtype duration; duration = icaldurationtype_from_seconds(60); // create a new icaldurationtype with a duration of 60 seconds pointing back in time duration = icaldurationtype_from_seconds(-60);
• ```

Since

4.0 previously known as icaldurationtype_from_int

Definition at line 28 of file icalduration.c.

struct icaldurationtype icaldurationtype_from_string

(

const char *

str

)

Creates a new icaldurationtype from a duration given as a string.

Parameters

str	The duration as a string

Returns

An icaldurationtype representing the duration str

Error handling

When given bad input, it sets icalerrno to ICAL_MALFORMEDDATA_ERROR and returns icaldurationtype_bad_duration().

Usage

• ```c // create a new icaldurationtype struct icaldurationtype duration; duration = icaldurationtype_from_string("+PT05M");

  // verify that it's 5 minutes assert(duration.minutes == 5);

• ```

Definition at line 43 of file icalduration.c.

bool icaldurationtype_is_bad_duration

(

struct icaldurationtype

d

)

Checks if a duration is a bad duration.

Parameters

d	The duration to check

Returns

true if the duration is a bad duration, false otherwise

See also

icalduration_bad_duration()

Usage

• ``` // make bad duration struct icaldurationtype duration; duration = icaldurationtype_bad_duration();

  // check bad duration assert(icaldurationtype_is_bad_duration(duration));

• ```

Definition at line 292 of file icalduration.c.

bool icaldurationtype_is_null_duration

(

struct icaldurationtype

d

)

Checks if a duration is a null duration.

Parameters

d	The duration to check

Returns

true if the duration is a null duration, false otherwise

See also

icalduration_null_duration()

Usage

• ``` // make null duration struct icaldurationtype duration; duration = icaldurationtype_null_duration();

  // check null duration assert(icaldurationtype_is_null_duration(duration));

• ```

Definition at line 270 of file icalduration.c.

struct icaldurationtype icaldurationtype_normalize

(

struct icaldurationtype

dur

)

Create a normalized duration from another duration.

Extracts the duration in seconds from an icalduration a continuous timeline with 24-hour days. Supports days, weeks, and negative durations.

Parameters

dur	The duration from which to create a normalized duration.

Returns

An icaldurationtype representing the normalized duration.

A duration is normalized such that:

• Minutes and seconds are in the inclusive range [0;59], but hours may exceed 23 hours.
• Only weeks or days are set, and weeks only are set if no hours, minutes and seconds are set.

Definition at line 369 of file icalduration.c.

struct icaldurationtype icaldurationtype_null_duration

(

void

)

Creates a duration with zero length.

Returns

An icaldurationtype with a zero length

See also

icaldurationtype_is_null_duration()

Usage

• ```c // create null duration struct icaldurationtype duration; duration = icaldurationtype_null_duration();

  // make sure it's zero length assert(duration.days == 0); assert(duration.weeks == 0); assert(duration.hours == 0); assert(duration.minutes == 0); assert(duration.seconds == 0); assert(icalduration_is_null_duration(duration)); assert(icalduration_as_seconds(duration) == 0);

• ```

Definition at line 261 of file icalduration.c.