libu8
u8timefns.h File Reference

Provides various functions for manipulating information about dates and times. More...

Data Structures

struct  U8_XTIME
 The U8_XTIME struct defines a variable precision timezone-offset time representation with extractable components. More...
 

Typedefs

typedef enum u8_timestamp_precision u8_tmprec
 Identifies the precision for a timestamp, ranging from u8_year to u8_femtosecond. More...
 
typedef struct U8_XTIME U8_XTIME
 The U8_XTIME struct defines a variable precision timezone-offset time representation with extractable components. More...
 

Enumerations

Functions

U8_EXPORT u8_xtime u8_init_xtime (struct U8_XTIME *xt, time_t tick, u8_tmprec prec, int nsecs, int tzoff, int dstoff)
 Populates a U8_XTIME structure based on a POSIX time_t value. More...
 
U8_EXPORT u8_xtime u8_local_xtime (struct U8_XTIME *xt, time_t tick, u8_tmprec prec, int nsecs)
 Populates a U8_XTIME structure for the local timezone based on a POSIX time_t value. More...
 
U8_EXPORT time_t u8_localtime (struct U8_XTIME *xt, time_t tick)
 Populates a U8_XTIME structure with local time based on a POSIX time_t value. More...
 
U8_EXPORT time_t u8_localtime_x (struct U8_XTIME *xt, time_t tick, int nsecs)
 Populates a U8_XTIME structure with a local time based on a POSIX time_t and a nanosecond count. More...
 
U8_EXPORT time_t u8_xtime_to_tptr (struct U8_XTIME *xt, struct tm *tm)
 Populates a struct tm structure from an U8_XTIME representation. More...
 
U8_EXPORT time_t u8_now (struct U8_XTIME *xt)
 Populates a U8_XTIME structure based on the current local time. More...
 
U8_EXPORT time_t u8_mktime (struct U8_XTIME *xt)
 Returns a POSIX time_t representation for a broken down U8_XTIME structure, including timezone and dst offsets Also fills out day of week, day of year, etc. More...
 
U8_EXPORT time_t u8_mklocaltime (struct U8_XTIME *xt)
 Returns a POSIX time_t representation for a broken down U8_XTIME structure, interpreting the time locally and filling out timezone and daylight offsets. More...
 
U8_EXPORT void u8_set_xtime_precision (struct U8_XTIME *xt, u8_tmprec tp)
 Sets the time precision of a U8_XTIME structure. More...
 
U8_EXPORT void u8_set_xtime_gmtoff (struct U8_XTIME *xt, int tzoff, int dstoff)
 Sets the GMT offset of an XTIME structure. More...
 
U8_EXPORT double u8_xtime_diff (struct U8_XTIME *xt, struct U8_XTIME *yt)
 Returns a non-integral difference, in seconds, between U8_XTIME pointers. More...
 
U8_EXPORT void u8_xtime_plus (struct U8_XTIME *xt, double delta)
 Adds a specific interval to a U8_XTIME representation. More...
 
U8_EXPORT int u8_parse_tzspec (u8_string s, int dflt)
 Returns a GMT offset in seconds for a given string. More...
 
U8_EXPORT void u8_apply_tzspec (struct U8_XTIME *xt, u8_string s)
 Parses and applies timezone information to a U8_XTIME structure Negative numbers indicate offsets to clock times earlier than (east of) GMT. More...
 
U8_EXPORT time_t u8_iso8601_to_xtime (u8_string s, struct U8_XTIME *xt)
 Populates a U8_XTIME pointer based on an ISO-8601 formated timestamp. More...
 
U8_EXPORT void u8_xtime_to_iso8601 (struct U8_OUTPUT *ss, struct U8_XTIME *xt)
 Outputs an ISO-8601 representation of a U8_XTIME structure. More...
 
U8_EXPORT void u8_xtime_to_iso8601_x (struct U8_OUTPUT *ss, struct U8_XTIME *xt, int flags)
 Outputs an ISO-8601 of an U8_XTIME structure, with variations. More...
 
U8_EXPORT time_t u8_rfc822_to_xtime (u8_string s, struct U8_XTIME *xt)
 Populates a U8_XTIME pointer based on an RFC822 formated timestamp. More...
 
U8_EXPORT void u8_xtime_to_rfc822 (struct U8_OUTPUT *ss, struct U8_XTIME *xt)
 Outputs an RFC822 representation of a U8_XTIME structure. More...
 
U8_EXPORT void u8_xtime_to_rfc822_x (struct U8_OUTPUT *ss, struct U8_XTIME *xt, int zone, int opts)
 Outputs an RFC822 representation of a U8_XTIME structure. More...
 
U8_EXPORT long long u8_millitime (void)
 Returns the number of milliseconds since the epoch. More...
 
U8_EXPORT u8_uuid u8_consuuid (struct U8_XTIME *xtime, long long nodeid, short clockid, u8_uuid buf)
 Gets a 16-byte UUID based on the time and MAC address Arguments: none. More...
 
U8_EXPORT u8_uuid u8_getuuid (u8_uuid buf)
 Gets a 16-byte UUID based on the time and MAC address. More...
 
U8_EXPORT u8_string u8_uuidstring (u8_uuid uuid, u8_byte *strbuf)
 Gets the text representation of a 16-byte UUID based on the time and MAC address. More...
 
U8_EXPORT u8_uuid u8_parseuuid (u8_string string, u8_uuid uuid)
 Converts a text representation of a UUID into a UUID Arguments: a string. More...
 
U8_EXPORT long long u8_uuid_nodeid (u8_uuid uuid)
 Gets the node id for a time-based UUID, returning -1 if the UUID is not time-based. More...
 
U8_EXPORT long long u8_uuid_timestamp (u8_uuid uuid)
 Gets the timestamp for the UUID, returning -1 if the UUID is not time-based. More...
 
U8_EXPORT time_t u8_uuid_tick (u8_uuid uuid)
 Gets the time_t tick for the UUID, returning -1 if the UUID is not time-based or is outside of the time_t range. More...
 
U8_EXPORT struct U8_XTIMEu8_uuid_xtime (u8_uuid uuid, struct U8_XTIME *xtime)
 Gets the time_t tick for the UUID, returning -1 if the UUID is not time-based or is outside of the time_t range. More...
 

Detailed Description

Provides various functions for manipulating information about dates and times.

It's chief data structure is struct U8_XTIME, which combines a broken down time representation with a nanosecond timer and information about timezone, dst offset, and precision. Significantly, these functions are intended to represent most possible timezones, rather than just the local time and GMT. U8_XTIME structures are populated by u8_now, u8_localtime, and u8_iso8601_to_xtime. u8_mktime returns a time_t value from a U8_XTIME pointer and u8_xtime_to_iso8601 outputs a printed representation of U8_XTIME. (Also see the explanation of the t conversion in the u8printf docmentation.) Finally, u8_xtime_diff and u8_xtime_plus do precision-sensitive arithmetic on U8_XTIME structures.

Typedef Documentation

Identifies the precision for a timestamp, ranging from u8_year to u8_femtosecond.

Precisions finer than u8_nanosecond are not currently effective and on many platforms, precisions finer than microseconds are not generally significant.

typedef struct U8_XTIME U8_XTIME

The U8_XTIME struct defines a variable precision timezone-offset time representation with extractable components.

Enumeration Type Documentation

Identifies the precision for a timestamp, ranging from u8_year to u8_femtosecond.

Precisions finer than u8_nanosecond are not currently effective and on many platforms, precisions finer than microseconds are not generally significant.

Function Documentation

U8_EXPORT void u8_apply_tzspec ( struct U8_XTIME xt,
u8_string  s 
)

Parses and applies timezone information to a U8_XTIME structure Negative numbers indicate offsets to clock times earlier than (east of) GMT.

Strings such as -5:00 and +2:00 are handled, as are some commoner, unambigous timezone codes.

Parameters
xta pointer to a U8_XTIME structure
sa UTF-8 character string
Returns
void

References U8_XTIME::u8_tzoff.

Referenced by u8_iso8601_to_xtime(), and u8_rfc822_to_xtime().

U8_EXPORT u8_uuid u8_consuuid ( struct U8_XTIME xtime,
long long  nodeid,
short  clockid,
u8_uuid  buf 
)

Gets a 16-byte UUID based on the time and MAC address Arguments: none.

Parameters
xtimean xtime structure
nodeida 48-bit node id, -1 means use the default
clockida clock id, -1 means make one up
bufa (possibly NULL) 16-byte buffer to use/return
Returns
an array of 16 bytes

References u8_now(), and u8_random().

Referenced by u8_rfc822_to_xtime().

U8_EXPORT u8_uuid u8_getuuid ( u8_uuid  buf)

Gets a 16-byte UUID based on the time and MAC address.

Parameters
bufa (possibly NULL) 16-byte buffer to use/return
Returns
an array of 16 bytes
U8_EXPORT u8_xtime u8_init_xtime ( struct U8_XTIME xt,
time_t  tick,
u8_tmprec  prec,
int  nsecs,
int  tzoff,
int  dstoff 
)

Populates a U8_XTIME structure based on a POSIX time_t value.

This populates the broken down components of an XTIME structure based on a given timezone offset (including DST compensation). If the xt pointer is NULL, one is consed with u8_alloc/malloc If the time value is negative, the current date and time is used.

Parameters
xta pointer to a U8_XTIME structure
ticka POSIX time_t value (seconds past the epoch)
preca u8_tmprec value indicating the precision of the timestamp
nsecsthe number of nanoseconds after the indicated second
tzoffthe timezone offset to use in populating the structure
dstoffthe daylight savings time offset to use When the tick value is negative (referring to the current time), the precision argument is bumped down to the available precision. The nsecs argument may be ignored based on the precision argument.

References u8_graberr(), u8_local_xtime(), U8_XTIME::u8_nsecs, U8_XTIME::u8_prec, U8_XTIME::u8_tick, and U8_XTIME::u8_tzoff.

Referenced by u8_iso8601_to_xtime(), u8_millitime(), u8_rfc822_to_xtime(), u8_set_xtime_gmtoff(), u8_uuid_xtime(), and u8_xtime_plus().

U8_EXPORT time_t u8_iso8601_to_xtime ( u8_string  s,
struct U8_XTIME xt 
)

Populates a U8_XTIME pointer based on an ISO-8601 formated timestamp.

Parameters
sa UTF-8 (ASCII) string containing an ISO-8601 timestamp.
xta pointer to a U8_XTIME structure.
Returns
the time_t value for the structure

References u8_apply_tzspec(), u8_init_xtime(), u8_log(), U8_XTIME::u8_nsecs, U8_XTIME::u8_prec, u8_printf(), U8_XTIME::u8_tick, U8_XTIME::u8_tzoff, u8_xtime_to_iso8601(), and u8_xtime_to_iso8601_x().

U8_EXPORT u8_xtime u8_local_xtime ( struct U8_XTIME xt,
time_t  tick,
u8_tmprec  prec,
int  nsecs 
)

Populates a U8_XTIME structure for the local timezone based on a POSIX time_t value.

This populates the broken down components of an XTIME structure based on the local timezone If the xt pointer is NULL, one is consed with u8_alloc/malloc If the time value is negative, the current date and time is used.

Parameters
xta pointer to a U8_XTIME structure
ticka POSIX time_t value (seconds past the epoch)
preca u8_tmprec value indicating the precision of the timestamp
nsecsthe number of nanoseconds after the indicated second When the tick value is negative (referring to the current time), the precision argument is bumped down to the available precision. The nsecs argument may be ignored based on the precision argument.

References u8_graberr(), U8_XTIME::u8_nsecs, U8_XTIME::u8_prec, U8_XTIME::u8_tick, and U8_XTIME::u8_tzoff.

Referenced by u8_init_xtime(), u8_now(), u8_rfc822_to_xtime(), and u8_sessionid().

U8_EXPORT time_t u8_localtime ( struct U8_XTIME xt,
time_t  tick 
)

Populates a U8_XTIME structure with local time based on a POSIX time_t value.

This populates the broken down components based on the current timezone and initializes tzoff.

Parameters
xta pointer to a U8_XTIME structure
ticka POSIX time_t value (seconds past the epoch)

References u8_localtime_x().

U8_EXPORT time_t u8_localtime_x ( struct U8_XTIME xt,
time_t  tick,
int  nsecs 
)

Populates a U8_XTIME structure with a local time based on a POSIX time_t and a nanosecond count.

This populates the broken down components based on the current timezone and initializes tzoff.

Parameters
xta pointer to a U8_XTIME structure
ticka POSIX time_t value (seconds past the epoch)
nsecsan integer number of nanoseconds past the tick

References U8_XTIME::u8_nsecs, U8_XTIME::u8_prec, U8_XTIME::u8_tick, and U8_XTIME::u8_tzoff.

Referenced by u8_localtime().

U8_EXPORT long long u8_millitime ( void  )

Returns the number of milliseconds since the epoch.

This returns a value with whatever accuracy it can get.

Returns
a long long counting milliseconds

References u8_init_xtime().

U8_EXPORT time_t u8_mklocaltime ( struct U8_XTIME xt)

Returns a POSIX time_t representation for a broken down U8_XTIME structure, interpreting the time locally and filling out timezone and daylight offsets.

Also fills out day of week, day of year, etc.

Parameters
xta pointer to a populated U8_XTIME structure.
Returns
a POSIX time_t value indicating seconds past the epoch for the moment represented by xt
U8_EXPORT time_t u8_mktime ( struct U8_XTIME xt)

Returns a POSIX time_t representation for a broken down U8_XTIME structure, including timezone and dst offsets Also fills out day of week, day of year, etc.

Parameters
xta pointer to a populated U8_XTIME structure.
Returns
a POSIX time_t value indicating seconds past the epoch for the moment represented by xt

Referenced by u8_rfc822_to_xtime().

U8_EXPORT time_t u8_now ( struct U8_XTIME xt)

Populates a U8_XTIME structure based on the current local time.

This attempts to get the most precise representation possible.

References u8_graberr(), u8_local_xtime(), and U8_XTIME::u8_tick.

Referenced by u8_consuuid(), and u8_uuid_xtime().

U8_EXPORT int u8_parse_tzspec ( u8_string  s,
int  dflt 
)

Returns a GMT offset in seconds for a given string.

Negative numbers indicate offsets to clock times earlier than (east of) GMT. Strings such as -5:00 and +2:00 are handled, as are some commoner, unambigous timezone codes.

Parameters
sa UTF-8 character string
dfltan integer value used as a default if a valid offset cannot be determined
Returns
an int representing seconds offset from GMT
U8_EXPORT u8_uuid u8_parseuuid ( u8_string  string,
u8_uuid  uuid 
)

Converts a text representation of a UUID into a UUID Arguments: a string.

Parameters
stringa UTF-8 string
uuida (possibly NULL) 16-byte buffer to use/return
Returns
an array of 16 bytes
U8_EXPORT time_t u8_rfc822_to_xtime ( u8_string  s,
struct U8_XTIME xt 
)

Populates a U8_XTIME pointer based on an RFC822 formated timestamp.

Parameters
sa UTF-8 (ASCII) string containing an ISO-8601 timestamp.
xta pointer to a U8_XTIME structure.
Returns
the time_t value for the structure

References u8_apply_tzspec(), u8_consuuid(), u8_init_xtime(), u8_local_xtime(), u8_mktime(), U8_XTIME::u8_nsecs, U8_XTIME::u8_prec, u8_printf(), u8_random(), U8_XTIME::u8_tick, U8_XTIME::u8_tzoff, u8_uuid_nodeid(), u8_xtime_to_iso8601(), u8_xtime_to_rfc822(), and u8_xtime_to_rfc822_x().

U8_EXPORT void u8_set_xtime_gmtoff ( struct U8_XTIME xt,
int  tzoff,
int  dstoff 
)

Sets the GMT offset of an XTIME structure.

Parameters
xta pointer to a U8_XTIME structure
tzoff(int) a timezone offset in seconds
dstoff(int) a local (daylight savings/summer offset) in seconds
Returns
void

References u8_init_xtime(), U8_XTIME::u8_nsecs, U8_XTIME::u8_prec, and U8_XTIME::u8_tick.

U8_EXPORT void u8_set_xtime_precision ( struct U8_XTIME xt,
u8_tmprec  tp 
)

Sets the time precision of a U8_XTIME structure.

Parameters
xta pointer to a U8_XTIME structure.
tpa precision value (u8_tmprec), including u8_year, u8_month, u8_day, u8_hour, u8_minute, u8_second, u8_millisecond, u8_microsecond, or u8_nanosecond.
Returns
void

References U8_XTIME::u8_nsecs, U8_XTIME::u8_prec, and U8_XTIME::u8_tick.

U8_EXPORT long long u8_uuid_nodeid ( u8_uuid  uuid)

Gets the node id for a time-based UUID, returning -1 if the UUID is not time-based.

Parameters
uuida pointer to uuid (u8_uuid)
Returns
a long long (actually 48 bits)

Referenced by u8_rfc822_to_xtime().

U8_EXPORT time_t u8_uuid_tick ( u8_uuid  uuid)

Gets the time_t tick for the UUID, returning -1 if the UUID is not time-based or is outside of the time_t range.

Parameters
uuida pointer to uuid (u8_uuid)
Returns
a time_t value
U8_EXPORT long long u8_uuid_timestamp ( u8_uuid  uuid)

Gets the timestamp for the UUID, returning -1 if the UUID is not time-based.

The timestamp is the number of 100-nanosecond ticks since 15 October 1582, when the Gregorian calendar was adopted.

Parameters
uuida pointer to uuid (u8_uuid)
Returns
a long long uuid timestamp
U8_EXPORT struct U8_XTIME* u8_uuid_xtime ( u8_uuid  uuid,
struct U8_XTIME xtime 
)

Gets the time_t tick for the UUID, returning -1 if the UUID is not time-based or is outside of the time_t range.

Parameters
uuida pointer to uuid (u8_uuid)
xtimea (possibly NULL) pointer to a U8_XTIME struct to use
Returns
a pointer to a U8_XTIME struct

References u8_init_xtime(), u8_now(), U8_XTIME::u8_nsecs, u8_random(), and U8_XTIME::u8_tick.

U8_EXPORT u8_string u8_uuidstring ( u8_uuid  uuid,
u8_byte *  strbuf 
)

Gets the text representation of a 16-byte UUID based on the time and MAC address.

Parameters
uuida UUID
strbufa (possibly NULL) string buffer
Returns
a UTF-8 (actually, ASCII) string
U8_EXPORT double u8_xtime_diff ( struct U8_XTIME xt,
struct U8_XTIME yt 
)

Returns a non-integral difference, in seconds, between U8_XTIME pointers.

Returns the number of seconds (possibly non-integral) that the moment described by yt occurs after xt. This is negative if yt occurreed before xt. This incorporates timezone offsets and computes a value based on the least precise of the two timestamp pointers.

Parameters
xta pointer to a U8_XTIME structure.
yta pointer to a U8_XTIME structure.
Returns
a double representing a number of seconds

References U8_XTIME::u8_nsecs, U8_XTIME::u8_prec, and U8_XTIME::u8_tick.

U8_EXPORT void u8_xtime_plus ( struct U8_XTIME xt,
double  delta 
)

Adds a specific interval to a U8_XTIME representation.

The actual change will reflect the precision of the XTIME representation. Adding a negative value moves the point back in time.

Parameters
xta pointer to a U8_XTIME structure
deltaan offset in seconds from the current time represented by xt.
Returns
void

References u8_init_xtime(), U8_XTIME::u8_nsecs, U8_XTIME::u8_prec, U8_XTIME::u8_tick, and U8_XTIME::u8_tzoff.

U8_EXPORT void u8_xtime_to_iso8601 ( struct U8_OUTPUT ss,
struct U8_XTIME xt 
)

Outputs an ISO-8601 representation of a U8_XTIME structure.

Parameters
ssa pointer to a U8_OUTPUT stream
xta pointer to a U8_XTIME structure.
Returns
void

This takes xtime pointer and outputs an ISO8601 representation of it, obeying the precision of the XTIME structure

Referenced by u8_iso8601_to_xtime(), and u8_rfc822_to_xtime().

U8_EXPORT void u8_xtime_to_iso8601_x ( struct U8_OUTPUT ss,
struct U8_XTIME xt,
int  flags 
)

Outputs an ISO-8601 of an U8_XTIME structure, with variations.

Parameters
ssa pointer to a U8_OUTPUT stream
xta pointer to a U8_XTIME structure.
flagsan int ORing together various display options
Returns
void

The flags arg provides display options, which can be ORd together: U8_ISO8601_BASIC: use the more compact BASIC format) U8_ISO8601_NOZONE: don't show the timezone information U8_ISO8601_NOMSECS: don't show milli/micro/nano seconds U8_ISO8601_UTC: display time as UTC

Referenced by u8_iso8601_to_xtime().

U8_EXPORT void u8_xtime_to_rfc822 ( struct U8_OUTPUT ss,
struct U8_XTIME xt 
)

Outputs an RFC822 representation of a U8_XTIME structure.

Parameters
ssa pointer to a U8_OUTPUT stream
xta pointer to a U8_XTIME structure.
Returns
void

Referenced by u8_rfc822_to_xtime().

U8_EXPORT void u8_xtime_to_rfc822_x ( struct U8_OUTPUT ss,
struct U8_XTIME xt,
int  zone,
int  opts 
)

Outputs an RFC822 representation of a U8_XTIME structure.

Parameters
ssa pointer to a U8_OUTPUT stream
xta pointer to a U8_XTIME structure.
zonea timezone offset
optsdisplay option flags (currently unused)
Returns
void

Referenced by u8_rfc822_to_xtime().

U8_EXPORT time_t u8_xtime_to_tptr ( struct U8_XTIME xt,
struct tm *  tm 
)

Populates a struct tm structure from an U8_XTIME representation.

Parameters
xta pointer to a U8_XTIME structure
tma pointer to a tm structure
Returns
the time_t value for the moment represented by both data structures

References U8_XTIME::u8_tzoff.