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

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

Detailed Description

Methods for working with durations in iCal.

Macro Definition Documentation

ICALDURATIONTYPE_INITIALIZER

#define ICALDURATIONTYPE_INITIALIZER

Value:

    {                                \
        0, 0, 0, 0, 0, 0}

Function Documentation

icalduration_extend()

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

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

icalduration_from_times()

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

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

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

Usage

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

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_seconds(3424224);
 
// print as ical-formatted string
printf("%s\n", icaldurationtype_as_ical_string(duration));

icaldurationtype_as_seconds()

int icaldurationtype_as_seconds

(

struct icaldurationtype

duration

)

Extracts the duration in integer seconds from an icaldurationtype.

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

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

icaldurationtype_as_utc_seconds()

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.

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

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

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

icaldurationtype_from_string()

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

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

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

icaldurationtype_is_null_duration()

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

icaldurationtype_normalize()

struct icaldurationtype icaldurationtype_normalize

(

struct icaldurationtype

dur

)

Create a normalized duration from another duration.

Parameters

dur	The duration of which to create a normalized copy from.

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.

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