Timestamp representation, computation, and conversion. More...

Detailed Description

Timestamp representation, computation, and conversion.

Files
file	timex.h
	Utility library for comparing and computing timestamps.

file	tm.h
	Utility library for `struct tm`.

Data Structures
struct	timex_t
	A timex timestamp. More...

Macros
#define	US_PER_SEC (1000000LU)
	The number of microseconds per second.

#define	SEC_PER_MIN (60LU)
	The number of seconds per minute.

#define	CS_PER_SEC (100LU)
	The number of centiseconds per second.

#define	MS_PER_SEC (1000LU)
	The number of milliseconds per second.

#define	US_PER_MS (1000LU)
	The number of microseconds per millisecond.

#define	US_PER_CS (10000U)
	The number of microseconds per centisecond.

#define	NS_PER_US (1000LU)
	The number of nanoseconds per microsecond.

#define	NS_PER_SEC (1000000000U)
	The number of nanoseconds per second.

#define	TIMEX_MAX_STR_LEN (20)
	The maximum length of the string representation of a timex timestamp.

#define	TM_WDAY_SUN (0)
	Sunday in `struct tm::tm_wday`.

#define	TM_WDAY_MON (1)
	Monday in `struct tm::tm_wday`.

#define	TM_WDAY_TUE (2)
	Tuesday in `struct tm::tm_wday`.

#define	TM_WDAY_WED (3)
	Wednesday in `struct tm::tm_wday`.

#define	TM_WDAY_THU (4)
	Thursday in `struct tm::tm_wday`.

#define	TM_WDAY_FRI (5)
	Friday in `struct tm::tm_wday`.

#define	TM_WDAY_SAT (6)
	Saturday in `struct tm::tm_wday`.

#define	TM_MON_JAN ( 0)
	January in `struct tm::tm_mon`

#define	TM_MON_FEB ( 1)
	February in `struct tm::tm_mon`

#define	TM_MON_MAR ( 2)
	March in `struct tm::tm_mon`

#define	TM_MON_APR ( 3)
	April in `struct tm::tm_mon`

#define	TM_MON_MAY ( 4)
	May in `struct tm::tm_mon`

#define	TM_MON_JUN ( 5)
	June in `struct tm::tm_mon`

#define	TM_MON_JUL ( 6)
	July in `struct tm::tm_mon`

#define	TM_MON_AUG ( 7)
	August in `struct tm::tm_mon`

#define	TM_MON_SEP ( 8)
	September in `struct tm::tm_mon`

#define	TM_MON_OCT ( 9)
	October in `struct tm::tm_mon`

#define	TM_MON_NOV (10)
	November in `struct tm::tm_mon`

#define	TM_MON_DEC (11)
	December in `struct tm::tm_mon`

Functions
timex_t	timex_add (const timex_t a, const timex_t b)
	Adds two timestamps. More...

timex_t	timex_sub (const timex_t a, const timex_t b)
	Subtracts two timestamps. More...

timex_t	timex_set (uint32_t seconds, uint32_t microseconds)
	Initializes a timex timestamp. More...

int	timex_cmp (const timex_t a, const timex_t b)
	Compares two timex timestamps. More...

static void	timex_normalize (timex_t *time)
	Corrects timex structure so that microseconds < 1000000. More...

static int	timex_isnormalized (const timex_t *time)
	Tests a timex timestamp for normalization. More...

static uint64_t	timex_uint64 (const timex_t a)
	Converts a timex timestamp to a 64 bit value. More...

static timex_t	timex_from_uint64 (const uint64_t timestamp)
	Converts a 64 bit value of microseconds to a timex timestamp. More...

const char *	timex_to_str (timex_t t, char *timestamp)
	Converts a timex timestamp to a string. More...

int	tm_is_leap_year (unsigned year) CONST
	Tells if a given year is a leap year in the Gregorian calendar. More...

int	tm_doomsday (int year) CONST
	Returns the congruent weekday of the Doomsday (March 0). More...

void	tm_get_wyday (int year, int mon, int mday, int wday, int yday)
	Calculates the day of the year and the weekday of a given date. More...

void	tm_fill_derived_values (struct tm *tm)
	Fills in `struct tm::tm_wday` and `struct tm::tm_yday` given a date. More...

int	tm_is_valid_date (int year, int mon, int mday) CONST
	Tests if a date is valid. More...

int	tm_is_valid_time (int hour, int min, int sec) CONST
	Shallow test if a time is valid. More...

Variables
const int8_t	TM_MON_DAYS [12]
	The number of days in common years. More...

const int16_t	TM_MON_DAYS_ACCU [12]
	The prefixsum of the number of days in common years. More...

Function Documentation

◆ timex_add()

timex_t timex_add	(	const timex_t	a,
		const timex_t	b
	)

Adds two timestamps.

Parameters

[in]	a	First summand
[in]	b	Second summand

Returns: The sum of the two timestamps

◆ timex_cmp()

int timex_cmp	(	const timex_t	a,
		const timex_t	b
	)

Compares two timex timestamps.

Parameters

[in]	a	The first timestamp to compare to
[in]	b	The second timestamp to compare with

Returns: -1 when a is smaller; 0 if equal; 1 if a is bigger

◆ timex_from_uint64()

static timex_t timex_from_uint64 ( const uint64_t timestamp )

inlinestatic

Converts a 64 bit value of microseconds to a timex timestamp.

Parameters

[in] timestamp The timestamp to convert.

Returns: a timex representation of an uint64 timestamp.

Definition at line 179 of file timex.h.

◆ timex_isnormalized()

static int timex_isnormalized ( const timex_t * time )

inlinestatic

Tests a timex timestamp for normalization.

Parameters

[in] time Pointer to the timestamp to check

Returns: true for a normalized timex_t; false otherwise

Definition at line 155 of file timex.h.

◆ timex_normalize()

static void timex_normalize ( timex_t * time )

inlinestatic

Corrects timex structure so that microseconds < 1000000.

Parameters

[in,out] time Pointer to the timestamp to normalize

Definition at line 141 of file timex.h.

◆ timex_set()

timex_t timex_set	(	uint32_t	seconds,
		uint32_t	microseconds
	)

Initializes a timex timestamp.

Parameters

[in]	seconds	Number of seconds to set
[in]	microseconds	Number of microseconds to set

Returns: The initialized timex timestamp

◆ timex_sub()

timex_t timex_sub	(	const timex_t	a,
		const timex_t	b
	)

Subtracts two timestamps.

Parameters

[in]	a	The minuend
[in]	b	The subtrahend

Returns: The difference a - b

◆ timex_to_str()

const char* timex_to_str	(	timex_t	t,
		char *	timestamp
	)

Converts a timex timestamp to a string.

Precondition: memory at timestamp >= TIMEX_MAX_STR_LEN

Parameters

[in]	t	The timestamp to convert
[out]	timestamp	The output char buffer for the converted timestamp

Note: The timestamp will be normalized

Returns: A pointer to the string representation of the timestamp

◆ timex_uint64()

static uint64_t timex_uint64 ( const timex_t a )

inlinestatic

Converts a timex timestamp to a 64 bit value.

Parameters

[in] a The timestamp to convert

Returns: timex representation as uint64_t

Definition at line 167 of file timex.h.

◆ tm_doomsday()

int tm_doomsday ( int year )

Returns the congruent weekday of the Doomsday (March 0).

Only applies for years in the Gregorian calendar.

Parameters

[in] year The year. Probably should be ≥ 1582, but needs to be ≥ 1.

Returns: The result % 7 is the weekday of the Doomsday of the given year.

◆ tm_fill_derived_values()

void tm_fill_derived_values ( struct tm * tm )

Fills in struct tm::tm_wday and struct tm::tm_yday given a date.

struct tm::tm_year, struct tm::tm_mon, and struct tm::tm_mday need to be set before you call this function.

Parameters

[in,out] tm The datum to operate on.

◆ tm_get_wyday()

void tm_get_wyday	(	int	year,
		int	mon,
		int	mday,
		int *	wday,
		int *	yday
	)

Calculates the day of the year and the weekday of a given date.

Illegal dates are not caught.

Parameters

[in]	year	The year. Probably should be ≥ 1582, but needs to be ≥ 1.
[in]	mon	The month, TM_MON_JAN to TM_MON_DEC.
[in]	mday	The day in the month, 1 to 31.
[out]	wday	Returns the day of the week.
[out]	yday	Returns the day of the year (Jan 1st is 0).

◆ tm_is_leap_year()

int tm_is_leap_year ( unsigned year )

Tells if a given year is a leap year in the Gregorian calendar.

Parameters

[in] year The year. Probably should be ≥ 1582, but needs to be ≥ 1.

Returns: 1 if it is a leap year, 0 if it is a common year.

◆ tm_is_valid_date()

int tm_is_valid_date	(	int	year,
		int	mon,
		int	mday
	)

Tests if a date is valid.

Dates before 1582-10-15 are invalid.

Parameters

[in]	year	The year.
[in]	mon	The month.
[in]	mday	The day in the month.

Returns: 0 if the date is invalid.

◆ tm_is_valid_time()

int tm_is_valid_time	(	int	hour,
		int	min,
		int	sec
	)

Shallow test if a time is valid.

This function accepts leap seconds at any given time, because the timezone is unknown.

Parameters

[in]	hour	The hour.
[in]	min	The minutes.
[in]	sec	The seconds.

Returns: 0 if the time is invalid.

Variable Documentation

◆ TM_MON_DAYS

const int8_t TM_MON_DAYS[12]

The number of days in common years.

See also: http://oeis.org/A008685

◆ TM_MON_DAYS_ACCU

const int16_t TM_MON_DAYS_ACCU[12]

The prefixsum of the number of days in common years.

See also: http://oeis.org/A061251

Detailed Description

Files

Data Structures

Macros

Functions

Variables

Function Documentation

◆ timex_add()

◆ timex_cmp()

◆ timex_from_uint64()

◆ timex_isnormalized()

◆ timex_normalize()

◆ timex_set()

◆ timex_sub()

◆ timex_to_str()

◆ timex_uint64()

◆ tm_doomsday()

◆ tm_fill_derived_values()

◆ tm_get_wyday()

◆ tm_is_leap_year()

◆ tm_is_valid_date()

◆ tm_is_valid_time()

Variable Documentation

◆ TM_MON_DAYS

◆ TM_MON_DAYS_ACCU