Libical API Documentation  3.0
Data Structures | Macros | Functions
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
dis 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
dis 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
durationThe 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
tThe 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
durThe 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
dThe 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
dThe 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
tThe time object to add the duration to
dThe 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
t1The first point in time
t2The 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);

  • ```