Parsing Dates and Times

Top  Previous  Next

This page covers the FreeFlyer features for working with dates and times. For related topics, see the TimeSpans page and the Timing Precision Modes page.

 

Handling Calendar Epochs

TimeTools

Epoch Systems

Reference Dates

Date and Time Format Specifiers

 

Note: All epochs that are specified with a numeric value are treated as TAI by default, and all epochs that are specified with strings are UTC by default.

 

Handling Calendar Epochs


FreeFlyer provides the TimeSpan.ConvertToCalendarDate() and String.ParseCalendarDate() methods for easily converting epochs between a numerical value and a calendar-formatted string.

 

TimeSpan epochValue = TimeSpan.FromDays(25197.5);

Report   epochValue.ConvertToCalendarDate(); // Returns: "Dec 31 2009 23:59:26.000000000"

 

String epochString = "Dec 31 2009 23:59:26.000";

Report epochString.ParseCalendarDate();      // Returns: 25197.5

 

These methods also allow you to specify custom calendar date formats, and you can embed text within the date/time format using double asterisks, as shown below:

 

TimeSpan epochValue = TimeSpan.FromDays(25197.5);

Report epochValue.ConvertToCalendarDate("**Date is:** D Mmmm YY");          // Returns: "Date is: 31 December 09"

 

String epochString = "Timestamp = 5 Mar 17 11:59:23";

Report epochString.ParseCalendarDate("**Timestamp =** D Mmm YY hh:mm:ss");  // Returns: 27818

 

The TimeTools object discussed below provides many additional time conversion utilities.

 

Note: As of FreeFlyer 7.3, the default timing precision mode is nanosecond precision mode. For older Mission Plans that have not yet been converted from millisecond precision mode, the syntax for working with epochs and calendar date/time strings is different. A few samples are shown below; see the timing precision mode page for more information.

 

Variable epochValue = 25197.5;

Report   epochValue.EpochFormat(); // Returns: "Dec 31 2009 23:59:26.000"

 

String epochString = "Dec 31 2009 23:59:26.000";

Report epochString.EpochScan();    // Returns: 25197.5

 

 

TimeTools


The TimeTools object allows the user to convert epochs to different time systems, convert between numerical time values and calendar-formatted strings, handle time zones, and check for special circumstances like leap years and daylight savings time.

 

The examples below use the following objects:

 

TimeSpan epoch = TimeSpan.FromDays(25988);

TimeSpan timeinterval = TimeSpan.FromDays(0.5);

 

TimeTools examples:

 

Method

Purpose

Example

Example Output

ConvertTime

To convert time to a different system.

Report TimeTools.ConvertTime(epoch, "TAI""MJD GSFC""GPS""MJD GSFC");

25987.999780093

ConvertToCalendarDate

To convert a time value to a calendar date.

Report TimeTools.ConvertToCalendarDate(epoch, "TAI""MJD GSFC");

Mar 01 2012 12:00:00.000

ConvertToLocalCalendarDate

To convert a time value to a calendar date in a local time zone.

Report TimeTools.ConvertToLocalCalendarDate(epoch, "TAI""MJD GSFC", 5 /*UTC-8:00*/);

Mar 01 2012 03:59:26.000

GetGPSWeekAndSecondsOfWeek

To convert a time value to the GPS week number and seconds of the week.

Report TimeTools.GetGPSWeekAndSecondsOfWeek(epoch, "TAI""MJD GSFC", 0);

{ 1677, 388781}

IsInDaylightSavings

To determine if an epoch is in daylight savings.

Report TimeTools.IsInDaylightSavings(epoch, "TAI""MJD GSFC");

0

IsInLeapYear

To determine if an epoch is in a leap year.

Report TimeTools.IsInLeapYear(epoch, "TAI""MJD GSFC");

1

ParseCalendarDate

To parse a calendar date and get its value.

Report TimeTools.ParseCalendarDate("Jan 10 2008 00:00:00.000""UTC""UT1""MJD GSFC");

24475.499996759

ParseLocalCalendarDate

To parse a calendar date in a local time zone and get its value.

Report TimeTools.ParseLocalCalendarDate("Mar 01 2012 04:00:00.000", 5 /*UTC-8:00*/"TAI","MJD GSFC");

25988.000393519

ParseTimeInterval

To parse a time interval String into a value.

Report TimeTools.ParseTimeInterval("12:00:00""hh:mm:ss");

0.5

TimeIntervalToString

To represent a time interval value as a String.

Report TimeTools.TimeIntervalToString(timeinterval, "hh:mm:ss");

12:00:00

 

Note: As of FreeFlyer 7.3, the default timing precision mode is nanosecond precision mode. For older Mission Plans that have not yet been converted from millisecond precision mode, the TimeTools object uses Variables to represent time values, instead of TimeSpan objects. See the timing precision mode page for more information.

 

 

Epoch Systems


The table below describes the epoch systems available in FreeFlyer.

 

Epoch System

Description

Spacecraft Property

TAI

International Atomic Time (TAI) is measured in days from a reference epoch. The time system is continuous; there are no discontinuities related to variations in the environment. For the different reference epochs, see the below Epoch References section.

 

Modified Julian (GSFC) = Julian Date - 2400000.5 - 29999.5

Modified Julian (USNO) = Julian Date - 2400000.5

Spacecraft.Epoch (Read/Write)

Spacecraft.EpochTAI (Read)

Spacecraft.EpochUSNO (Read)

UTC

Coordinated Universal Time (UTC) time differs from TAI time by an integer number of leap seconds, inserted to make the time system’s local midnight match the observed local midnight to within +/- 0.9 seconds.

 

The time difference between UTC and TAI times occurs because of variations in the rotational rate of the Earth. Astronomical observations are used to determine the drift of the Earth’s rotation, and these observations are used to calculate the insertion of an additional second into the offset between TAI and UTC times. These leap seconds are calculated at the Naval Observatory in Washington, DC, and published in tables at regular intervals. The table of actual and predicted leap seconds is contained in FreeFlyer's Leap Second Table.

Spacecraft.EpochUTC (Read)

Spacecraft.EpochText (Read)

TDT

Terrestrial Dynamic Time (TDT) is equivalent to Terrestrial Time (TT). TDT is the theoretical timescale of apparent geocentric ephemerides of bodies in the solar system. There is a constant offset from TAI of 32.184 seconds.

N/A

TDB

Barycentric Dynamical Time (TDB) is defined as the independent variable of the equations of motion with respect to the barycenter of the solar system.

N/A

UT1

Universal Time (UT1) includes corrections for polar motion. The UT1 and UTC time differences are stored in the Timing Corrections File.

Spacecraft.EpochUT1 (Read)

GPS

Global Positioning System (GPS) time has a constant offset of 19 seconds from TAI and always trails it by that amount.

N/A

Local

Local time is UTC time plus the regional time zone offset of the desired location.

N/A

 

 

Reference Dates


The reference dates that can be used with the TimeTools object are listed in the table below.

 

Reference Date

Description

Julian Date

Julian Date (Jan 1 4713 BCE 12:00:00.000 TAI)

MJD GSFC

GSFC Modified Julian Date (Jan 05 1941 12:00:00.000 TAI)

MJD USNO

USNO Modified Julian Date (Nov 17 1858 00:00:00.000 TAI)

MJD GPS

GPS Modified Julian Date (Jan 06 1980 00:00:00.000 TAI)

MJD 1950

Besselian Date 1950.0 (Dec 31 1949 22:09:46.862 TAI)

 

Note: The GPS time system has a constant offset of 19 seconds from TAI; this happens to be coincident with UTC at the GPS reference epoch. Reference: GPS: Theory and Practice 5th ed., Hofmann-Wellenhof, Lichtenegger, Collins.

 

 

Date and Time Format Specifiers


The FreeFlyer features that can convert between numerical time values and calendar-formatted strings as discussed above all support the date and time string format specifiers listed below. For variable-length date and time specifiers in the third table below, an additional Example column is present to give you an example that can be copied and pasted directly into FreeFlyer that will work. With these variable-length date and time specifiers, the number of characters following the decimal denotes the desired precision and the [+] indicates where additional characters can be added to extend the format as desired. For example, "DOY.DDDDD" would retrieve the 3-digit leading-zero-padded Day Of Year with fraction of day out to five decimal places.

 

Date Formats

 

Time Formats

 

Variable Date and Time Formats

 

 

See Also


TimeTools Properties and Methods

TimeSpan Properties and Methods

TimeSpanArray Properties and Methods