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
pThe 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));
const char * icalperiodtype_as_ical_string(struct icalperiodtype p)
Converts an icalperiodtype into an iCal-formatted string.
Definition: icalperiod.c:94
struct icalperiodtype icalperiodtype_from_string(const char *str)
Constructs a new icalperiodtype from str.
Definition: icalperiod.c:30
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
pThe 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);
void icalmemory_free_buffer(void *buf)
Releases a buffer.
Definition: icalmemory.c:287
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
strThe 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
pThe time period to check
Returns
1 if p is a null period, 0 otherwise
See also
icalperiodtype_null_period()

Usage

// creates null period
// checks if it's a null period
struct icalperiodtype icalperiodtype_null_period(void)
Definition: icalperiod.c:133
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
pThe time period to check
Returns
1 if p is a valid period, 0 otherwise

Usage

// creates null period
// a null period isn't a valid period
assert(icalperiodtype_is_valid_period(period) == 0);
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
// 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));
int icaltime_is_null_time(const struct icaltimetype t)
Returns true if the time is null.
Definition: icaltime.c:609