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.
struct icaldurationtype	icaldurationtype_bad_duration (void)
	Creates a bad duration (used to indicate error).
struct icaldurationtype	icaldurationtype_from_int (int t)
	Creates a new icaldurationtype from a duration in seconds.
struct icaldurationtype	icaldurationtype_from_string (const char *dur)
	Creates a new icaldurationtype from a duration given as a string.
int	icaldurationtype_is_bad_duration (struct icaldurationtype d)
	Checks if a duration is a bad duration.
int	icaldurationtype_is_null_duration (struct icaldurationtype d)
	Checks if a duration is a null duration.
struct icaldurationtype	icaldurationtype_null_duration (void)
	Creates a duration with zero length.
struct icaltimetype	icaltime_add (struct icaltimetype t, struct icaldurationtype d)
	Adds a duration to an icaltime object and returns the result.
struct icaldurationtype	icaltime_subtract (struct icaltimetype t1, struct icaltimetype t2)
	Returns the difference between two icaltimetype as a duration.

Detailed Description

Methods for working with durations in iCal.

Function Documentation

icaldurationtype_as_ical_string()

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

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

icaldurationtype_as_ical_string_r()

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

// create new duration
struct icaldurationtype duration;
duration = icaldurationtype_from_int(3424224);
 
// print as ical-formatted string
printf("%s\n", icaldurationtype_as_ical_string(duration));

icaldurationtype_as_int()

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

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

icaldurationtype_bad_duration()

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

// create bad duration
struct icaldurationtype duration;
duration = icaldurationtype_bad_duration();
 
// make sure it's bad
assert(icaldurationtype_is_bad_duration(duration));

icaldurationtype_from_int()

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

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

icaldurationtype_from_string()

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

// create a new icaldurationtype
struct icaldurationtype duration;
duration = icaldurationtype_from_string("+PT05M");
 
// verify that it's 5 minutes
assert(duration.minutes == 5);

icaldurationtype_is_bad_duration()

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

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

icaldurationtype_null_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

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

icaltime_add()

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

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

icaltime_subtract()

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

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