Libical API Documentation 3.0

Data Structures | Functions
icalperiod.h File Reference

Functions for working with iCal periods (of time). More...

Go to the source code of this file.

## Data Structures
struct | icalperiodtype
| Struct to represent a period in time. More...

## Functions
const char * | icalperiodtype_as_ical_string (struct icalperiodtype p)
| Converts an icalperiodtype into an iCal-formatted string. More...
char * | icalperiodtype_as_ical_string_r (struct icalperiodtype p)
| Converts an icalperiodtype into an iCal-formatted string. More...
struct icalperiodtype | icalperiodtype_from_string (const char *str)
| Constructs a new icalperiodtype from str. More...
int | icalperiodtype_is_null_period (struct icalperiodtype p)
int | icalperiodtype_is_valid_period (struct icalperiodtype p)
struct icalperiodtype | icalperiodtype_null_period (void)

## Detailed Description

Functions for working with iCal periods (of time).

## Function Documentation

## ◆ icalperiodtype_as_ical_string()

const char * icalperiodtype_as_ical_string | ( | struct icalperiodtype | p | ) |

Converts an icalperiodtype into an iCal-formatted string.

Parameters

  p | The time period to convert

Returns
  A string representing the iCal-formatted period

See also
  icalperiodtype_as_ical_string_r()

Error handling
  Sets icalerrno to ICAL_ALLOCATION_ERROR if there was an internal error allocating memory.

Ownership
  The string returned by this method is owned by libical and must not be `free()` by the caller.

### Example

// create icalperiodtype
const char *period_string = "20170606T090000/20170607T090000";
struct icalperiodtype period = icalperiodtype_from_string(period_string);
// print period in iCal format
printf("%s\n", icalperiodtype_as_ical_string(period));
icalperiodtype_as_ical_string
const char * icalperiodtype_as_ical_string(struct icalperiodtype p)
Converts an icalperiodtype into an iCal-formatted string.
Definition: icalperiod.c:94
icalperiodtype_from_string
struct icalperiodtype icalperiodtype_from_string(const char *str)
Constructs a new icalperiodtype from str.
Definition: icalperiod.c:30
icalperiodtype
Struct to represent a period in time.
Definition: icalperiod.h:38

## ◆ icalperiodtype_as_ical_string_r()

char * icalperiodtype_as_ical_string_r | ( | struct icalperiodtype | p | ) |

Converts an icalperiodtype into an iCal-formatted string.

Parameters

  p | The time period to convert

Returns
  A string representing the iCal-formatted period

See also
  icalperiodtype_as_ical_string()

Error handling
  Sets icalerrno to ICAL_ALLOCATION_ERROR if there was an internal error allocating memory.

Ownership
  The string returned by this method is owned by the caller and must be released with the appropriate function after use.

### Example

// create icalperiodtype
const char *period_string = "20170606T090000/20170607T090000";
struct icalperiodtype period = icalperiodtype_from_string(period_string);
// print period in iCal format
const char *period_string_gen = icalperiodtype_as_ical_string_r(period);
printf("%s\n", period_string_gen);
icalmemory_free_buffer(period_string_gen);
icalmemory_free_buffer
void icalmemory_free_buffer(void *buf)
Releases a buffer.
Definition: icalmemory.c:287
icalperiodtype_as_ical_string_r
char * icalperiodtype_as_ical_string_r(struct icalperiodtype p)
Converts an icalperiodtype into an iCal-formatted string.
Definition: icalperiod.c:103

## ◆ icalperiodtype_from_string()

struct icalperiodtype icalperiodtype_from_string | ( | const char * | str | ) |

Constructs a new icalperiodtype from str.

Parameters

  str | The string from which to construct a time period

Returns
  An icalperiodtype representing the peroid str

See also
  icaltime_from_string(), icaldurationtype_from_string()

Error handling
  If str is not properly formatted, it sets icalerrno to ICAL_MALFORMEDDATA_ERROR and returns icalperiodtype_null_period().

### Data format

There are two ways to specify a duration; either a start time and an end time can be specified, or a start time and a duration. The format for there is as such:

- `<STARTTIME>/<ENDTIME>`
- `<STARTTIME>/<DURATION>`

The format for the times is the same as those used by icaltime_from_string(), and the format for the duration is the same as that used by icaldurationtype_from_string().

### Usage

// create icalperiodtype
const char *period_string = "20170606T090000/20170607T090000";
struct icalperiodtype period = icalperiodtype_from_string(period_string);
// print period in iCal format
printf("%s\n", icalperiodtype_as_ical_string(period));

## ◆ icalperiodtype_is_null_period()

int icalperiodtype_is_null_period | ( | struct icalperiodtype | p | ) |

Checks if a given icalperiodtype is a null period.

Parameters

  p | The time period to check

Returns
  1 if p is a null period, 0 otherwise

See also
  icalperiodtype_null_period()

### Usage

// creates null period
struct icalperiodtype period = icalperiodtype_null_period();
// checks if it's a null period
assert(icalperiodtype_is_null_period(period));
icalperiodtype_null_period
struct icalperiodtype icalperiodtype_null_period(void)
Definition: icalperiod.c:133
icalperiodtype_is_null_period
int icalperiodtype_is_null_period(struct icalperiodtype p)
Definition: icalperiod.c:144

## ◆ icalperiodtype_is_valid_period()

int icalperiodtype_is_valid_period | ( | struct icalperiodtype | p | ) |

Checks if a given icalperiodtype is a valid period.

Parameters

  p | The time period to check

Returns
  1 if p is a valid period, 0 otherwise

### Usage

// creates null period
struct icalperiodtype period = icalperiodtype_null_period();
// a null period isn't a valid period
assert(icalperiodtype_is_valid_period(period) == 0);
icalperiodtype_is_valid_period
int icalperiodtype_is_valid_period(struct icalperiodtype p)
Definition: icalperiod.c:154

## ◆ icalperiodtype_null_period()

struct icalperiodtype icalperiodtype_null_period | ( | void |  | ) |

Creates a null period icalperiodtype.

Returns
  An icalperiodtype representing a null period

See also
  icalperiodtype_is_null_period()

### Usage

// creates null period
struct icalperiodtype period = icalperiodtype_null_period();
// verifies start, end and length
assert(icaltime_is_null_time(period.start));
assert(icaltime_is_null_time(period.end));
assert(icaldurationtype_is_null_duratino(period.duration));
icaltime_is_null_time
int icaltime_is_null_time(const struct icaltimetype t)
Returns true if the time is null.
Definition: icaltime.c:609