Libical API Documentation 3.0

Data Structures | 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...

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

## ◆ icaldurationtype_as_ical_string()

char * icaldurationtype_as_ical_string | ( | struct icaldurationtype | d | ) |

Converts an icaldurationtype into the iCal format as string.

Parameters

  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_from_int
struct icaldurationtype icaldurationtype_from_int(int t)
Creates a new icaldurationtype from a duration in seconds.
Definition: icalduration.c:32
icaldurationtype_as_ical_string
char * icaldurationtype_as_ical_string(struct icaldurationtype d)
Definition: icalduration.c:211
icaldurationtype
A struct representing a duration.
Definition: icalduration.h:37

## ◆ icaldurationtype_as_ical_string_r()

char * icaldurationtype_as_ical_string_r | ( | struct icaldurationtype | d | ) |

Converts an icaldurationtype into the iCal format as string.

Parameters

  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_as_int
int icaldurationtype_as_int(struct icaldurationtype duration)
Converts an icaldurationtype into the duration in seconds as int.
Definition: icalduration.c:270

## ◆ 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_bad_duration
struct icaldurationtype icaldurationtype_bad_duration(void)
Creates a bad duration (used to indicate error).
Definition: icalduration.c:304
icaldurationtype_is_bad_duration
int icaldurationtype_is_bad_duration(struct icaldurationtype d)
Checks if a duration is a bad duration.
Definition: icalduration.c:313

## ◆ 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 returnes 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_from_string
struct icaldurationtype icaldurationtype_from_string(const char *dur)
Creates a new icaldurationtype from a duration given as a string.
Definition: icalduration.c:62

## ◆ 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.
Definition: icalduration.c:279
icaldurationtype_is_null_duration
int icaldurationtype_is_null_duration(struct icaldurationtype d)
Checks if a duration is a null duration.
Definition: icalduration.c:288

## ◆ 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_add
struct icaltimetype icaltime_add(struct icaltimetype t, struct icaldurationtype d)
Adds a duration to an ::icaltime object and returns the result.
Definition: icalduration.c:318
icaltime_today
struct icaltimetype icaltime_today(void)
Convenience constructor.
Definition: icaltime.c:226
icaltimetype
Definition: icaltime.h:105

## ◆ 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);
icaltime_subtract
struct icaldurationtype icaltime_subtract(struct icaltimetype t1, struct icaltimetype t2)
Returns the difference between two icaltimetype as a duration.
Definition: icalduration.c:339
icaltime_from_day_of_year
struct icaltimetype icaltime_from_day_of_year(const int doy, const int year)
Contructor.
Definition: icaltime.c:527