CODA Time

Functions
int	coda_time_double_to_parts (double datetime, int *year, int *month, int *day, int *hour, int *minute, int *second, int *musec)
int	coda_time_double_to_parts_utc (double datetime, int *year, int *month, int *day, int *hour, int *minute, int *second, int *musec)
int	coda_time_parts_to_double (int year, int month, int day, int hour, int minute, int second, int musec, double *datetime)
int	coda_time_parts_to_double_utc (int year, int month, int day, int hour, int minute, int second, int musec, double *datetime)
int	coda_time_parts_to_string (int year, int month, int day, int hour, int minute, int second, int musec, const char *format, char *str)
int	coda_time_string_to_parts (const char *format, const char *str, int *year, int *month, int *day, int *hour, int *minute, int *second, int *musec)
int	coda_time_double_to_string (double datetime, const char *format, char *str)
int	coda_time_double_to_string_utc (double datetime, const char *format, char *str)
int	coda_time_string_to_double (const char *format, const char *str, double *datetime)
int	coda_time_string_to_double_utc (const char *format, const char *str, double *datetime)

Detailed Description

The CODA Time module contains all functions and procedures related to time handling.

Most of the time functions assume that you stay within the same time system. In CODA a single time value can be represented in three different forms and CODA provides functions to convert between them:

• as a floating point value indicating the amount of seconds since 2000-01-01 00:00:00.00000 (this Jan 1st 2000 is an 'epoch' in the same time system as your time value is in)
• as a decomposition of individual year, month, day, hour, minute, second, and microsecond values.
• as a string (e.g. "2005-04-03 02:01:00.00000").

The problem is that most time values are provided using the UTC time system. However, because of leap seconds, the only valid representations for a UTC time value are the last two. The problem with the floating point representation is that there is no unique definition of the Jan 1st 2000 epoch. Whenever a leap second is introduced this also shifts the epoch by one second. For instance, you cannot calculate the difference in seconds between UTC 2006-01-02 00:00:00 and UTC 2005-12-30 00:00:00 by just subtracting the two floating point representations of those times because of the leap second at 2005-12-31 23:59:60. If you would just subtract the values you would get 172800 seconds, but the actual answer should be 172801 seconds. If you want to calculate leap-second-accurate time differences the only solution is to convert your UTC time values to a time system that is based on actual clock ticks such as TAI or GPS.

In CODA this problem is solved by introducing special UTC leap-second-aware functions for converting from a floating point value to a string or datetime decomposition (and vice versa). The floating point value is in TAI whereas the string and datetime decomposition values represent the time value in UTC (be aware that the value for 'amount of seconds in a minute' can range from 0 to 60 inclusive for UTC!)

For each public time function there are thus two variants. One that treats all days as having 86400 seconds (and where both the input(s) and output(s) are of the same time system) and one that is able to deal with leap seconds. The functions that deal with leap seconds have 'utc' in the name and assume that the number of seconds since 2000-01-01 is a value in the TAI time system whereas the datetime decomposition (or string value) is using the UTC time system.

Note that TAI does not really have a fixed epoch relative to which to provide a number of seconds. TAI is only represented in how it deviates from UTC. In CODA, the choice was made to base the offset for the TAI floating point values on the convention that 2000-01-01T00:00:00 UTC has an offset of 0 (in UTC). Since at that time TAI was 32 seconds ahead of UTC, coda_utcdatetime_to_double() (which converts UTC to TAI) will thus return the value 32 for 2000-01-01T00:00:00.

If you don't want to use an actual TAI floating point value, but just an amount of seconds since 2000-01-01T00:00:00 UTC (i.e. such that a leap-second aware coversion of 2000-01-01T00:00:00 to a floating point value will actually result in 0), the best approach is to just subtract the result of coda_utcdatetime_to_double(2000,1,1,0,0,0,0,...) from your other result of coda_utcdatetime_to_double(). Note that this is more robust than assuming the epoch difference is always 32 and it is also an approach that can be applied more generally to retrieve a number of seconds relative to any other UTC date.

Below is an overview of time systems that are commonly used:

• TAI: International Atomic Time scale International Atomic Time (TAI) represents the mean of readings of several atomic clocks, and its fundamental unit is exactly one SI second at mean sea level and is, therefore, constant and continuous. d TAI = TAI - UTC is the increment to be applied to UTC to give TAI.
• UTC: Coordinated Universal Time The time system generally used is the Coordinated Universal Time (UTC), previously called Greenwich Mean Time. The UTC is piece wise uniform and continuous, i.e. the time difference between UTC and TAI is equal to an integer number of seconds and is constant except for occasional jumps from inserted integer leap seconds. The leap seconds are inserted to cause UTC to follow the rotation of the Earth, which is expressed by means of the non uniform time reference Universal Time UT1. If UT1 is predicted to lag behind UTC by more than 0.9 seconds, a leap second is inserted. CODA has a built-in table of leap seconds up to 2012-07-01. You can use a more recent table by downloading the recent list of leap seconds from ftp://maia.usno.navy.mil/ser7/tai-utc.dat and set the environment variable CODA_LEAP_SECOND_TABLE with a full path to this file.
• UT1: Universal Time Universal Time (UT1) is a time reference that conforms, within a close approximation, to the mean diurnal motion of the Earth. It is determined from observations of the diurnal motions of the stars, and then corrected for the shift in the longitude of the observing stations caused by the polar motion.
• GPS: GPS Time GPS Time is an atomic clock time similar to but not the same as UTC time. It is synchronised to UTC but the main difference relies in the fact that GPS time does not introduce any leap second. Thus, the introduction of UTC leap second causes the GPS time and UTC time to differ by a known integer number of cumulative leap seconds; i.e. the leap seconds that have been accumulated since GPS epoch in midnight January 5, 1980. d GPS = TAI - GPS is the increment to be applied to GPS to give TAI, being a constant value of 19 seconds.

Function Documentation

coda_time_double_to_parts()

int coda_time_double_to_parts	(	double	datetime,
		int *	year,
		int *	month,
		int *	day,
		int *	hour,
		int *	minute,
		int *	second,
		int *	musec )

Retrieve the decomposed date corresponding with the given amount of seconds since Jan 1st 2000.

Warning

This function does not perform any leap second correction. The returned value is just a straightforward conversion using 86400 seconds per day.

Parameters

datetime	The amount of seconds since Jan 1st 2000.
year	Pointer to the variable where the year will be stored.
month	Pointer to the variable where the month of the year (1 - 12) will be stored.
day	Pointer to the variable where the day of the month (1 - 31) will be stored.
hour	Pointer to the variable where the hour of the day (0 - 23) will be stored.
minute	Pointer to the variable where the minute of the hour (0 - 59) will be stored.
second	Pointer to the variable where the second of the minute (0 - 59) will be stored.
musec	Pointer to the variable where the microseconds of the second (0 - 999999) will be stored.

Returns

• 0, Success.
• -1, Error occurred (check coda_errno).

coda_time_double_to_parts_utc()

int coda_time_double_to_parts_utc	(	double	datetime,
		int *	year,
		int *	month,
		int *	day,
		int *	hour,
		int *	minute,
		int *	second,
		int *	musec )

Retrieve the decomposed UTC date corresponding with the given amount of TAI seconds since Jan 1st 2000. This function assumes the input to by the number of seconds since 2000-01-01 in the TAI system. The returned date/time components will be the corresponding UTC datetime (using proper leap second handling for the TAI to UTC conversion). For example: -88361290 will be 1972-01-01 00:00:00 UTC 0 will be 1999-31-12 23:59:28 UTC 284083232 will be 2008-12-31 23:59:59 UTC 284083233 will be 2008-12-31 23:59:60 UTC 284083234 will be 2009-01-01 00:00:00 UTC

Warning

For dates before 1972-01-01 UTC a fixed leap second offset of 10 is used.

Note

CODA has a built in table of leap seconds. To use a more recent leap second table, download the most recent file from ftp://maia.usno.navy.mil/ser7/tai-utc.dat and set the environment variable CODA_LEAP_SECOND_TABLE with a full path to this file.

Parameters

datetime	The amount of seconds since Jan 1st 2000.
year	Pointer to the variable where the year will be stored.
month	Pointer to the variable where the month of the year (1 - 12) will be stored.
day	Pointer to the variable where the day of the month (1 - 31) will be stored.
hour	Pointer to the variable where the hour of the day (0 - 23) will be stored.
minute	Pointer to the variable where the minute of the hour (0 - 59) will be stored.
second	Pointer to the variable where the second of the minute (0 - 60) will be stored.
musec	Pointer to the variable where the microseconds of the second (0 - 999999) will be stored.

Returns

• 0, Success.
• -1, Error occurred (check coda_errno).

coda_time_double_to_string()

int coda_time_double_to_string	(	double	datetime,
		const char *	format,
		char *	str )

Convert a floating point time value to a string using a specified format. The string will be formatted using the format that is provided as second parameter. The time string will be stored in the str parameter. This parameter should be allocated by the user and should be long enough to hold the formatted time string and a 0 termination character.

The specification for the time format parameter is the same as the date/time format patterns in coda expressions.

Warning

This function does not perform any leap second correction.

Parameters

datetime	Floating point value representing the number of seconds since January 1st, 2000 00:00:00.000000.
format	Date/time format to use for the string representation of the datetime value.
str	String representation of the floating point time value.

Returns

• 0, Success.
• -1, Error occurred (check coda_errno).

coda_time_double_to_string_utc()

int coda_time_double_to_string_utc	(	double	datetime,
		const char *	format,
		char *	str )

Convert a floating point TAI time value to a UTC string. The string will be formatted using the format that is provided as second parameter. The time string will be stored in the str parameter. This parameter should be allocated by the user and should be long enough to hold the formatted time string and a 0 termination character.

The specification for the time format parameter is the same as the date/time format patterns in coda expressions.

This function performs proper leap second correction in the conversion from TAI to UTC (see also coda_time_double_to_parts_utc()).

Parameters

datetime	Floating point value representing the number of seconds since January 1st, 2000 00:00:00.000000.
format	Date/time format to use for the string representation of the datetime value.
str	String representation of the floating point time value.

Returns

• 0, Success.
• -1, Error occurred (check coda_errno).

coda_time_parts_to_double()

int coda_time_parts_to_double	(	int	year,
		int	month,
		int	day,
		int	hour,
		int	minute,
		int	second,
		int	musec,
		double *	datetime )

Retrieve the number of seconds since Jan 1st 2000 for a certain date and time.

Warning

This function does not perform any leap second correction. The returned value is just a straightforward conversion using 86400 seconds per day.

Parameters

year	The year.
month	The month of the year (1 - 12).
day	The day of the month (1 - 31).
hour	The hour of the day (0 - 23).
minute	The minute of the hour (0 - 59).
second	The second of the minute (0 - 59).
musec	The microseconds of the second (0 - 999999).
datetime	Pointer to the variable where the amount of seconds since Jan 1st 2000 will be stored.

Returns

• 0, Success.
• -1, Error occurred (check coda_errno).

coda_time_parts_to_double_utc()

int coda_time_parts_to_double_utc	(	int	year,
		int	month,
		int	day,
		int	hour,
		int	minute,
		int	second,
		int	musec,
		double *	datetime )

Retrieve the number of TAI seconds since Jan 1st 2000 for a certain UTC date and time using leap second correction. This function assumes the input to be an UTC datetime. The returned value will be the seconds since 2000-01-01 in the TAI time system (using proper leap second handling for the UTC to TAI conversion). For example: 1972-01-01 00:00:00 UTC will be -883612790 2000-01-01 00:00:00 UTC will be 32 2008-12-31 23:59:59 UTC will be 284083232 2008-12-31 23:59:60 UTC will be 284083233 2009-01-01 00:00:00 UTC will be 284083234

Warning

For dates before 1972-01-01 UTC a fixed leap second offset of 10 is used.

Note

CODA has a built in table of leap seconds. To use a more recent leap second table, download the most recent file from ftp://maia.usno.navy.mil/ser7/tai-utc.dat and set the environment variable CODA_LEAP_SECOND_TABLE with a full path to this file.

Parameters

year	The year.
month	The month of the year (1 - 12).
day	The day of the month (1 - 31).
hour	The hour of the day (0 - 23).
minute	The minute of the hour (0 - 59).
second	The second of the minute (0 - 60).
musec	The microseconds of the second (0 - 999999).
datetime	Pointer to the variable where the amount of seconds since Jan 1st 2000 will be stored.

Returns

• 0, Success.
• -1, Error occurred (check coda_errno).

coda_time_parts_to_string()

int coda_time_parts_to_string	(	int	year,
		int	month,
		int	day,
		int	hour,
		int	minute,
		int	second,
		int	musec,
		const char *	format,
		char *	str )

Create a string representation for a specific data and time. The string will be formatted using the format that is provided as first parameter. The time string will be stored in the str parameter. This parameter should be allocated by the user and should be long enough to hold the formatted time string and a 0 termination character.

The specification for the time format parameter is the same as the date/time format patterns in coda expressions.

Warning

This function does not perform any leap second correction.

Parameters

year	The year.
month	The month of the year (1 - 12).
day	The day of the month (1 - 31).
hour	The hour of the day (0 - 23).
minute	The minute of the hour (0 - 59).
second	The second of the minute (0 - 60).
musec	The microseconds of the second (0 - 999999).
format	Date/time format to use for the string representation of the datetime value.
str	String representation of the given date and time.

Returns

• 0, Success.
• -1, Error occurred (check coda_errno).

coda_time_string_to_double()

int coda_time_string_to_double	(	const char *	format,
		const char *	str,
		double *	datetime )

Convert a time string to a floating point time value. The string will be parsed using the format that is provided as first parameter. This can be a '|' separated list of formats that will be tried in sequence until one succeeds.

The specification for the time format parameter is the same as the date/time format patterns in coda expressions.

Warning

This function does not perform any leap second correction.

Parameters

format	String containing the datetime format(s) to use for parsing the datetime value.
str	String containing the time in one of the supported formats.
datetime	Floating point value representing the number of seconds since January 1st, 2000 00:00:00.000000.

Returns

• 0, Success.
• -1, Error occurred (check coda_errno).

coda_time_string_to_double_utc()

int coda_time_string_to_double_utc	(	const char *	format,
		const char *	str,
		double *	datetime )

Convert a UTC time string to a TAI floating point time value. The string will be parsed using the format that is provided as first parameter. This can be a '|' separated list of formats that will be tried in sequence until one succeeds.

The specification for the time format parameter is the same as the date/time format patterns in coda expressions.

This function performs proper leap second correction in the conversion from UTC to TAI (see also coda_time_parts_to_double_utc()).

Parameters

format	String containing the datetime format(s) to use for parsing the datetime value.
str	String containing the time in one of the supported formats.
datetime	Floating point value representing the number of seconds since January 1st, 2000 00:00:00.000000.

Returns

• 0, Success.
• -1, Error occurred (check coda_errno).

coda_time_string_to_parts()

int coda_time_string_to_parts	(	const char *	format,
		const char *	str,
		int *	year,
		int *	month,
		int *	day,
		int *	hour,
		int *	minute,
		int *	second,
		int *	musec )

Convert a time string to a date and time using a specified format. The string will be parsed using the format that is provided as first parameter. This can be a '|' separated list of formats that will be tried in sequence until one succeeds.

The specification for the time format parameter is the same as the date/time format patterns in coda expressions.

Warning

This function does not perform any leap second correction.

Parameters

format	String containing the datetime format(s) to use for parsing the datetime value.
str	String containing the time in one of the supported formats.
year	Pointer to the variable where the year will be stored.
month	Pointer to the variable where the month of the year (1 - 12) will be stored.
day	Pointer to the variable where the day of the month (1 - 31) will be stored.
hour	Pointer to the variable where the hour of the day (0 - 23) will be stored.
minute	Pointer to the variable where the minute of the hour (0 - 59) will be stored.
second	Pointer to the variable where the second of the minute (0 - 59) will be stored.
musec	Pointer to the variable where the microseconds of the second (0 - 999999) will be stored.

Returns

• 0, Success.
• -1, Error occurred (check coda_errno).