das_time_t Struct Reference

#include <das2/das1.h>

---

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.

Public Member Functions
bool	dt_parsetime (const char *string, das_time_t *dt)
	Convert most human-parseable time strings to numeric components.
void	dt_from_1958 (unsigned short int daysSince1958, unsigned int msOfDay, das_time_t *dt)
	Get a das time given days since 1958 and optional milliseconds of day.
bool	dt_in_range (const das_time_t *begin, const das_time_t *end, const das_time_t *test)
	Test for time within a time range The the standard exclusive upper bound test.
void	dt_copy (das_time_t *pDest, const das_time_t *pSrc)
	Simple helper to copy values from one das time to another.
void	dt_set (das_time_t *pDt, int year, int month, int mday, int yday, int hour, int minute, double second)
	Simple helper to set values in a das time.
int	dt_compare (const das_time_t *pA, const das_time_t *pB)
	Compare to dastime structures.
double	dt_diff (const das_time_t *pA, const das_time_t *pB)
	Get the difference of two das_time_t structures in seconds.
char *	dt_isoc (char *sBuf, size_t nLen, const das_time_t *pDt, int nFracSec)
	Print an ISOC standard time string given a das_time_t structure.
char *	dt_isod (char *sBuf, size_t nLen, const das_time_t *pDt, int nFracSec)
	Print an ISOD standard time string given a das_time_t structure.
char *	dt_dual_str (char *sBuf, size_t nLen, const das_time_t *pDt, int nFracSec)
	Print time a string that provides both day of month and day of year given a das_time_t structure.
double	dt_ttime (const das_time_t *dt)
	Convert time components to double seconds since January 1st 1958.
void	dt_emitt (double tt, das_time_t *dt)
	convert double seconds since epoch to time components.
void	dt_tnorm (das_time_t *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
	Calender 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, range 0.0 to 60.0 - epsilon.

---

Member Function Documentation

bool dt_parsetime	(	const char *	string,
		das_time_t *	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_t *	dt
	)

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

This format is common for many older spacecraft missions

bool dt_in_range	(	const das_time_t *	begin,
		const das_time_t *	end,
		const das_time_t *	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_t *	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_t *	pA,
		const das_time_t *	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_t structure
	pB	a pointer to a das_time_t 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_t *	pA,
		const das_time_t *	pB
	)

Get the difference of two das_time_t 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_t *	pDt,
		int	nFracSec
	)

Print an ISOC standard time string given a das_time_t 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_t *	pDt,
		int	nFracSec
	)

Print an ISOD standard time string given a das_time_t 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_t *	pDt,
		int	nFracSec
	)

Print time a string that provides both day of month and day of year given a das_time_t 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_t *

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_t *	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_t *

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_t.yday member is OUTPUT only. To add a day to a time, increment mday as much as needed and then call tnorm.

---

Field Documentation

int das_time_t::yday

Integer Day of year, Jan.

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

double das_time_t::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/das1.h