Documentation and annotation updates
This commit updates the Doxygen documentation (particularly taking into account a request from Kelly Dunlop for more verbose notice about which members are changed by iso8601_from_*()) and file/function annotation/formatting to current standards.
This commit is contained in:
parent
e504a722f5
commit
6285d214aa
|
|
@ -1,7 +1,7 @@
|
|||
/* libiso8601/src/libiso8601/100_types.h
|
||||
*
|
||||
* (c)2006, Laurence Withers, <l@lwithers.me.uk>.
|
||||
* Released under the GNU GPLv2. See file COPYING or
|
||||
* (c)2006-2010, Laurence Withers, <l@lwithers.me.uk>.
|
||||
* Released under the GNU GPLv3. See file COPYING or
|
||||
* http://www.gnu.org/copyleft/gpl.html for details.
|
||||
*/
|
||||
|
||||
|
|
@ -9,19 +9,20 @@
|
|||
|
||||
/*! \brief Date/time point.
|
||||
|
||||
This structure contains the details to represent a specific instant on the UTC timescale. It uses
|
||||
Jan 1, year 0000 as the origin (when \a day will be 0). \a sec is the number of seconds elapsed
|
||||
since start of day, and \a nsec is the number of nanoseconds elapsed since the start of the current
|
||||
second.
|
||||
This structure contains the details to represent a specific instant on the UTC
|
||||
timescale. It uses Jan 1, year 0000 as the origin (when \a day will be 0). \a
|
||||
sec is the number of seconds elapsed since start of day, and \a nsec is the
|
||||
number of nanoseconds elapsed since the start of the current second.
|
||||
|
||||
We correctly deal with leap seconds by encoding 23:59:60 as having a \a sec field of 86400.
|
||||
We correctly deal with leap seconds by encoding 23:59:60 as having a \a sec
|
||||
field of 86400.
|
||||
|
||||
*/
|
||||
struct iso8601_date {
|
||||
/*! \brief Number of nanoseconds elapsed since start of second. */
|
||||
int32_t nsec;
|
||||
|
||||
/*! \brief Number of days elapsed since Jan 1, year 0000. May be negative. */
|
||||
/*! \brief Number of days elapsed since Jan 1, year 0000. May be negative.*/
|
||||
int32_t day;
|
||||
|
||||
/*! \brief Number of seconds elapsed since start of day. */
|
||||
|
|
@ -33,9 +34,10 @@ struct iso8601_date {
|
|||
/*! \brief Date (day portion) precision.
|
||||
\ingroup parser
|
||||
|
||||
This enumeration will record how precisely the date was specified, as well as the format in use. It
|
||||
allows the library to determine the earliest and latest dates that could possibly be represented
|
||||
with the given input and also allows the output format to match the input format.
|
||||
This enumeration will record how precisely the date was specified, as well as
|
||||
the format in use. It allows the library to determine the earliest and latest
|
||||
dates that could possibly be represented with the given input and also allows
|
||||
the output format to match the input format.
|
||||
|
||||
*/
|
||||
enum iso8601_date_prec {
|
||||
|
|
@ -63,9 +65,10 @@ enum iso8601_date_prec {
|
|||
/*! \brief Time precision.
|
||||
\ingroup parser
|
||||
|
||||
This enumeration records how precisely the time was specified as well as its format. The fractional
|
||||
format will record whether it was the hour, minute or second that was specified with a fractional
|
||||
part, allowing a processed date/time to be presented to the user in the format it was originally
|
||||
This enumeration records how precisely the time was specified as well as its
|
||||
format. The fractional format will record whether it was the hour, minute or
|
||||
second that was specified with a fractional part, allowing a processed
|
||||
date/time to be presented to the user in the format it was originally
|
||||
encountered.
|
||||
|
||||
*/
|
||||
|
|
@ -90,10 +93,10 @@ enum iso8601_time_prec {
|
|||
|
||||
/*! \brief Date/time formatting details.
|
||||
|
||||
This structure simply records details related to the formatting (and precision) of a date/time
|
||||
structure. The structure can be filled out by the parser so that a program's output can match
|
||||
the format of its input. Alternatively it can be controlled by the program to provide a consistent
|
||||
output format.
|
||||
This structure simply records details related to the formatting (and precision)
|
||||
of a date/time structure. The structure can be filled out by the parser so that
|
||||
a program's output can match the format of its input. Alternatively it can be
|
||||
controlled by the program to provide a consistent output format.
|
||||
|
||||
*/
|
||||
struct iso8601_details {
|
||||
|
|
@ -114,9 +117,10 @@ struct iso8601_details {
|
|||
|
||||
/*! \brief Short period elapsed time.
|
||||
|
||||
This structure contains the details of an elapsed time period, split into seconds and nanoseconds.
|
||||
None of its components can ever be negative. This is only capable of representing short (compared to
|
||||
struct iso8601_date's range) periods of up to approximately 136 years.
|
||||
This structure contains the details of an elapsed time period, split into
|
||||
seconds and nanoseconds. None of its components can ever be negative. This is
|
||||
only capable of representing short (compared to struct iso8601_date's range)
|
||||
periods of up to approximately 136 years.
|
||||
|
||||
*/
|
||||
struct iso8601_elapsed {
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
/* libiso8601/src/libiso8601/200_parser.h
|
||||
*
|
||||
* (c)2006, Laurence Withers, <l@lwithers.me.uk>.
|
||||
* Released under the GNU GPLv2. See file COPYING or
|
||||
* (c)2006-2010, Laurence Withers, <l@lwithers.me.uk>.
|
||||
* Released under the GNU GPLv3. See file COPYING or
|
||||
* http://www.gnu.org/copyleft/gpl.html for details.
|
||||
*/
|
||||
|
||||
|
|
@ -9,31 +9,41 @@
|
|||
|
||||
/*! \defgroup parser Parsing, printing and validation routines.
|
||||
|
||||
These routines are used for parsing an ISO8601 date/time string into the internal structure used
|
||||
to represent them, and for validating such dates/times.
|
||||
These routines are used for parsing an ISO8601 date/time string into the
|
||||
internal structure used to represent them, and for validating such dates/times.
|
||||
|
||||
*/
|
||||
/*!@{*/
|
||||
|
||||
|
||||
|
||||
/*! \brief Parse ISO8601 date/time.
|
||||
|
||||
\param str The input string. Whitespace will be stripped.
|
||||
\param[out] earliest The earliest possible time the string could represent. May be 0.
|
||||
\param[out] latest The latest possible time the string could represent. May be 0.
|
||||
\param[out] details Stores details such as the precision to which the time/date were specified. May
|
||||
\param[out] earliest The earliest possible time the string could represent. May
|
||||
be 0.
|
||||
\param[out] latest The latest possible time the string could represent. May be
|
||||
0.
|
||||
\param[out] details Stores details such as the precision to which the time/date
|
||||
were specified. May be 0.
|
||||
\retval -1 on error.
|
||||
\retval 0 on success.
|
||||
|
||||
Parses a string containing the ISO8601 date/time. Deals with any format of date, optionally storing
|
||||
the details in \a details. The time may be partial, in which case this function returns the earliest
|
||||
and latest times that could possibly be represented by the string.
|
||||
Parses a string containing the ISO8601 date/time. Deals with any format of
|
||||
date, optionally storing the details in \a details. The time may be partial, in
|
||||
which case this function returns the earliest and latest times that could
|
||||
possibly be represented by the string.
|
||||
|
||||
Note that this function will accept leap seconds (23:59:60) on days on which they occurred.
|
||||
Note that this function will accept leap seconds (23:59:60) on days on which
|
||||
they occurred.
|
||||
|
||||
*/
|
||||
int iso8601_parse(const char* str, struct iso8601_date* earliest, struct iso8601_date* latest,
|
||||
struct iso8601_details* details);
|
||||
int iso8601_parse(const char* str, struct iso8601_date* earliest,
|
||||
struct iso8601_date* latest, struct iso8601_details* details)
|
||||
#ifndef DOXYGEN
|
||||
__attribute__((nonnull(1),warn_unused_result))
|
||||
#endif
|
||||
;
|
||||
|
||||
|
||||
|
||||
|
|
@ -45,12 +55,17 @@ int iso8601_parse(const char* str, struct iso8601_date* earliest, struct iso8601
|
|||
\param details Formatting details (may be 0).
|
||||
\returns Pointer to buffer (\a str).
|
||||
|
||||
Formats and prints an ISO8601 date, optionally using the details in \a details. Will always return
|
||||
a null-terminated result, even if that means truncating the output to fit the buffer.
|
||||
Formats and prints an ISO8601 date, optionally using the details in \a details.
|
||||
Will always return a null-terminated result, even if that means truncating the
|
||||
output to fit the buffer.
|
||||
|
||||
*/
|
||||
char* iso8601_print(char* str, int amt, const struct iso8601_date* date,
|
||||
const struct iso8601_details* details);
|
||||
const struct iso8601_details* details)
|
||||
#ifndef DOXYGEN
|
||||
__attribute__((nonnull(1,3)))
|
||||
#endif
|
||||
;
|
||||
|
||||
|
||||
|
||||
|
|
@ -60,18 +75,21 @@ char* iso8601_print(char* str, int amt, const struct iso8601_date* date,
|
|||
\retval -1 if not valid.
|
||||
\retval 0 if valid.
|
||||
|
||||
Checks the details of \a date to ensure that they are sensible. This involves checking that \a sec
|
||||
is in the range 0 to 86399 (or 86400 if there is a leap second), and that \a nsec is in the range 0
|
||||
to 999999999.
|
||||
Checks the details of \a date to ensure that they are sensible. This involves
|
||||
checking that \a sec is in the range 0 to 86399 (or 86400 if there is a leap
|
||||
second), and that \a nsec is in the range 0 to 999999999.
|
||||
|
||||
*/
|
||||
int iso8601_invalid(const struct iso8601_date* date);
|
||||
int iso8601_invalid(const struct iso8601_date* date)
|
||||
#ifndef DOXYGEN
|
||||
__attribute__((nonnull))
|
||||
#endif
|
||||
;
|
||||
|
||||
|
||||
|
||||
/*!@}*/
|
||||
|
||||
/* options for text editors
|
||||
kate: replace-trailing-space-save true; space-indent true; tab-width 4;
|
||||
vim: expandtab:ts=4:sw=4
|
||||
vim: expandtab:ts=4:sw=4:syntax=ch.doxygen
|
||||
*/
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
/* libiso8601/src/libiso8601/400_c_library.h
|
||||
*
|
||||
* (c)2006, Laurence Withers, <l@lwithers.me.uk>.
|
||||
* Released under the GNU GPLv2. See file COPYING or
|
||||
* (c)2006-2010, Laurence Withers, <l@lwithers.me.uk>.
|
||||
* Released under the GNU GPLv3. See file COPYING or
|
||||
* http://www.gnu.org/copyleft/gpl.html for details.
|
||||
*/
|
||||
|
||||
|
|
@ -9,7 +9,8 @@
|
|||
|
||||
/*! \defgroup c_library C library integration.
|
||||
|
||||
These functions enable integration with the C library (system call wrappers and conversion).
|
||||
These functions enable integration with the C library (system call wrappers and
|
||||
conversion).
|
||||
|
||||
*/
|
||||
/*!@{*/
|
||||
|
|
@ -21,8 +22,8 @@ These functions enable integration with the C library (system call wrappers and
|
|||
\param[out] date Current date/time (may be 0), in UTC.
|
||||
\param[out] details Details (may be 0), including timezone.
|
||||
|
||||
Retrieves the current time from the system clock, storing it into \a date and \a details (both
|
||||
parameters optional).
|
||||
Retrieves the current time from the system clock, storing it into \a date and
|
||||
\a details (both parameters optional).
|
||||
|
||||
*/
|
||||
void iso8601_now(struct iso8601_date* date, struct iso8601_details* details);
|
||||
|
|
@ -35,32 +36,65 @@ void iso8601_now(struct iso8601_date* date, struct iso8601_details* details);
|
|||
\retval 0 on success.
|
||||
\retval -1 on error (and see \a errno).
|
||||
|
||||
Attempts to set the system clock using \c clock_settime(), falling back to \c settimeofday(). The
|
||||
user will need the \c CAP_SYS_TIME capability to set the clock, otherwise \a errno will be set to
|
||||
\c EPERM.
|
||||
Attempts to set the system clock using \c clock_settime(), falling back to \c
|
||||
settimeofday(). The user will need the \c CAP_SYS_TIME capability to set the
|
||||
clock, otherwise \a errno will be set to \c EPERM.
|
||||
|
||||
*/
|
||||
int iso8601_set_sysclock(const struct iso8601_date* date);
|
||||
int iso8601_set_sysclock(const struct iso8601_date* date)
|
||||
#ifndef DOXYGEN
|
||||
__attribute__((nonnull))
|
||||
#endif
|
||||
;
|
||||
|
||||
|
||||
|
||||
/*! \brief Convert from a struct timespec. */
|
||||
void iso8601_from_ts(struct iso8601_date* date, const struct timespec* ts);
|
||||
void iso8601_from_ts(struct iso8601_date* date, const struct timespec* ts)
|
||||
#ifndef DOXYGEN
|
||||
__attribute__((nonnull))
|
||||
#endif
|
||||
;
|
||||
|
||||
/*! \brief Convert to a struct timespec. */
|
||||
void iso8601_to_ts(struct timespec* ts, const struct iso8601_date* date);
|
||||
void iso8601_to_ts(struct timespec* ts, const struct iso8601_date* date)
|
||||
#ifndef DOXYGEN
|
||||
__attribute__((nonnull))
|
||||
#endif
|
||||
;
|
||||
|
||||
/*! \brief Convert from a struct timeval. */
|
||||
void iso8601_from_tv(struct iso8601_date* date, const struct timeval* tv);
|
||||
void iso8601_from_tv(struct iso8601_date* date, const struct timeval* tv)
|
||||
#ifndef DOXYGEN
|
||||
__attribute__((nonnull))
|
||||
#endif
|
||||
;
|
||||
|
||||
/*! \brief Convert to a struct timeval. */
|
||||
void iso8601_to_tv(struct timeval* tv, const struct iso8601_date* date);
|
||||
void iso8601_to_tv(struct timeval* tv, const struct iso8601_date* date)
|
||||
#ifndef DOXYGEN
|
||||
__attribute__((nonnull))
|
||||
#endif
|
||||
;
|
||||
|
||||
/*! \brief Convert from a time_t. */
|
||||
void iso8601_from_time_t(struct iso8601_date* date, const time_t* t);
|
||||
void iso8601_from_time_t(struct iso8601_date* date, const time_t* t)
|
||||
#ifndef DOXYGEN
|
||||
__attribute__((nonnull))
|
||||
#endif
|
||||
;
|
||||
|
||||
/*! \brief Convert to a time_t. */
|
||||
void iso8601_to_time_t(time_t* t, const struct iso8601_date* date);
|
||||
void iso8601_to_time_t(time_t* t, const struct iso8601_date* date)
|
||||
#ifndef DOXYGEN
|
||||
__attribute__((nonnull))
|
||||
#endif
|
||||
;
|
||||
|
||||
|
||||
|
||||
/*!@}*/
|
||||
/* options for text editors
|
||||
kate: replace-trailing-space-save true; space-indent true; tab-width 4;
|
||||
vim: expandtab:ts=4:sw=4
|
||||
vim: expandtab:ts=4:sw=4:syntax=ch.doxygen
|
||||
*/
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
/* libiso8601/src/libiso8601/400_calc.h
|
||||
*
|
||||
* (c)2006, Laurence Withers, <l@lwithers.me.uk>.
|
||||
* Released under the GNU GPLv2. See file COPYING or
|
||||
* (c)2006-2010, Laurence Withers, <l@lwithers.me.uk>.
|
||||
* Released under the GNU GPLv3. See file COPYING or
|
||||
* http://www.gnu.org/copyleft/gpl.html for details.
|
||||
*/
|
||||
|
||||
|
|
@ -9,8 +9,8 @@
|
|||
|
||||
/*! \defgroup calc Conversion and calculation routines.
|
||||
|
||||
This set of functions is useful for converting dates and times into formats understood by humans,
|
||||
and vice versa.
|
||||
This set of functions is useful for converting dates and times into formats
|
||||
understood by humans, and vice versa.
|
||||
|
||||
*/
|
||||
/*!@{*/
|
||||
|
|
@ -26,7 +26,11 @@ and vice versa.
|
|||
Returns non-0 if \a year is a leap year.
|
||||
|
||||
*/
|
||||
int iso8601_isleap(int year);
|
||||
int iso8601_isleap(int year)
|
||||
#ifndef DOXYGEN
|
||||
__attribute__((nonnull))
|
||||
#endif
|
||||
;
|
||||
|
||||
|
||||
|
||||
|
|
@ -38,7 +42,12 @@ int iso8601_isleap(int year);
|
|||
\param date Date to convert.
|
||||
|
||||
*/
|
||||
void iso8601_to_cal(int* year, int* month, int* day, const struct iso8601_date* date);
|
||||
void iso8601_to_cal(int* year, int* month, int* day,
|
||||
const struct iso8601_date* date)
|
||||
#ifndef DOXYGEN
|
||||
__attribute__((nonnull))
|
||||
#endif
|
||||
;
|
||||
|
||||
|
||||
|
||||
|
|
@ -51,11 +60,18 @@ void iso8601_to_cal(int* year, int* month, int* day, const struct iso8601_date*
|
|||
\retval 0 on success.
|
||||
\retval -1 on error (and see \a errno).
|
||||
|
||||
Converts the date specified in \a year, \a month and \a day into \a date. Does not touch the \a sec
|
||||
or \a nsec time members of \a date.
|
||||
Converts the date specified in \a year, \a month and \a day into \a date.
|
||||
|
||||
\note Does not touch the \a sec or \a nsec time members of \a date. This means
|
||||
they will be unchanged after a call to this function. If this will lead to
|
||||
unexpected results, initialise the structure to 0 first.
|
||||
|
||||
*/
|
||||
int iso8601_from_cal(struct iso8601_date* date, int year, int month, int day);
|
||||
int iso8601_from_cal(struct iso8601_date* date, int year, int month, int day)
|
||||
#ifndef DOXYGEN
|
||||
__attribute__((nonnull))
|
||||
#endif
|
||||
;
|
||||
|
||||
|
||||
|
||||
|
|
@ -66,7 +82,11 @@ int iso8601_from_cal(struct iso8601_date* date, int year, int month, int day);
|
|||
\param date Date to convert.
|
||||
|
||||
*/
|
||||
void iso8601_to_ord(int* year, int* oday, const struct iso8601_date* date);
|
||||
void iso8601_to_ord(int* year, int* oday, const struct iso8601_date* date)
|
||||
#ifndef DOXYGEN
|
||||
__attribute__((nonnull))
|
||||
#endif
|
||||
;
|
||||
|
||||
|
||||
|
||||
|
|
@ -78,11 +98,18 @@ void iso8601_to_ord(int* year, int* oday, const struct iso8601_date* date);
|
|||
\retval 0 on success.
|
||||
\retval -1 on error (and see \a errno).
|
||||
|
||||
Converts the date specified into \a year and \a oday into \a date. Does not touch the \a sec or
|
||||
\a nsec time members of \a date.
|
||||
Converts the date specified into \a year and \a oday into \a date.
|
||||
|
||||
\note Does not touch the \a sec or \a nsec time members of \a date. This means
|
||||
they will be unchanged after a call to this functoin. If this will lead to
|
||||
unexpected results, initialise the structure to 0 first.
|
||||
|
||||
*/
|
||||
int iso8601_from_ord(struct iso8601_date* date, int year, int oday);
|
||||
int iso8601_from_ord(struct iso8601_date* date, int year, int oday)
|
||||
#ifndef DOXYGEN
|
||||
__attribute__((nonnull))
|
||||
#endif
|
||||
;
|
||||
|
||||
|
||||
|
||||
|
|
@ -94,7 +121,12 @@ int iso8601_from_ord(struct iso8601_date* date, int year, int oday);
|
|||
\param date Date to convert.
|
||||
|
||||
*/
|
||||
void iso8601_to_week(int* year, int* week, int* wday, const struct iso8601_date* date);
|
||||
void iso8601_to_week(int* year, int* week, int* wday,
|
||||
const struct iso8601_date* date)
|
||||
#ifndef DOXYGEN
|
||||
__attribute__((nonnull))
|
||||
#endif
|
||||
;
|
||||
|
||||
|
||||
|
||||
|
|
@ -107,8 +139,18 @@ void iso8601_to_week(int* year, int* week, int* wday, const struct iso8601_date*
|
|||
\retval 0 on success.
|
||||
\retval -1 on error (and see \a errno).
|
||||
|
||||
Converts the date specified into \a year, \a week and \a wday into \a date.
|
||||
|
||||
\note Does not touch the \a sec or \a nsec time members of \a date. This means
|
||||
they will be unchanged after a call to this functoin. If this will lead to
|
||||
unexpected results, initialise the structure to 0 first.
|
||||
|
||||
*/
|
||||
int iso8601_from_week(struct iso8601_date* date, int year, int week, int wday);
|
||||
int iso8601_from_week(struct iso8601_date* date, int year, int week, int wday)
|
||||
#ifndef DOXYGEN
|
||||
__attribute__((nonnull))
|
||||
#endif
|
||||
;
|
||||
|
||||
|
||||
|
||||
|
|
@ -119,11 +161,16 @@ int iso8601_from_week(struct iso8601_date* date, int year, int week, int wday);
|
|||
\param[out] sec Output second.
|
||||
\param date Date/time to convert.
|
||||
|
||||
Converts the time stored in \a date into wall clock format, storing the result in \a hour, \a min
|
||||
and \a sec.
|
||||
Converts the time stored in \a date into wall clock format, storing the result
|
||||
in \a hour, \a min and \a sec.
|
||||
|
||||
*/
|
||||
void iso8601_to_clocktime(int* hour, int* min, int* sec, const struct iso8601_date* date);
|
||||
void iso8601_to_clocktime(int* hour, int* min, int* sec,
|
||||
const struct iso8601_date* date)
|
||||
#ifndef DOXYGEN
|
||||
__attribute__((nonnull))
|
||||
#endif
|
||||
;
|
||||
|
||||
|
||||
|
||||
|
|
@ -136,16 +183,25 @@ void iso8601_to_clocktime(int* hour, int* min, int* sec, const struct iso8601_da
|
|||
\retval 0 on success.
|
||||
\retval -1 on error (and see \a errno).
|
||||
|
||||
Converts the time as specified by \a hour, \a min and \a sec, storing the result in \a date. Does
|
||||
not touch the \a day (date) member of \a date.
|
||||
Converts the time as specified by \a hour, \a min and \a sec, storing the
|
||||
result in \a date.
|
||||
|
||||
\note Does not touch the \a day (date) member of \a date. This means it will be
|
||||
unchanged after a call to this function. If this will lead to unexpected
|
||||
results, initialise the structure to 0 first.
|
||||
|
||||
*/
|
||||
int iso8601_from_clocktime(struct iso8601_date* date, int hour, int min, int sec);
|
||||
int iso8601_from_clocktime(struct iso8601_date* date, int hour, int min,
|
||||
int sec)
|
||||
#ifndef DOXYGEN
|
||||
__attribute__((nonnull))
|
||||
#endif
|
||||
;
|
||||
|
||||
|
||||
|
||||
/*!@}*/
|
||||
/* options for text editors
|
||||
kate: replace-trailing-space-save true; space-indent true; tab-width 4;
|
||||
vim: expandtab:ts=4:sw=4
|
||||
vim: expandtab:ts=4:sw=4:syntax=ch.doxygen
|
||||
*/
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
/* libiso8601/src/libiso8601/400_leap.h
|
||||
*
|
||||
* (c)2006, Laurence Withers, <l@lwithers.me.uk>.
|
||||
* Released under the GNU GPLv2. See file COPYING or
|
||||
* (c)2006-2010, Laurence Withers, <l@lwithers.me.uk>.
|
||||
* Released under the GNU GPLv3. See file COPYING or
|
||||
* http://www.gnu.org/copyleft/gpl.html for details.
|
||||
*/
|
||||
|
||||
|
|
@ -9,20 +9,23 @@
|
|||
|
||||
/*! \defgroup leap Leap second support.
|
||||
|
||||
A set of functions for explicitly dealing with leap seconds. All library functions are implicitly
|
||||
leap second aware, but there are occasions when leap seconds must be dealt with explicitly. These
|
||||
functions permit this.
|
||||
A set of functions for explicitly dealing with leap seconds. All library
|
||||
functions are implicitly leap second aware, but there are occasions when leap
|
||||
seconds must be dealt with explicitly. These functions permit this.
|
||||
|
||||
Internally, leap seconds are represented as a table of day numbers; each day number present in the
|
||||
table means that the corresponding day has 86401 seconds (a leap second).
|
||||
Internally, leap seconds are represented as a table of day numbers; each day
|
||||
number present in the table means that the corresponding day has 86401 seconds
|
||||
(a leap second).
|
||||
|
||||
\note The library does not (yet) have support for negative leap seconds. This support will be added
|
||||
should a day with a negative leap second ever come. This will need to addressed in the API as
|
||||
the current API does not support loading a table of negative leap seconds.
|
||||
\note The library does not (yet) have support for negative leap seconds. This
|
||||
support will be added should a day with a negative leap second ever come.
|
||||
This will need to addressed in the API as the current API does not support
|
||||
loading a table of negative leap seconds.
|
||||
|
||||
It is possible to create a disk file containing an updated table and to load that file using
|
||||
\ref iso8601_leap_table_load (or to explicitly use an existing in-memory table with
|
||||
\ref iso8601_leap_table_set). The format of the on-disk file is:
|
||||
It is possible to create a disk file containing an updated table and to load
|
||||
that file using \ref iso8601_leap_table_load (or to explicitly use an existing
|
||||
in-memory table with \ref iso8601_leap_table_set). The format of the on-disk
|
||||
file is:
|
||||
|
||||
<pre># integers are stored big-endian
|
||||
[8*char] signature, "/O9PdPZI"
|
||||
|
|
@ -43,14 +46,19 @@ It is possible to create a disk file containing an updated table and to load tha
|
|||
\retval 86400 day with no leap second.
|
||||
\retval 86401 day with one leap second.
|
||||
|
||||
Returns the duration of a day \a date, in seconds. This function takes leap seconds into account and
|
||||
may be used to determine if a day contains a leap second or not.
|
||||
Returns the duration of a day \a date, in seconds. This function takes leap
|
||||
seconds into account and may be used to determine if a day contains a leap
|
||||
second or not.
|
||||
|
||||
\note There have not yet been any days requiring a negative leap second, so at present 86399 will
|
||||
never be returned.
|
||||
\note There have not yet been any days requiring a negative leap second, so at
|
||||
present 86399 will never be returned.
|
||||
|
||||
*/
|
||||
int iso8601_seconds_leap(const struct iso8601_date* date);
|
||||
int iso8601_seconds_leap(const struct iso8601_date* date)
|
||||
#ifndef DOXYGEN
|
||||
__attribute__((nonnull))
|
||||
#endif
|
||||
;
|
||||
|
||||
|
||||
|
||||
|
|
@ -60,13 +68,19 @@ int iso8601_seconds_leap(const struct iso8601_date* date);
|
|||
\param end The end date.
|
||||
\returns Number of leap seconds elapsed.
|
||||
|
||||
Computes the number of leap seconds that have elapsed between two days. Note that this is the sum of
|
||||
such leap seconds, so it will be 0 if (for example) there is one positive leap second and one
|
||||
negative leap second. The ordering of the dates is important; if \a start is after \a end, then the
|
||||
value returned will be negative (for positive leap seconds).
|
||||
Computes the number of leap seconds that have elapsed between two days. Note
|
||||
that this is the sum of such leap seconds, so it will be 0 if (for example)
|
||||
there is one positive leap second and one negative leap second. The ordering of
|
||||
the dates is important; if \a start is after \a end, then the value returned
|
||||
will be negative (for positive leap seconds).
|
||||
|
||||
*/
|
||||
int iso8601_leap_elapsed(const struct iso8601_date* start, const struct iso8601_date* end);
|
||||
int iso8601_leap_elapsed(const struct iso8601_date* start,
|
||||
const struct iso8601_date* end)
|
||||
#ifndef DOXYGEN
|
||||
__attribute__((nonnull))
|
||||
#endif
|
||||
;
|
||||
|
||||
|
||||
|
||||
|
|
@ -75,17 +89,22 @@ int iso8601_leap_elapsed(const struct iso8601_date* start, const struct iso8601_
|
|||
\param new_table Array of day numbers on which leap seconds occur.
|
||||
\param new_size Number of entries in array.
|
||||
|
||||
This function can be used to update the table of leap seconds at runtime. The \a new_table argument
|
||||
points to an array of integers, each entry being the day number containing a leap second. The array
|
||||
must be sorted so that lower day numbers appear towards the start of the array. \a new_size gives
|
||||
the number of entries in the array. \a new_table must persist in memory as long as library functions
|
||||
are in use.
|
||||
This function can be used to update the table of leap seconds at runtime. The
|
||||
\a new_table argument points to an array of integers, each entry being the day
|
||||
number containing a leap second. The array must be sorted so that lower day
|
||||
numbers appear towards the start of the array. \a new_size gives the number of
|
||||
entries in the array. \a new_table must persist in memory as long as library
|
||||
functions are in use.
|
||||
|
||||
\warning If negative leap seconds are ever used, this function will not support them. There may need
|
||||
to be an ABI change in future to solve this problem.
|
||||
\warning If negative leap seconds are ever used, this function will not support
|
||||
them. There may need to be an ABI change in future to solve this problem.
|
||||
|
||||
*/
|
||||
void iso8601_leap_table_set(int* new_table, int new_size) __attribute__((nonnull));
|
||||
void iso8601_leap_table_set(int* new_table, int new_size)
|
||||
#ifndef DOXYGEN
|
||||
__attribute__((nonnull))
|
||||
#endif
|
||||
;
|
||||
|
||||
|
||||
|
||||
|
|
@ -95,15 +114,21 @@ void iso8601_leap_table_set(int* new_table, int new_size) __attribute__((nonnull
|
|||
\retval 0 on success.
|
||||
\retval -1 on error (and see \a errno).
|
||||
|
||||
This function attempts to load a new table of leap seconds from disk, using the filename \a fname.
|
||||
If \a fname is not specified, the system default (set at compile time) will be used.
|
||||
This function attempts to load a new table of leap seconds from disk, using the
|
||||
filename \a fname. If \a fname is not specified, the system default (set at
|
||||
compile time) will be used.
|
||||
|
||||
If the table is loaded successfully, it will be set with \ref iso8601_leap_table_set(). On any
|
||||
error, -1 will be returned, and \a errno will be set appropriately. If \a errno is \c EINVAL, then
|
||||
the file does not contain a valid leap second table.
|
||||
If the table is loaded successfully, it will be set with \ref
|
||||
iso8601_leap_table_set(). On any error, -1 will be returned, and \a errno will
|
||||
be set appropriately. If \a errno is \c EINVAL, then the file does not contain
|
||||
a valid leap second table.
|
||||
|
||||
*/
|
||||
int iso8601_leap_table_load(const char* fname);
|
||||
int iso8601_leap_table_load(const char* fname)
|
||||
#ifndef DOXYGEN
|
||||
__attribute__((nonnull))
|
||||
#endif
|
||||
;
|
||||
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
/* libiso8601/src/libiso8601/400_manip.h
|
||||
*
|
||||
* (c)2006, Laurence Withers, <l@lwithers.me.uk>.
|
||||
* Released under the GNU GPLv2. See file COPYING or
|
||||
* (c)2006-2010, Laurence Withers, <l@lwithers.me.uk>.
|
||||
* Released under the GNU GPLv3. See file COPYING or
|
||||
* http://www.gnu.org/copyleft/gpl.html for details.
|
||||
*/
|
||||
|
||||
|
|
@ -9,8 +9,8 @@
|
|||
|
||||
/*! \defgroup manip Manipulation routines.
|
||||
|
||||
This set of functions is useful for performing arithmetic etc. on dates. It uses
|
||||
struct iso8601_elapsed to represent the magnitude of time differences.
|
||||
This set of functions is useful for performing arithmetic etc. on dates. It
|
||||
uses struct \ref iso8601_elapsed to represent the magnitude of time differences.
|
||||
|
||||
*/
|
||||
/*!@{*/
|
||||
|
|
@ -25,7 +25,11 @@ struct iso8601_elapsed to represent the magnitude of time differences.
|
|||
\retval 0 otherwise
|
||||
|
||||
*/
|
||||
int iso8601_lt(const struct iso8601_date* d1, const struct iso8601_date* d2);
|
||||
int iso8601_lt(const struct iso8601_date* d1, const struct iso8601_date* d2)
|
||||
#ifndef DOXYGEN
|
||||
__attribute__((nonnull))
|
||||
#endif
|
||||
;
|
||||
|
||||
|
||||
|
||||
|
|
@ -37,7 +41,11 @@ int iso8601_lt(const struct iso8601_date* d1, const struct iso8601_date* d2);
|
|||
\retval 0 otherwise
|
||||
|
||||
*/
|
||||
int iso8601_lte(const struct iso8601_date* d1, const struct iso8601_date* d2);
|
||||
int iso8601_lte(const struct iso8601_date* d1, const struct iso8601_date* d2)
|
||||
#ifndef DOXYGEN
|
||||
__attribute__((nonnull))
|
||||
#endif
|
||||
;
|
||||
|
||||
|
||||
|
||||
|
|
@ -49,7 +57,11 @@ int iso8601_lte(const struct iso8601_date* d1, const struct iso8601_date* d2);
|
|||
\retval 0 otherwise
|
||||
|
||||
*/
|
||||
int iso8601_eq(const struct iso8601_date* d1, const struct iso8601_date* d2);
|
||||
int iso8601_eq(const struct iso8601_date* d1, const struct iso8601_date* d2)
|
||||
#ifndef DOXYGEN
|
||||
__attribute__((nonnull))
|
||||
#endif
|
||||
;
|
||||
|
||||
|
||||
|
||||
|
|
@ -62,7 +74,11 @@ int iso8601_eq(const struct iso8601_date* d1, const struct iso8601_date* d2);
|
|||
\retval 1 if \a d1 > \a d2
|
||||
|
||||
*/
|
||||
int iso8601_cmp(const struct iso8601_date* d1, const struct iso8601_date* d2);
|
||||
int iso8601_cmp(const struct iso8601_date* d1, const struct iso8601_date* d2)
|
||||
#ifndef DOXYGEN
|
||||
__attribute__((nonnull))
|
||||
#endif
|
||||
;
|
||||
|
||||
|
||||
|
||||
|
|
@ -72,7 +88,12 @@ int iso8601_cmp(const struct iso8601_date* d1, const struct iso8601_date* d2);
|
|||
\param per Period to advance date/time by.
|
||||
|
||||
*/
|
||||
void iso8601_add_elapsed(struct iso8601_date* date, const struct iso8601_elapsed* per);
|
||||
void iso8601_add_elapsed(struct iso8601_date* date,
|
||||
const struct iso8601_elapsed* per)
|
||||
#ifndef DOXYGEN
|
||||
__attribute__((nonnull))
|
||||
#endif
|
||||
;
|
||||
|
||||
|
||||
|
||||
|
|
@ -82,7 +103,12 @@ void iso8601_add_elapsed(struct iso8601_date* date, const struct iso8601_elapsed
|
|||
\param per Period to regress date/time by.
|
||||
|
||||
*/
|
||||
void iso8601_subtract_elapsed(struct iso8601_date* date, const struct iso8601_elapsed* per);
|
||||
void iso8601_subtract_elapsed(struct iso8601_date* date,
|
||||
const struct iso8601_elapsed* per)
|
||||
#ifndef DOXYGEN
|
||||
__attribute__((nonnull))
|
||||
#endif
|
||||
;
|
||||
|
||||
|
||||
|
||||
|
|
@ -92,11 +118,17 @@ void iso8601_subtract_elapsed(struct iso8601_date* date, const struct iso8601_el
|
|||
\param per Period to advance date/time by.
|
||||
\param n Multiple of \a per.
|
||||
|
||||
Adds \a n multiples of \a per to \a date. \a n may be 0 or negative. The result is stored in
|
||||
\a date. This is an efficient implementation which avoids loops, but it does use 64-bit arithmetic.
|
||||
Adds \a n multiples of \a per to \a date. \a n may be 0 or negative. The result
|
||||
is stored in \a date. This is an efficient implementation which avoids loops,
|
||||
but it does use 64-bit arithmetic.
|
||||
|
||||
*/
|
||||
void iso8601_add_multiple(struct iso8601_date* date, const struct iso8601_elapsed* per, int n);
|
||||
void iso8601_add_multiple(struct iso8601_date* date,
|
||||
const struct iso8601_elapsed* per, int n)
|
||||
#ifndef DOXYGEN
|
||||
__attribute__((nonnull))
|
||||
#endif
|
||||
;
|
||||
|
||||
|
||||
|
||||
|
|
@ -107,13 +139,18 @@ void iso8601_add_multiple(struct iso8601_date* date, const struct iso8601_elapse
|
|||
\param[out] per Magnitude of period elapsed between two dates. Pointer may be 0.
|
||||
\param[out] sign Set to sign of difference (-1 or +1). Pointer may be 0.
|
||||
|
||||
This function will perform the calculation <code>|d1 - d2|</code>, storing the result in \a per (if
|
||||
it is not a null pointer). The sign of the result is stored in \a sign (if it is not a null
|
||||
pointer), i.e. -1 if \a d2 > \a d1 or +1 if \a d2 <= \a d1.
|
||||
This function will perform the calculation <code>|d1 - d2|</code>, storing the
|
||||
result in \a per (if it is not a null pointer). The sign of the result is
|
||||
stored in \a sign (if it is not a null pointer), i.e. -1 if \a d2 > \a d1 or
|
||||
+1 if \a d2 <= \a d1.
|
||||
|
||||
*/
|
||||
void iso8601_difference(const struct iso8601_date* d1, const struct iso8601_date* d2,
|
||||
struct iso8601_elapsed* per, int* sign);
|
||||
void iso8601_difference(const struct iso8601_date* d1,
|
||||
const struct iso8601_date* d2, struct iso8601_elapsed* per, int* sign)
|
||||
#ifndef DOXYGEN
|
||||
__attribute__((nonnull))
|
||||
#endif
|
||||
;
|
||||
|
||||
|
||||
|
||||
|
|
@ -124,13 +161,13 @@ void iso8601_difference(const struct iso8601_date* d1, const struct iso8601_date
|
|||
\param[out] remain Remainder. May be 0.
|
||||
\returns Number of times \a denom divides into \a num.
|
||||
|
||||
This function computes the number of times that \a denom can be divided into \a num, returning that
|
||||
number. If desired, the remaining period which could not be divided can be written into \a remain.
|
||||
Uses 64-bit arithmetic internally.
|
||||
This function computes the number of times that \a denom can be divided into \a
|
||||
num, returning that number. If desired, the remaining period which could not be
|
||||
divided can be written into \a remain. Uses 64-bit arithmetic internally.
|
||||
|
||||
*/
|
||||
int iso8601_elapsed_div(const struct iso8601_elapsed* num, const struct iso8601_elapsed* denom,
|
||||
struct iso8601_elapsed* remain)
|
||||
int iso8601_elapsed_div(const struct iso8601_elapsed* num,
|
||||
const struct iso8601_elapsed* denom, struct iso8601_elapsed* remain)
|
||||
#ifndef DOXYGEN
|
||||
__attribute__((nonnull(1,2)));
|
||||
#endif
|
||||
|
|
|
|||
Loading…
Reference in New Issue