Parsing and converting calendar dates and times. More...

Detailed Description

Parsing and converting calendar dates and times.

Data Structures
struct	das_time
	Basic date-time structure used throughout the Das1 & Das2 utilities. More...

Functions
void	dt_null (das_time *pDt)
	Zero out all values in a das_time structrue. More...

bool	dt_now (das_time *pDt)
	Initialize a das_time to the current UTC time. More...

bool	dt_parsetime (const char string, das_time dt)
	Convert most human-parseable time strings to numeric components. More...

void	dt_from_1958 (unsigned short int daysSince1958, unsigned int msOfDay, das_time *dt)
	Get a das time given days since 1958 and optional milliseconds of day. More...

int64_t	dt_nano_1970 (const das_time *dt)
	Convert a das time to integer nanoseconds since 1970-01-01. More...

bool	dt_in_range (const das_time begin, const das_time end, const das_time *test)
	Test for time within a time range The the standard exclusive upper bound test. More...

void	dt_copy (das_time pDest, const das_time pSrc)
	Simple helper to copy values from one das time to another.

void	dt_set (das_time *pDt, int year, int month, int mday, int yday, int hour, int minute, double second)
	Simple helper to set values in a das time. More...

int	dt_compare (const das_time pA, const das_time pB)
	Compare to dastime structures. More...

double	dt_diff (const das_time pA, const das_time pB)
	Get the difference of two das_time structures in seconds. More...

char *	dt_isoc (char sBuf, size_t nLen, const das_time pDt, int nFracSec)
	Print an ISOC standard time string given a das_time structure. More...

char *	dt_isod (char sBuf, size_t nLen, const das_time pDt, int nFracSec)
	Print an ISOD standard time string given a das_time structure. More...

char *	dt_dual_str (char sBuf, size_t nLen, const das_time pDt, int nFracSec)
	Print time a string that provides both day of month and day of year given a das_time structure. More...

double	dt_ttime (const das_time *dt)
	Convert time components to double seconds since January 1st 1958. More...

void	dt_emitt (double tt, das_time *dt)
	convert double seconds since epoch to time components. More...

void	dt_tnorm (das_time *dt)
	Normalize date and time components. More...

Function Documentation

void dt_null ( das_time * pDt )

Zero out all values in a das_time structrue.

Note, the resulting das_time is an invalid time, not a zero point.

bool dt_now ( das_time * pDt )

Initialize a das_time to the current UTC time.

Note: UTC is not your local time zone.

bool dt_parsetime	(	const char *	string,
		das_time *	dt
	)

Convert most human-parseable time strings to numeric components.

Parameters

string	- the string to convert to a numeric time
dt	- a pointer to the das_time structure to initialize

Returns: true on success and false on failure

void dt_from_1958	(	unsigned short int	daysSince1958,
		unsigned int	msOfDay,
		das_time *	dt
	)

Get a das time given days since 1958 and optional milliseconds of day.

This format is common for many older spacecraft missions

int64_t dt_nano_1970 ( const das_time * dt )

Convert a das time to integer nanoseconds since 1970-01-01.

Parameters

dt	a das time
pDays	days since Jan. 1st 1970 at midnight
pFrac	fraction of a day.

bool dt_in_range	(	const das_time *	begin,
		const das_time *	end,
		const das_time *	test
	)

Test for time within a time range The the standard exclusive upper bound test.

Parameters

begin	The beginning time point for the range
end	The ending time point for the range
test	The test time

Returns: true if begin <= test and test < end, false otherwise

void dt_set	(	das_time *	pDt,
		int	year,
		int	month,
		int	mday,
		int	yday,
		int	hour,
		int	minute,
		double	second
	)

Simple helper to set values in a das time.

Warning: This function does not cal tnorm, so you can use it to set invalid das times

int dt_compare	(	const das_time *	pA,
		const das_time *	pB
	)

Compare to dastime structures.

Since we can't overload the numerical comparison operators in C, you you get this function

Parameters

pA	a pointer to a das_time structure
pB	a pointer to a das_time structure

Returns: an integer less than 0 if *pA is less that *pB, 0 if *pA is equal to *pB and greater than 0 if *pA is greater than *pB.

double dt_diff	(	const das_time *	pA,
		const das_time *	pB
	)

Get the difference of two das_time structures in seconds.

Handle time subtractions in a way that is sensitive to small differences. Thus, do not go out to tnorm and back.

Time difference in seconds is returned. This method should be valid as long as you are using the gegorian calendar, but doesn't account for leap seconds.

Credit: http://stackoverflow.com/questions/12862226/the-implementation-of-calculating-the-number-of-days-between-2-dates

char * dt_isoc	(	char *	sBuf,
		size_t	nLen,
		const das_time *	pDt,
		int	nFracSec
	)

Print an ISOC standard time string given a das_time structure.

The output has the format:

yyyy-mm-ddThh:mm:ss[.sssss]

Where the number of fractional seconds digits to print is variable and may be set to 0

Parameters

sBuf	the buffer to hold the output
nLen	the length of the output buffer
pDt	the dastime to print
nFracSec	the number of fractional seconds digits in the output must be a number from 0 to 15 inclusive

char * dt_isod	(	char *	sBuf,
		size_t	nLen,
		const das_time *	pDt,
		int	nFracSec
	)

Print an ISOD standard time string given a das_time structure.

The output has the format:

yyyy-dddThh:mm:ss[.sssss]

Where the number of fractional seconds digits to print is variable and may be set to 0

Parameters

sBuf	the buffer to hold the output
nLen	the length of the output buffer
pDt	the dastime to print
nFracSec	the number of fractional seconds digits in the output must be a number from 0 to 15 inclusive

char * dt_dual_str	(	char *	sBuf,
		size_t	nLen,
		const das_time *	pDt,
		int	nFracSec
	)

Print time a string that provides both day of month and day of year given a das_time structure.

The output has the format:

yyyy-mm-dd (ddd) hh:mm:ss[.sssss]

Where the number of fractional seconds digits to print is variable and may be set to 0

Parameters

sBuf	the buffer to hold the output
nLen	the length of the output buffer
pDt	the dastime to print
nFracSec	the number of fractional seconds digits in the output must be a number from 0 to 15 inclusive

double dt_ttime ( const das_time * dt )

Convert time components to double seconds since January 1st 1958.

converts time components to a double precision floating point value (seconds since the beginning of 1958, ignoring leap seconds) and normalize inputs. Note that this floating point value should only be used for "internal" purposes. (There's no need to propagate yet another time system, plus I want to be able to change/fix these values.)

There is no accomodation for calendar adjustments, for example the transition from Julian to Gregorian calendar, so I wouldn't recommend using these routines for times prior to the 1800's. Sun IEEE 64-bit floating point preserves millisecond accuracy past the year 3000. For various applications, it may be wise to round to nearest millisecond (or microsecond, etc.) after the value is returned.

void dt_emitt	(	double	tt,
		das_time *	dt
	)

convert double seconds since epoch to time components.

emitt (ttime backwards) converts double precision seconds (since the beginning of 1958, ignoring leap seconds) to date and time components.

void dt_tnorm ( das_time * dt )

Normalize date and time components.

Call this function after manipulating time structure values directly to insure that any overflow or underflow from various fields are caried over into to more significant fields. After calling this function a das_time sturcture is again normalized into a valid date-time.

Warning: The das_time.yday member is OUTPUT only. To add a day to a time, increment mday as much as needed and then call tnorm.

Detailed Description

Data Structures

Functions

Function Documentation