Date and Time

Description

Various definitions related to date and time handling.

Times are always represented by the type TTicks and stored in integer units of milliseconds.

Depending on the context, the Home2L suite uses two different clocks, as also supported by the Linux kernel, namely the real time and a monotonic time.

To distinguish between different clocks or relative times, the following terminology is used:

1. An absolute time refers to the number of of milliseconds since the Epoch (1970-01-01-000000 UTC). This clock is used for calendar or alarm clock applications, where the absolute date and time matters. The absolute clock is eventually synchronized via network with time servers to be kept accurate.
2. A monotonic time is relative to some reference time, usually the start of the application. It can never move backwards (as is possible with the absolute clock after network synchronization) and does not make quick changes in speed. The monotonic clock is used for Timers.
3. A relative is either relative to the current time or to some contexct-specific base time.

Besides the basic type TTicks, this group contains some helper types TDate and TTime for calendar time handling.

Collaboration diagram for Date and Time:

Ticks ...
typedef int64_t	TTicks
	Time value (relative, absolute, or monotonic).
TTicks	TicksNow ()
	Get the current absolute time in milliseconds. This function never returns 0 or a negative value.
TTicks	TicksNowMonotonic ()
	Get the current monotonic time in milliseconds. This function never returns 0 or a negative value.
TTicks	TicksAbsFromMonotic (TTicks tm)
	Get the approximated absolute (real) time for a monotonic time. Arguments <= 0 are returned unmodified.
TTicks	TicksMonotonicFromAbs (TTicks ta)
	Get the approximated monotonic time for an absolute time . Arguments <= 0 are returned unmodified.
const char *	TicksAbsToString (CString *ret, TTicks ticks, int fracDigits=INT_MAX, bool precise=false)
	Get a string of the form "YYYY-MM-DD-hhmmss[.<millis>]" in local time. More...
const char *	TicksRelToString (CString *ret, TTicks ticks)
	Get a string of the form "<integer>[<unit>]" for a relative time. More...
bool	TicksFromString (const char *str, TTicks *ret, bool absolute)
	Convert a string to a relative or absolute ticks value. More...
static bool	TicksAbsFromString (const char *str, TTicks *ret)
	Convert a string to an absolute ticks value. See TicksFromString() for supported string formats.
static bool	TicksRelFromString (const char *str, TTicks *ret)
	Convert a string to a relative ticks value. See TicksFromString() for supported string formats.
void	TicksToStructTimeval (TTicks t, struct timeval *retTv)
#define	ASAP   ((TTicks) 0)
	Special value that may represent "as soon as possible" for absolute or monotonic times.
#define	NEVER   ((TTicks) INT64_MIN)
	Special value that may represent "never" for absolute or monotonic times. Other application-specific special values may be defined as (NEVER + 1), (NEVER + 2), ... . The actual value is and will always be < 0.
#define	TICKS_FROM_SECONDS(S)   (((TTicks) (S)) * 1000)
	Convert seconds (integer!) to ticks.
#define	SECONDS_FROM_TICKS(T)   (((TTicks) (T) + 500) / 1000)
	Convert ticks to seconds.
#define	TICKS_FROM_MILLIS(MS)   ((TTicks) (MS))
	Convert milliseconds (integer!) to ticks.
#define	MILLIS_FROM_TICKS(T)   ((int) (T))
	Convert ticks to milliseconds.

Date/time: Types ...
typedef int	TDate
typedef int	TTime
#define	DATE_OF(Y, M, D)   ((TDate) (((Y) << 9) | ((M) << 5) | (D)))
#define	YEAR_OF(DT)   ((int) (DT) >> 9)
#define	MONTH_OF(DT)   (((int) (DT) >> 5) & 0xf)
#define	DAY_OF(DT)   ((int) (DT) & 0x1f)
#define	TIME_OF(H, M, S)   ((TTime) ((H) * 3600 + (M) * 60 + (S)))
#define	HOURS_OF(T)   ((int) (T) / 3600)
#define	MINUTES_OF(T)   ((int) (T) / 60)
#define	HOUR_OF(T)   HOURS_OF(T)
#define	MINUTE_OF(T)   (MINUTES_OF(T) % 60)
#define	SECOND_OF(T)   ((int) (T) % 60)

Conversion between ticks and date/time ...
TTicks	TicksOfDate (int dy, int dm, int dd)
TTicks	TicksOfDate (TDate d)
TTicks	TicksOfTime (int th, int tm, int ts)
TTicks	TicksOfTime (TTime t)
TDate	DateOfTicks (TTicks t)
TTime	TimeOfTicks (TTicks t)
TTicks	DateTimeToTicks (TDate d, TTime t, struct tm *retTm=NULL)
TTicks	DateTimeToTicksUTC (TDate d, TTime t, struct tm *retTm=NULL)
void	TicksToDateTime (TTicks t, TDate *retDate, TTime *retTime, struct tm *retTm=NULL)
void	TicksToDateTimeUTC (TTicks t, TDate *retDate, TTime *retTime, struct tm *retTm=NULL)

Date/time: Current time...
static void	DateTimeNow (TDate *d, TTime *t)
	Retrieve current date and time (both pointers may be NULL)
TDate	Today ()
TTicks	TicksToday ()

Date/time: Arithmetics...
TDate	DateIncByDays (TDate date, int dDays)
int	DateDiffByDays (TDate d1, TDate d0)
TDate	DateIncByMonths (TDate date, int dMon)
static TDate	DateFirstOfMonth (TDate date)
int	GetWeekDay (TDate date)
int	GetCalWeek (TDate date)

Date/time: Written month and weekday names ...
const char *	MonthName (int dm)
	Get textual name. 1 = "January", ..., 12 = "December".
const char *	MonthNameShort (int dm)
	Get textual shortname. 1 = "Jan", ..., 12 = "Dec".
const char *	DayName (int wd)
	Get textual name. 0 = "Monday", ..., 6 = "Sunday".
const char *	DayNameShort (int wd)
	Get textual name. 0 = "Mon", ..., 6 = "Sun".

Function Documentation

TicksAbsToString()

const char* TicksAbsToString	(	CString *	ret,
		TTicks	ticks,
		int	fracDigits = INT_MAX,
		bool	precise = false
	)

Get a string of the form "YYYY-MM-DD-hhmmss[.<millis>]" in local time.

Parameters

ret	Return string
ticks	Ticks to be converted, must be an absolute time
fracDigits	Number of fractional digits. If set to -1, the seconds are skipped, too. If set to 'INT_MAX', the number of (fractional) seconds digits is determined automatically (trailing 0s may be skipped).
precise	If 'true', a string of the form "`t<n>`" is returned, where <n> is the decimal number milliseconds since the Epoch.

TicksRelToString()

const char* TicksRelToString	(	CString *	ret,
		TTicks	ticks
	)

Get a string of the form "<integer>[<unit>]" for a relative time.

Parameters

ret	Return string
ticks	Ticks to be converted

The function guesses an appropriate time unit, e.g. seconds ('s') or minutes ('m') and outputs a string that is precise and at best effort human-readable. This implies that the original value was a multiple of the resulting unit. See TicksFromString () for a list of possible units.

TicksFromString()

bool TicksFromString	(	const char *	str,
		TTicks *	ret,
		bool	absolute
	)

Convert a string to a relative or absolute ticks value.

The following formats are accepted:

• YYYY-MM-DD[-hhmm[ss[.<millis>]]] : readable time, interpreted as local time (only absolute).
• t<unsigned integer> : absolute time in milliseconds since the Epoch (only absolute).
• <integer>[<unit>] : relative time in milliseconds (or some other unit with <unit>); Possible units are: seconds ('s'), minutes ('m'), hours ('h'), days ('d'), and weeks ('w'); If 'absolute == true': time is interpreted as relative from now.
• hh:mm[:ss[.<millis>]] : hh may be > 23 to specify a time in the coming days (Beware of potential race conditions when using this close to midnight!); If 'absolute == true': time relative to 0:00 today.

If 'absolute' is set, an absolute time is returned in any case. Otherwise, the relative number of ticks is returned.

Note: For code readability, this function should not be called directly. Instead, TicksAbsFromString() or TicksRelFromString() should be used.