das_time Struct Reference

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

#include <das3/time.h>

Public Member Functions
DAS_API void	dt_null (das_time *pDt)
	Zero out all values in a das_time structure.
#define	dt_parsetime(S, T)   dt_parsetime((T), (S))
	Convert most human-parseable time strings to numeric components.
DAS_API bool	dt_now (das_time *pDt)
	Initialize a das_time to the current UTC time.
#define	dt_from_1958(D, MS, T)   dt_from_1958((T), (D), (MS))
	Get a das time given days since 1958 and optional milliseconds of day.
DAS_API int64_t	dt_nano_1970 (const das_time *dt)
	Convert a das time to integer nanoseconds since 1970-01-01.
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.
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.
DAS_API int	dt_compare (const das_time *pA, const das_time *pB)
	Compare to dastime structures.
DAS_API double	dt_diff (const das_time *pA, const das_time *pB)
	Get the difference of two das_time structures in seconds.
#define	dt_isoc(B, N, T, F)   dt_isoc((T), (B), (size_t)(N), (F))
	Print an ISOC standard time string given a das_time structure.
#define	dt_isod(B, N, T, F)   dt_isod((T), (B), (size_t)(N), (F))
	Print an ISOD standard time string given a das_time structure.
#define	dt_dual_str(B, N, T, F)   dt_dual_str((T), (B), (size_t)(N), (F))
	Print time a string that provides both day of month and day of year given a das_time structure.
DAS_API double	dt_ttime (const das_time *dt)
	Convert time components to double seconds since January 1st 1958.
#define	dt_emitt(TT, T)   dt_emitt((T), (TT))
	convert double seconds since epoch to time components.
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.

Data Fields
int	year
	Calendar year number, cannot hold years before 1 AD.
int	month
	Calendar month number, 1 = January.
int	mday
	Calendar Day of month, starts at 1.
int	yday
	Integer Day of year, Jan.
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.

Detailed Description

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

In all das routines, 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 structure.

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

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_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 gregorian 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_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 accommodation 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_to_tt2k()

DAS_API int64_t dt_to_tt2k

(

const das_time *

dt

)

Convert a time structure to a TT2000 time.

Returns

nanoseconds since 2000-01-01T11:58:55.816 (TT2000), or ILLEGAL_TT2000_VALUE if the fields can't be converted. No error is raised, compare the result.

dt_from_tt2k()

DAS_API void dt_from_tt2k	(	das_time *	dt,
		int64_t	nTime
	)

Convert a TT2000 time to a time structure.

During a leap second the result's second field is 60.x, which dt_to_tt2k() and dt_isoc() handle but dt_tnorm() does not!

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 carried over into to more significant fields. After calling this function a das_time structure 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.

Not leap second aware. A second of 60.x, as dt_from_tt2k() and Units_convertToDt() return during a leap second, is rolled up into the next minute. Don't normalize a das_time that may hold one.

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.

Normalization functions, dt_ttime() or dt_emit() assume that seconds > 60.0 are not normalized. Thus datetimes returned from TT2000 conversion should not be passed to dt_ttime() or dt_emitt().

---

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

• das3/time.h