Top  Previous  Next

The TimeSpan object is a container for a duration of time, referenced to a base epoch system depending on context. TimeSpans objects can be used to specify a time value at nanosecond-level precision. FreeFlyer uses this specialized object type to store time values because it is not possible to store an epoch at nanosecond-level precision in the FreeFlyer Variable object type, due to the limited numerical precision of floating point 64-bit values. A set of one or more time values can be stored in a TimeSpanArray object. Any property, method, or function in FreeFlyer that has a time value as an input or output will use the TimeSpan or TimeSpanArray object types.


Note: FreeFlyer provides two timing precision modes. As of FreeFlyer 7.3, the default timing precision mode is nanosecond precision mode, and the TimeSpan and TimeSpanArray objects are only available in 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. See the timing precision mode page for more information.


The following Sample Mission Plans (included with your FreeFlyer installation) demonstrate the use of TimeSpan objects:


FreeFlyer Scripting Samples





This section covers how to declare and work with TimeSpans in FreeFlyer script. The TimeSpan object must be initialized either using static methods or with literal time spans. Either approach also allows you to use TimeSpans in-line in statements such as For and While loops.


TimeSpan Declaration using Static Methods

The syntax examples below show how to initialize a TimeSpan using the static methods on the TimeSpan object type. You can specify the units for the input value (days, hours, minutes, seconds, and/or fractional seconds). TimeSpan objects can also be initialized with a value of zero, an undefined value, or a value parsed from a string.


Undefined TimeSpan values can be used to compare against time values that may be undefined, such as the start time of an Ephemeris object that doesn't contain any vectors.


TimeSpan myTimeSpan;

myTimeSpan = TimeSpan.FromDays(1);

myTimeSpan = TimeSpan.FromSeconds(86400);

myTimeSpan = TimeSpan.FromSeconds(someVariable);

myTimeSpan = TimeSpan.Parse("86400""s"); // Parse string as seconds

myTimeSpan = TimeSpan.Undefined;

myTimeSpan = TimeSpan.Zero;


Spacecraft sc;


While (sc.ElapsedTime < TimeSpan.FromDays(2));

    Step sc;



Literal TimeSpan Declarations

The TIMESPAN keyword is used to declare a literal TimeSpan. The units of the input value must be specified using one of the following keywords: days, hours, minutes, seconds, milliseconds, microseconds, or nanoseconds. Literal TimeSpan declarations must use actual numbers for their values; Variable objects other expressions cannot be used.


TimeSpan myTimeSpan;

myTimeSpan = TIMESPAN(1 days);

myTimeSpan = TIMESPAN(86400.123 seconds);

myTimeSpan = TS(1440 minutes);

myTimeSpan = TS(24 hours);


Spacecraft sc;


While (sc.ElapsedTime < TIMESPAN(2 days));

    Step sc;



TimeSpan Operators

The TimeSpan and VirtualTimeSpan objects can be used with the operators shown below. All of these operators are analogous to the mathematical operators available for the Variable object.





Result Type



ts1 + ts2




ts1 - ts2




ts1 = ts2



Addition Assignment

ts1 += ts2;



Subtraction Assignment

ts1 -= ts2;




ts1 == ts2

VirtualVariable (Boolean)


Not Equals

ts1 != ts2

VirtualVariable (Boolean)


Less Than

ts1 < ts2

VirtualVariable (Boolean)


Less Than or Equals To

ts1 <= ts2

VirtualVariable (Boolean)


Greater Than

ts1 > ts2

VirtualVariable (Boolean)


Greater Than or Equals To

ts1 >= ts2

VirtualVariable (Boolean)






All of these operators are also available as element-by-element operators for the TimeSpanArray and VirtualTimeSpanArray objects. The TimeSpanArray object also supports the bracket syntax used by Array objects to access a single element of the TimeSpanArray.



See Also

Parsing Dates and Times

TimeSpan Properties and Methods

TimeSpanArray Properties and Methods