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

Format

Description

YYYY

4-digit leading-zero-padded year

YY

2-digit leading-zero-padded year of century

MMMM

Month of year, all capitals

Mmmm

Month of year, 1st letter capital

mmmm

Month of year, all lower case

MMM

3-letter abbreviated month, all capitals

Mmm

3-letter abbreviated month, 1st capital

mmm

3-letter abbreviated month, all lower case

MM

2-digit leading-zero-padded month

M

1- or 2-digit month of year (i.e not zero-padded)

DOY

3-digit leading-zero-padded day of year

DDDD

Day of week, all capitals

Dddd

Day of week, 1st capital

dddd

Day of week, all lower case

DDD

3-letter abbreviated day of week, all capitals

Ddd

3-letter abbreviated day of week, 1st capital

ddd

3-letter abbreviated day of week, all lower case

DOW

1-digit day of week (Sunday represented as 1)

DD

2-digit leading-zero-padded day of month

D

1- or 2-digit day of month (i.e. not zero-padded)

 

Time Formats

Format

Description

hh

2-digit leading-zero-padded hour, 24-hour format

h

1- or 2-digit hour, 24-hour format (i.e. not zero-padded)

mm

2-digit leading-zero-padded minute

m

1- or 2-digit minute

ss

2-digit leading-zero-padded second

s

1- or 2-digit second

hh12

2-digit leading-zero-padded hour, 12-hour format

h12

1- or 2-digit hour, 12-hour format (i.e. not zero-padded)

AM/PM

AM or PM, all capitals

Am/Pm

Am or Pm, 1st capital

am/pm

am or pm, all lower case

 

Variable Date and Time Formats

Format

Example*

Description

d[+]

dd

Time interval in leading-zero-padded days with the specified number of digits

DOY.D[+]

DOY.DDD

3-digit leading-zero-padded Day Of Year with fraction of day

d[+].d[+]

dd.dddd

Time interval in leading-zero-padded days with fraction of day

d.d[+]

d.ddd

Fraction of a day with leading zero

hh.h[+]

hh.hh

2-digit leading-zero-padded hour with fraction of hour

h.h[+]

h.hh

1- or 2-digit hour with fraction of hour

mm.m[+]

mm.mmm

2-digit leading-zero-padded minute with fraction of minute

m.m[+]

m.mmmmm

1- or 2-digit minute with fraction of minute

ss.s[+]

ss.ss

2-digit leading-zero-padded seconds with fraction of second

s.s[+]

s.s

1- or 2-digit seconds with fraction of second

ss.fs

ss.fs

2-digit leading-zero-padded seconds with any number of fractional second decimal places up to the max supported

•Up to 3 decimal places in millisecond timing precision mode

•Up to 9 decimal places in nanosecond timing precision mode

ss(d)

ss(d)

5-digit leading-zero-padded second of day

ss(d).s[+]

ss(d).ss

5-digit leading-zero-padded second of day with fraction of second

•The number of characters following the decimal denotes desired precision

ss(d).fs

ss(d).fs

5-digit leading-zero-padded second of day with any number of fractional second decimal places up to the max supported

•Up to 3 decimal places in millisecond timing precision mode

•Up to 9 decimal places in nanosecond timing precision mode

ss(y)

ss(y)

8-digit leading-zero-padded second of year

ss(y).s[+]

ss(y).ssss

8-digit leading-zero-padded second of year with fraction of second

•The number of characters following the decimal denotes desired precision

 

Note: The asterisk (*) in the Example column above is present to indicate that while the listed examples will parse as-is, they are not the only variants of these formats that are allowed. As discussed above, variable number of characters can be added anywhere that a [+] is present in the format for outputs of variable length and styling.

 

 

See Also

•TimeTools Properties and Methods

•TimeSpan Properties and Methods

•TimeSpanArray Properties and Methods