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

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

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

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

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

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

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

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

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

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

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

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.

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

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

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

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

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

Macro Definition Documentation

◆ TIMEX_MAX_STR_LEN

#define TIMEX_MAX_STR_LEN (20)

The maximum length of the string representation of a timex timestamp.

Definition at line 34 of file timex.h.

◆ TM_MON_APR

#define TM_MON_APR ( 3)

April in struct tm::tm_mon

Definition at line 39 of file tm.h.

◆ TM_MON_AUG

#define TM_MON_AUG ( 7)

August in struct tm::tm_mon

Definition at line 43 of file tm.h.

◆ TM_MON_DEC

#define TM_MON_DEC (11)

December in struct tm::tm_mon

Definition at line 47 of file tm.h.

◆ TM_MON_FEB

#define TM_MON_FEB ( 1)

February in struct tm::tm_mon

Definition at line 37 of file tm.h.

◆ TM_MON_JAN

#define TM_MON_JAN ( 0)

January in struct tm::tm_mon

Definition at line 36 of file tm.h.

◆ TM_MON_JUL

#define TM_MON_JUL ( 6)

July in struct tm::tm_mon

Definition at line 42 of file tm.h.

◆ TM_MON_JUN

#define TM_MON_JUN ( 5)

June in struct tm::tm_mon

Definition at line 41 of file tm.h.

◆ TM_MON_MAR

#define TM_MON_MAR ( 2)

March in struct tm::tm_mon

Definition at line 38 of file tm.h.

◆ TM_MON_MAY

#define TM_MON_MAY ( 4)

May in struct tm::tm_mon

Definition at line 40 of file tm.h.

◆ TM_MON_NOV

#define TM_MON_NOV (10)

November in struct tm::tm_mon

Definition at line 46 of file tm.h.

◆ TM_MON_OCT

#define TM_MON_OCT ( 9)

October in struct tm::tm_mon

Definition at line 45 of file tm.h.

◆ TM_MON_SEP

#define TM_MON_SEP ( 8)

September in struct tm::tm_mon

Definition at line 44 of file tm.h.

◆ TM_WDAY_FRI

#define TM_WDAY_FRI (5)

Friday in struct tm::tm_wday.

Definition at line 33 of file tm.h.

◆ TM_WDAY_MON

#define TM_WDAY_MON (1)

Monday in struct tm::tm_wday.

Definition at line 29 of file tm.h.

◆ TM_WDAY_SAT

#define TM_WDAY_SAT (6)

Saturday in struct tm::tm_wday.

Definition at line 34 of file tm.h.

◆ TM_WDAY_SUN

#define TM_WDAY_SUN (0)

Sunday in struct tm::tm_wday.

Definition at line 28 of file tm.h.

◆ TM_WDAY_THU

#define TM_WDAY_THU (4)

Thursday in struct tm::tm_wday.

Definition at line 32 of file tm.h.

◆ TM_WDAY_TUE

#define TM_WDAY_TUE (2)

Tuesday in struct tm::tm_wday.

Definition at line 30 of file tm.h.

◆ TM_WDAY_WED

#define TM_WDAY_WED (3)

Wednesday in struct tm::tm_wday.

Definition at line 31 of file tm.h.

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 139 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 115 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 101 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 127 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]

extern

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]

extern

The prefixsum of the number of days in common years.

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

Detailed Description

Files

Data Structures

Macros

Functions

Variables

Macro Definition Documentation

◆ TIMEX_MAX_STR_LEN

◆ TM_MON_APR

◆ TM_MON_AUG

◆ TM_MON_DEC

◆ TM_MON_FEB

◆ TM_MON_JAN

◆ TM_MON_JUL

◆ TM_MON_JUN

◆ TM_MON_MAR

◆ TM_MON_MAY

◆ TM_MON_NOV

◆ TM_MON_OCT

◆ TM_MON_SEP

◆ TM_WDAY_FRI

◆ TM_WDAY_MON

◆ TM_WDAY_SAT

◆ TM_WDAY_SUN

◆ TM_WDAY_THU

◆ TM_WDAY_TUE

◆ TM_WDAY_WED

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