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


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




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:





Example Output


To convert time to a different system.

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



To convert a time value to a calendar date.

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

Mar 01 2012 12:00:00.000


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


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}


To determine if an epoch is in daylight savings.

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



To determine if an epoch is in a leap year.

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



To parse a calendar date and get its value.

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



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");



To parse a time interval String into a value.

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



To represent a time interval value as a String.

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



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


Spacecraft Property


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)


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)


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.



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



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

Spacecraft.EpochUT1 (Read)


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



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




Reference Dates

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


Reference Date


Julian Date

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


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


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


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

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