Basic date-time structure used throughout the Das1 & Das2 utilities. More...

#include <das2/time.h>

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

DAS_API int64_t	dt_to_tt2k (const das_time *dt)
	Convert a time structure to a TT2000 time.

DAS_API void	dt_from_tt2k (das_time *dt, int64_t nTime)
	Convert a TT2000 time to a time structure.

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

Data Fields
int	year
	Calendar year number, cannot hold years before 1 AD.

int	month
	Calendar month number, 1 = January.

int	mday
	Calender Day of month, starts at 1.

int	yday
	Integer Day of year, Jan. More...

int	hour
	Hour of day, range is 0 to 23.

int	minute
	Minute of the hour, range 0 to 59.

double	second
	Second of the minute, range 0.0 to 60.0 - epsilon. More...

Detailed Description

Basic date-time structure used throughout the Das1 & Das2 utilities.

In all das rountines, times are assumed to be UTC. Since we are dealing with spacecraft far from Earth, local time zones are of no consideration in almost all cases.

On 64-bit machines sizeof(das_time) == 24+8 = 32 bytes.

Member Function Documentation

◆ dt_null()

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

◆ dt_parsetime()

DAS_API 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

◆ dt_now()

DAS_API bool dt_now ( das_time * pDt )

Initialize a das_time to the current UTC time.

Note: UTC is not your local time zone.

◆ dt_from_1958()

DAS_API 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

◆ dt_nano_1970()

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

◆ dt_in_range()

DAS_API 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

◆ dt_set()

DAS_API 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

◆ dt_compare()

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

◆ dt_diff()

DAS_API 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

Returns: Time A - Time B in seconds.

◆ dt_isoc()

DAS_API 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

◆ dt_isod()

DAS_API 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

◆ dt_dual_str()

DAS_API 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

◆ dt_ttime()

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

◆ dt_emitt()

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

◆ dt_tnorm()

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

Field Documentation

◆ yday

int yday

Integer Day of year, Jan.

1st = 1.
This field is output only for most Das1 functions see the warning in dt_tnorm()

◆ second

double second

Second of the minute, range 0.0 to 60.0 - epsilon.

Note, there is no provision for leap seconds in the library. All minutes are assumed to have 60 seconds.

The documentation for this struct was generated from the following file:

das2/time.h

Public Member Functions

Data Fields

Detailed Description

Member Function Documentation

◆ dt_null()

◆ dt_parsetime()

◆ dt_now()

◆ dt_from_1958()

◆ dt_nano_1970()

◆ dt_in_range()

◆ dt_set()

◆ dt_compare()

◆ dt_diff()

◆ dt_isoc()

◆ dt_isod()

◆ dt_dual_str()

◆ dt_ttime()

◆ dt_emitt()

◆ dt_tnorm()

Field Documentation

◆ yday

◆ second