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_XTIME *	u8_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

typedef enum u8_timestamp_precision u8_tmprec

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

enum u8_timestamp_precision

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:

stime	an xtime structure
nodeid	a 48-bit node id, -1 means use the default
clockid	a clock id, -1 means make one up
buf	a (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:

buf	a (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:

xt	a pointer to a U8_XTIME structure
tick	a POSIX time_t value (seconds past the epoch)
prec	a u8_tmprec value indicating the precision of the timestamp
nsecs	the number of nanoseconds after the indicated second
tzoff	the timezone offset to use in populating the structure
dstoff	the 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:

s	a UTF-8 (ASCII) string containing an ISO-8601 timestamp.
xt	a 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:

xt	a pointer to a U8_XTIME structure
tick	a POSIX time_t value (seconds past the epoch)
prec	a u8_tmprec value indicating the precision of the timestamp
nsecs	the 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:

xt	a pointer to a U8_XTIME structure
tick	a 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:

xt	a pointer to a U8_XTIME structure
tick	a POSIX time_t value (seconds past the epoch)
nsecs	an 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:

xt	a 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:

s	a UTF-8 character string
dflt	an 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:

string	a UTF-8 string
uuid	a (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:

s	a UTF-8 (ASCII) string containing an ISO-8601 timestamp.
xt	a 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:

xt	a pointer to a U8_XTIME structure.
tp	a 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:

a	pointer 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:

a	pointer 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:

a	pointer 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:

a	pointer 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:

uuid	a UUID
strbuf	a (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:

xt	a pointer to a U8_XTIME structure.
yt	a 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:

xt	a pointer to a U8_XTIME structure
delta	an 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:

ss	a pointer to a U8_OUTPUT stream
xt	a 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:

ss	a pointer to a U8_OUTPUT stream
xt	a 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:

xt	a pointer to a U8_XTIME structure
tm	a pointer to a tm structure

Returns:: the time_t value for the moment represented by both data structures

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

Enumeration Type Documentation

Function Documentation