Main Page   Modules  

Functions
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:

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:

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
datetimeThe amount of seconds since Jan 1st 2000.
yearPointer to the variable where the year will be stored.
monthPointer to the variable where the month of the year (1 - 12) will be stored.
dayPointer to the variable where the day of the month (1 - 31) will be stored.
hourPointer to the variable where the hour of the day (0 - 23) will be stored.
minutePointer to the variable where the minute of the hour (0 - 59) will be stored.
secondPointer to the variable where the second of the minute (0 - 59) will be stored.
musecPointer 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
datetimeThe amount of seconds since Jan 1st 2000.
yearPointer to the variable where the year will be stored.
monthPointer to the variable where the month of the year (1 - 12) will be stored.
dayPointer to the variable where the day of the month (1 - 31) will be stored.
hourPointer to the variable where the hour of the day (0 - 23) will be stored.
minutePointer to the variable where the minute of the hour (0 - 59) will be stored.
secondPointer to the variable where the second of the minute (0 - 60) will be stored.
musecPointer 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
datetimeFloating point value representing the number of seconds since January 1st, 2000 00:00:00.000000.
formatDate/time format to use for the string representation of the datetime value.
strString 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
datetimeFloating point value representing the number of seconds since January 1st, 2000 00:00:00.000000.
formatDate/time format to use for the string representation of the datetime value.
strString 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
yearThe year.
monthThe month of the year (1 - 12).
dayThe day of the month (1 - 31).
hourThe hour of the day (0 - 23).
minuteThe minute of the hour (0 - 59).
secondThe second of the minute (0 - 59).
musecThe microseconds of the second (0 - 999999).
datetimePointer 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
yearThe year.
monthThe month of the year (1 - 12).
dayThe day of the month (1 - 31).
hourThe hour of the day (0 - 23).
minuteThe minute of the hour (0 - 59).
secondThe second of the minute (0 - 60).
musecThe microseconds of the second (0 - 999999).
datetimePointer 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
yearThe year.
monthThe month of the year (1 - 12).
dayThe day of the month (1 - 31).
hourThe hour of the day (0 - 23).
minuteThe minute of the hour (0 - 59).
secondThe second of the minute (0 - 60).
musecThe microseconds of the second (0 - 999999).
formatDate/time format to use for the string representation of the datetime value.
strString 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
formatString containing the datetime format(s) to use for parsing the datetime value.
strString containing the time in one of the supported formats.
datetimeFloating 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
formatString containing the datetime format(s) to use for parsing the datetime value.
strString containing the time in one of the supported formats.
datetimeFloating 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
formatString containing the datetime format(s) to use for parsing the datetime value.
strString containing the time in one of the supported formats.
yearPointer to the variable where the year will be stored.
monthPointer to the variable where the month of the year (1 - 12) will be stored.
dayPointer to the variable where the day of the month (1 - 31) will be stored.
hourPointer to the variable where the hour of the day (0 - 23) will be stored.
minutePointer to the variable where the minute of the hour (0 - 59) will be stored.
secondPointer to the variable where the second of the minute (0 - 59) will be stored.
musecPointer to the variable where the microseconds of the second (0 - 999999) will be stored.
Returns
  • 0, Success.
  • -1, Error occurred (check coda_errno).