Skip to content

TimeSpan

See Also: Declaring Variables, Variable Declaration Commands, Time and Date Functions, Struct, Date, DateTime, Time

Purpose

Declares one or more TimeSpan variables.

Syntax

To declare TimeSpan variables

TimeSpan {identifier} [… {identifier}]

Where:

  • {identifier} is a variable name for the new TimeSpan variable.
  • {identifier} may be between 1 and 4096 characters in length, must start with a letter, and may not contain spaces. Recommended characters are 0-9, a-z, A-Z, and _ (underscore).

To declare array variables of type TimeSpan

TimeSpan {dimension-list} {identifier} [… {identifier}]

Where:

  • {dimension-list} is a list of one or more array dimensions for the array. A dimension list is declared using square brackets []. One pair of brackets is used to declare each dimension. If the array is static, then you must specify the static size of each dimension between each pair of brackets, i.e., [{size}]. For more information about declaring arrays, refer to Array Variable Assignments.
  • {identifier} may be between 1 and 4096 characters in length, must start with a letter, and may not contain spaces. Recommended characters are 0-9, a-z, A-Z, and _ (underscore).

What It Does

The TimeSpan command declares variables of the TimeSpan type.

The purpose of a TimeSpan variable is to store the result of a calculation between DateTime or Time variables. TimeSpan can store a span of time of up to 65,535 days.

Use TimeSpan manipulation functions such as SpanAddDay, SpanAddHour, SpanAddMillisecond, SpanAddMinute, and SpanAddSecond to place constant values in a TimeSpan variable.

Multiple variables may be declared on one command line, with their names separated from each other by spaces.

TimeSpan cannot contain a negative value. The value is a span of time and is always positive.

Typecasting between DateTime and TimeSpan

When you move data between DateTime, TimeSpan, and Date types, automatic casting occurs as follows:

  • Move DateTime to TimeSpan - Always works; data is transferred except month and year, which are set to 0.
  • Move TimeSpan to DateTime - Always works, but DateTime will be invalid unless it happens to be null.
  • Move Date to DateTime - Always works. Time portion is all 0.
  • Move DateTime to Date - Does limited Date type check. It simply checks that Month is 1-12 and Day is 1-31. It will advance the date if the Day (29, 30, 31) is too large for the month (legacy Date conversion behavior).
  • Move Date to TimeSpan - Always works; will move the date portion to TimeSpan. Day will be added but not Month or Year. Time portion is all 0.
  • Move TimeSpan to Date - Will be an error unless the TimeSpan is Null.

DateTime and TimeSpan Arithmetic

DateTime and TimeSpan arithmetic works according to the following table:

Operation Result
DateTime + DateTime error
DateTime + TimeSpan DateTime
TimeSpan + TimeSpan TimeSpan
TimeSpan - TimeSpan TimeSpan (result is always a positive difference)
DateTime - DateTime TimeSpan (result is always a positive difference)
DateTime - TimeSpan DateTime
TimeSpan + DateTime error
TimeSpan - DateTime error

Examples

Procedure Test
    TimeSpan tsVar
    Move (DateSetSecond(tsVar, 30)) To tsVar
    Move (DateSetMinute(tsVar, 10)) To tsVar
    Move (DateSetHour(tsVar, 10)) To tsVar
    Move (DateSetDay(tsVar, 30)) To tsVar
End_Procedure

This example declares a TimeSpan variable, then initializes its value to 30 days, 10 hours, 10 minutes, and 30 seconds.

TimeSpan[] tsIntervals

This example declares 1 dynamic array variable, named tsIntervals, containing an undefined number of elements of type TimeSpan.

TimeSpan[5] tsIntervals

This example declares 1 static array variable, named tsIntervals, containing 5 elements of type TimeSpan.

TimeSpan[][3] tsIntervals

This example creates a two-dimensional dynamic array variable named tsIntervals, containing an undefined number of elements of type TimeSpan. Conceptually, this represents a rectangular array with an undefined number of rows, each of 3 columns.

You can declare dynamic multi-dimensional arrays where all dimensions are dynamic; these are called jagged arrays.

Notes

  • The TimeSpan type is a structured type with the same internal structure as a DateTime.
  • TimeSpan types can also be used for declaring variables for storing the difference of two DateTime values, i.e., the subtraction of one DateTime value from another.
  • Use the date functions, DateSetMonth, DateSetDay, DateSetYear, DateSetSecond, DateSetMinute, and DateSetHour to manually place constant values in a TimeSpan variable.
  • If you need to define a global TimeSpan variable, you should use the global_variable command to do so.