Timex

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]aFirst summand
[in]bSecond 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]aThe first timestamp to compare to
[in]bThe 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]timestampThe 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]timePointer 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]timePointer 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]secondsNumber of seconds to set
[in]microsecondsNumber 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]aThe minuend
[in]bThe 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]tThe timestamp to convert
[out]timestampThe 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]aThe 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]yearThe 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]tmThe 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]yearThe year. Probably should be ≥ 1582, but needs to be ≥ 1.
[in]monThe month, TM_MON_JAN to TM_MON_DEC.
[in]mdayThe day in the month, 1 to 31.
[out]wdayReturns the day of the week.
[out]ydayReturns 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]yearThe 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]yearThe year.
[in]monThe month.
[in]mdayThe 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]hourThe hour.
[in]minThe minutes.
[in]secThe 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