/usr/include/libical/icalperiod.h is in libical-dev 3.0.1-5.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 | /*======================================================================
FILE: icalperiod.h
CREATOR: eric 26 Jan 2001
(C) COPYRIGHT 2000, Eric Busboom <eric@softwarestudio.org>
http://www.softwarestudio.org
This library is free software; you can redistribute it and/or modify
it under the terms of either:
The LGPL as published by the Free Software Foundation, version
2.1, available at: http://www.gnu.org/licenses/lgpl-2.1.html
Or:
The Mozilla Public License Version 2.0. You may obtain a copy of
the License at http://www.mozilla.org/MPL/
The Original Code is eric. The Initial Developer of the Original
Code is Eric Busboom
======================================================================*/
#ifndef ICALPERIOD_H
#define ICALPERIOD_H
/**
* @file icalperiod.h
* @brief Functions for working with iCal periods (of time).
*/
#include "libical_ical_export.h"
#include "icalduration.h"
#include "icaltime.h"
/**
* @brief Struct to represent a period in time.
*/
struct icalperiodtype
{
struct icaltimetype start;
struct icaltimetype end;
struct icaldurationtype duration;
};
/**
* @brief Constructs a new ::icalperiodtype from @a str
* @param str The string from which to construct a time period
* @return An ::icalperiodtype representing the peroid @a str
* @sa icaltime_from_string(), icaldurationtype_from_string()
*
* @par Error handling
* If @a 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
* ```c
* // 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));
* ```
*/
LIBICAL_ICAL_EXPORT struct icalperiodtype icalperiodtype_from_string(const char *str);
/**
* @brief Converts an ::icalperiodtype into an iCal-formatted string.
* @param p The time period to convert
* @return A string representing the iCal-formatted period
* @sa icalperiodtype_as_ical_string_r()
*
* @par Error handling
* Sets ::icalerrno to ::ICAL_ALLOCATION_ERROR if there was an
* internal error allocating memory.
*
* @par Ownership
* The string returned by this method is owned by libical and must not be
* `free()` by the caller.
*
* ### Example
* ```c
* // 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));
* ```
*/
LIBICAL_ICAL_EXPORT const char *icalperiodtype_as_ical_string(struct icalperiodtype p);
/**
* @brief Converts an ::icalperiodtype into an iCal-formatted string.
* @param p The time period to convert
* @return A string representing the iCal-formatted period
* @sa icalperiodtype_as_ical_string()
*
* @par Error handling
* Sets ::icalerrno to ::ICAL_ALLOCATION_ERROR if there was an
* internal error allocating memory.
*
* @par Ownership
* The string returned by this method is owned by the caller and must be
* released with the appropriate function after use.
*
* ### Example
* ```c
* // 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);
* ```
*/
LIBICAL_ICAL_EXPORT char *icalperiodtype_as_ical_string_r(struct icalperiodtype p);
/**
* @begin Creates a null period ::icalperiodtype.
* @return An ::icalperiodtype representing a null period
* @sa icalperiodtype_is_null_period()
*
* ### Usage
* ```c
* // 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));
* ```
*/
LIBICAL_ICAL_EXPORT struct icalperiodtype icalperiodtype_null_period(void);
/**
* @begin Checks if a given ::icalperiodtype is a null period.
* @return 1 if @a p is a null period, 0 otherwise
* @sa icalperiodtype_null_period()
*
* ### Usage
* ```c
* // creates null period
* struct icalperiodtype period = icalperiodtype_null_period();
*
* // checks if it's a null period
* assert(icalperiodtype_is_null_period(period));
* ```
*/
LIBICAL_ICAL_EXPORT int icalperiodtype_is_null_period(struct icalperiodtype p);
/**
* @begin Checks if a given ::icalperiodtype is a valid period.
* @return 1 if @a p is a valid period, 0 otherwise
*
* ### Usage
* ```c
* // creates null period
* struct icalperiodtype period = icalperiodtype_null_period();
*
* // a null period isn't a valid period
* assert(icalperiodtype_is_valid_period(period) == 0);
* ```
*/
LIBICAL_ICAL_EXPORT int icalperiodtype_is_valid_period(struct icalperiodtype p);
#endif /* !ICALTIME_H */
|