icalduration.h File Reference

Methods for working with durations in iCal. More...

Go to the source code of this file.

Data Structures
struct	icaldurationtype
	A struct representing a duration. More...

Macros
#define	ICALDURATIONTYPE_INITIALIZER   { 0, 0, 0, 0, 0, 0 }

Functions
char *	icaldurationtype_as_ical_string (struct icaldurationtype d)
char *	icaldurationtype_as_ical_string_r (struct icaldurationtype d)
int	icaldurationtype_as_int (struct icaldurationtype duration)
	Converts an icaldurationtype into the duration in seconds as int. More...
struct icaldurationtype	icaldurationtype_bad_duration (void)
	Creates a bad duration (used to indicate error). More...
struct icaldurationtype	icaldurationtype_from_int (int t)
	Creates a new icaldurationtype from a duration in seconds. More...
struct icaldurationtype	icaldurationtype_from_string (const char *dur)
	Creates a new icaldurationtype from a duration given as a string. More...
int	icaldurationtype_is_bad_duration (struct icaldurationtype d)
	Checks if a duration is a bad duration. More...
int	icaldurationtype_is_null_duration (struct icaldurationtype d)
	Checks if a duration is a null duration. More...
struct icaldurationtype	icaldurationtype_null_duration (void)
	Creates a duration with zero length. More...
struct icaltimetype	icaltime_add (struct icaltimetype t, struct icaldurationtype d)
	Adds a duration to an icaltime object and returns the result. More...
struct icaldurationtype	icaltime_subtract (struct icaltimetype t1, struct icaltimetype t2)
	Returns the difference between two icaltimetype as a duration. More...

Detailed Description

Methods for working with durations in iCal.

Function Documentation

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 free() after it's no longer needed.

Usage

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

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

  // release string free(ical);

• ```

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_int(3424224);

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

• ```

int icaldurationtype_as_int

(

struct icaldurationtype

duration

)

Converts an icaldurationtype into the duration in seconds as int.

Parameters

duration

The duration to convert to seconds

Returns

An int representing the duration in seconds

Usage

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

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

• ```

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

• ```

struct icaldurationtype icaldurationtype_from_int

(

int

t

)

Creates a new icaldurationtype from a duration in seconds.

Parameters

t	The duration in seconds

Returns

An icaldurationtype representing the duration t in seconds

Example

• ```c // create a new icaldurationtype with a duration of 60 seconds struct icaldurationtype duration; duration = icaldurationtype_from_int(60);

  // verify that the duration is one minute assert(duration.minutes == 1);

• ```

struct icaldurationtype icaldurationtype_from_string

(

const char *

dur

)

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

Parameters

dur	The duration as a string

Returns

An icaldurationtype representing the duration dur

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

• ```

int icaldurationtype_is_bad_duration

(

struct icaldurationtype

d

)

Checks if a duration is a bad duration.

Parameters

d	The duration to check

Returns

1 if the duration is a bad duration, 0 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));

• ```

int icaldurationtype_is_null_duration

(

struct icaldurationtype

d

)

Checks if a duration is a null duration.

Parameters

d	The duration to check

Returns

1 if the duration is a null duration, 0 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));

• ```

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_int(duration) == 0);

• ```

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

Adds a duration to an icaltime object and returns the result.

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_int(60);

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

• ```

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

Returns the difference between two icaltimetype as a duration.

Parameters

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

Returns

An icaldurationtype representing the duration the 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 = icaltime_subtract(t1, t2);

• ```