libu8
Data Structures | Typedefs | Enumerations | Functions
include/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.
typedef struct U8_XTIME U8_XTIME
 The U8_XTIME struct defines a variable precision timezone-offset time representation with extractable components.

Enumerations

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

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.
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.
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.
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.
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.
U8_EXPORT time_t u8_now (struct U8_XTIME *xt)
 Populates a U8_XTIME structure based on the current local time.
U8_EXPORT time_t u8_mktime (struct U8_XTIME *xt)
 Returns a POSIX time_t representation for a U8_XTIME structure.
U8_EXPORT void u8_set_xtime_precision (struct U8_XTIME *xt, u8_tmprec tp)
 Sets the time precision of a U8_XTIME structure.
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.
U8_EXPORT void u8_xtime_plus (struct U8_XTIME *xt, double delta)
 Adds a specific interval to a U8_XTIME representation.
U8_EXPORT int u8_parse_tzspec (u8_string s, int dflt)
 Returns a GMT offset in seconds for a given string.
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.
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.
U8_EXPORT time_t u8_rfc822_to_xtime (u8_string s, struct U8_XTIME *xt)
 Populates a U8_XTIME pointer based on an ISO-8601 formated timestamp.
U8_EXPORT void u8_xtime_to_rfc822 (struct U8_OUTPUT *ss, struct U8_XTIME *xt)
 Outputs an ISO-8601 representation of a U8_XTIME structure.
U8_EXPORT long long u8_millitime (void)
 Returns the number of milliseconds since the epoch.
U8_EXPORT long long u8_microtime (void)
 Returns the number of microseconds since the epoch.
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.
U8_EXPORT u8_uuid u8_getuuid (u8_uuid buf)
 Gets a 16-byte UUID based on the time and MAC address.
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.
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.
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.
U8_EXPORT long long u8_uuid_timestamp (u8_uuid)
 Gets the timestamp for the UUID, returning -1 if the UUID is not time-based.
U8_EXPORT time_t u8_uuid_tick (u8_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.
U8_EXPORT struct U8_XTIMEu8_uuid_xtime (u8_uuid, struct U8_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.

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 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:
stimean 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
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.
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
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.
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)
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
U8_EXPORT long long u8_microtime ( void  )

Returns the number of microseconds since the epoch.

This returns a value with whatever accuracy it can get.

Returns:
a long long counting microseconds
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
U8_EXPORT time_t u8_mktime ( struct U8_XTIME xt)

Returns a POSIX time_t representation for a U8_XTIME structure.

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_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.

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 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
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
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:
apointer to uuid (u8_uuid)
Returns:
a long long (actually 48 bits)
U8_EXPORT time_t u8_uuid_tick ( u8_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:
apointer to uuid (u8_uuid)
Returns:
a time_t value
U8_EXPORT long long u8_uuid_timestamp ( u8_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:
apointer to uuid (u8_uuid)
Returns:
a long long uuid timestamp
U8_EXPORT struct U8_XTIME* u8_uuid_xtime ( u8_uuid  ,
struct U8_XTIME  
) [read]

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:
apointer to uuid (u8_uuid)
a(possibly NULL) pointer to a U8_XTIME struct to use
Returns:
a pointer to a U8_XTIME struct
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
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
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
U8_EXPORT void u8_xtime_to_rfc822 ( 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
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