Time definitions and functions

Definitions and functions for related to library time values. More...

Macros
#define	DLTMODULUS   1000000
#define	DLTERROR   -2145916800000000LL
#define	DL_EPOCH2DLTIME(X)   X * (dltime_t) DLTMODULUS
#define	DL_DLTIME2EPOCH(X)   X / DLTMODULUS

Typedefs
typedef int64_t	dltime_t

Functions
char *	dl_dltime2isotimestr (dltime_t dltime, char *isotimestr, int8_t subseconds)
	Generate an ISO time string from a dltime_t.
char *	dl_dltime2mdtimestr (dltime_t dltime, char *mdtimestr, int8_t subseconds)
	Generate an time string in month-day format from a dltime_t.
char *	dl_dltime2seedtimestr (dltime_t dltime, char *seedtimestr, int8_t subseconds)
	Generate an time string in SEED format from a dltime_t.
dltime_t	dl_time2dltime (int year, int day, int hour, int min, int sec, int usec)
	Convert specified time values to a dltime_t value.
dltime_t	dl_seedtimestr2dltime (char *seedtimestr)
	Convert a SEED time string to a dltime_t value.
dltime_t	dl_timestr2dltime (char *timestr)
	Convert a time string to a dltime_t value.
int	dl_doy2md (int year, int jday, int *month, int *mday)
	Compute the month and day-of-month from day-of-year.
int	dl_md2doy (int year, int month, int mday, int *jday)
	Compute the day-of-year from year, month and day-of-month.

Detailed Description

Definitions and functions for related to library time values.

Internally the library uses an integer value to represent time as the number of microseconds since the Unix/POSIX epoch (Jan 1 1970).

Macro Definition Documentation

DLTMODULUS

#define DLTMODULUS   1000000

High precision time tick interval as 1/modulus seconds * Default modulus of 1000000 defines tick interval as a microsecond

DLTERROR

#define DLTERROR   -2145916800000000LL

Error code for routines that normally return a high precision time. The time value corresponds to '1902/1/1 00:00:00.000000' with the default DLTMODULUS

DL_EPOCH2DLTIME

#define DL_EPOCH2DLTIME

(

X

)

X * (dltime_t) DLTMODULUS

Macro to scale a Unix/POSIX epoch time to a high precision time

DL_DLTIME2EPOCH

#define DL_DLTIME2EPOCH

(

X

)

X / DLTMODULUS

Macro to scale a high precision time to a Unix/POSIX epoch time

Typedef Documentation

dltime_t

typedef int64_t dltime_t

Data type for high-precision time values. Require a large (>= 64-bit) integer type

Function Documentation

dl_dltime2isotimestr()

char * dl_dltime2isotimestr	(	dltime_t	dltime,
		char *	isotimestr,
		int8_t	subseconds
	)

Generate an ISO time string from a dltime_t.

Build a time string in ISO recommended format from a high precision epoch time, dltime_t, value.

The provided isostimestr must have enough room for the resulting time string of 27 characters, i.e. '2001-07-29T12:38:00.000000' + NULL.

The 'subseconds' flag controls whenther the sub second portion of the time is included or not.

Parameters

dltime	The dltime_t time value
isotimestr	Returned ISO time string, must have room for 27 characters
subseconds	Flag to control the inclusion of subseconds

Returns

A pointer to the resulting string or NULL on error.

dl_dltime2mdtimestr()

char * dl_dltime2mdtimestr	(	dltime_t	dltime,
		char *	mdtimestr,
		int8_t	subseconds
	)

Generate an time string in month-day format from a dltime_t.

Build a time string in month-day format from a high precision epoch time.

The provided mdtimestr must have enough room for the resulting time string of 27 characters, i.e. '2001-07-29 12:38:00.000000' + NULL.

The 'subseconds' flag controls whenther the sub second portion of the time is included or not.

Parameters

dltime	The dltime_t time value
mdtimestr	Returned time string, must have room for 27 characters
subseconds	Flag to control the inclusion of subseconds

Returns

A pointer to the resulting string or NULL on error.

dl_dltime2seedtimestr()

char * dl_dltime2seedtimestr	(	dltime_t	dltime,
		char *	seedtimestr,
		int8_t	subseconds
	)

Generate an time string in SEED format from a dltime_t.

Build a SEED (day-of-year) time string from a high precision epoch time.

The provided seedtimestr must have enough room for the resulting time string of 25 characters, i.e. '2001,195,12:38:00.000000
'.

The 'subseconds' flag controls whenther the sub second portion of the time is included or not.

Parameters

dltime	The dltime_t time value
seedtimestr	Returned time string, must have room for 25 characters
subseconds	Flag to control the inclusion of subseconds

Returns

A pointer to the resulting string or NULL on error.

dl_time2dltime()

dltime_t dl_time2dltime	(	int	year,
		int	day,
		int	hour,
		int	min,
		int	sec,
		int	usec
	)

Convert specified time values to a dltime_t value.

Convert specified time values to a high precision epoch time, a dltime_t value. The routine will range check all the input parameters.

Parameters

year	Year (1900 - 2100)
day	Day (1 - 366)
hour	Hour (0 - 23)
min	Minute (0 - 59)
sec	Second (0 - 60)
usec	Microsecond (0 - 999999)

Returns

dltime_t time value on success and DLTERROR on error.

dl_seedtimestr2dltime()

dltime_t dl_seedtimestr2dltime

(

char *

seedtimestr

)

Convert a SEED time string to a dltime_t value.

Convert a SEED time string to a high precision epoch time. SEED time format is "YYYY[,DDD,HH,MM,SS.FFFFFF]", the delimiter can be a comma [,], colon [:] or period [.] except for the fractional seconds which must start with a period [.].

The time string can be "short" in which case the omitted values are assumed to be zero (with the exception of DDD which is assumed to be 1): "YYYY,DDD,HH" assumes MM, SS and FFFF are 0. The year is required, otherwise there wouldn't be much for a date.

Ranges are checked for each time value.

Parameters

seedtimestr

SEED time string to convert

Returns

dltime_t time value on success and DLTERROR on error.

dl_timestr2dltime()

dltime_t dl_timestr2dltime

(

char *

timestr

)

Convert a time string to a dltime_t value.

Convert a generic time string to a high precision epoch time. SEED time format is "YYYY[/MM/DD HH:MM:SS.FFFF]", the delimiter can be a dash [-], slash [/], colon [:], or period [.] and between the date and time a 'T' or a space may be used. The fracttional seconds must begin with a period [.].

The time string can be "short" in which case the omitted values are assumed to be zero (with the exception of month and day which are assumed to be 1): "YYYY/MM/DD" assumes HH, MM, SS and FFFF are 0. The year is required, otherwise there wouldn't be much for a date.

Ranges are checked for each time value.

Parameters

timestr

Time string to convert

Returns

dltime_t time value on success and DLTERROR on error.

dl_doy2md()

int dl_doy2md	(	int	year,
		int	jday,
		int *	month,
		int *	mday
	)

Compute the month and day-of-month from day-of-year.

Compute the month and day-of-month from a year and day-of-year.

Year is expected to be in the range 1900-2100, jday is expected to be in the range 1-366, month will be in the range 1-12 and mday will be in the range 1-31.

Parameters

year	Year (1900 - 2100)
jday	Day-of-year, "Julian" day (1 - 366)
month	Returned month (1 - 12)
mday	Returned day-of-month (1 - 31)

Returns

0 on success and -1 on error.

dl_md2doy()

int dl_md2doy	(	int	year,
		int	month,
		int	mday,
		int *	jday
	)

Compute the day-of-year from year, month and day-of-month.

Compute the day-of-year from a year, month and day-of-month.

Year is expected to be in the range 1900-2100, month is expected to be in the range 1-12, mday is expected to be in the range 1-31 and jday will be in the range 1-366.

Parameters

year	Year (1900 - 2100)
month	Month (1 - 12)
mday	Day-of-month (1 - 31)
jday	Returned day-of-year, "Julian" day (1 - 366)

Returns

0 on success and -1 on error.