Time Format

There are two basic contexts that time is parsed: as a single absolute time and as a pair that constitutes a range (inclusive start and exclusive end). In both cases the times may be absolute time specifiers, but might be interpreted slightly differently: specifying a week is valid as both the start and end, but for the end it specifies the end of that week.

In cases where a program requires a range but it can detect when all but one argument should not be treated as a time (that is, only a single time argument was given), then that time will be treated as the start and the end will be inferred from the logical time unit of it. For example, specifying only a week as the start will set the end to the end of that week, resulting in only a single week of data. Specifying a single day would result in that entire day.

NOTE: While full functionality is available on AER_VM and aero there is only limited availability on vortex, aerolab6 and any other hosts that do not have the CPD3 compatibility layer.

Time Offsets

A time offset may appear as either one of the bounds in a range (specifying an amount of time to offset from the other bound) or as a number following a ”+” or ”-” from an absolute time, specifying an amount of time to offset forward or backward from that bound.

A time offset consists of an integer followed by a unit, like “X<unit>” or “2w”. The following units are valid:

  • msec or milliseconds
  • s, sec, or seconds
  • m, min, or minutes - Exactly X * 60 seconds
  • h or hours - Exactly X * 3600 seconds
  • d or days - Exactly X * 86400 seconds
  • w or weeks - Exactly X * 604800 seconds
  • mo, mon, or months - Preserves the time of day and day of month
  • q, qtr, or quarter - Preserves the time after the start of the quarter
  • y or years - Preserves the month, day of month, and time of day

For example “1w” specifies a single week.

The unit may also be followed by “a” or “aligned” to align (round) to the appropriate logical time unit. This rounds in the logical direction for the bound: the start will round to the start of the time unit while the end would round to the end of it. For example, “0qa” as the end bound would set the end to the end of the same quarter that contains the start time.

Absolute Times

In all cases an absolute time may be specified. This designates an absolute point in time, however in some cases components of it may be inferred from other parts. For example if only weeks are specified then the year is assumed to be the current year, but if one of the two bounds in a pair specifies a year then the other would be treated as a week in that year (or the prior/next if that would result in a backwards set of bounds).

In generally all of ISO 8601 is supported with additional extensions and component inference as possible.

Any non-infinite absolute time may be followed by ”+” or ”-” and a time offset described above.

The current time

The string “now” specifies the exact current time.

Date and/or time

If present the date must come first, it must start with a four digit year, followed by an optional month and day of month. Each field must be separated by either a dash or a slash. The time then follows either a space separator or a “T”. Time is specified on a 24 hour clock, with the hours first, seconds being optional. Each field must be separated by a ”:”. The specification may optionally end in a “Z”. Some valid examples include:

  • 2010-03-10T00:15:00Z
  • 2010/03/10 00:15:00
  • 2010-03-10
  • 20100310T001500Z
  • 15:00:12.123Z
  • 2010

If only a time is specified, the date is inferred as described above such that it would be reasonable relative to it. A date and/or time may optionally be followed by a time zone offset, this takes the form of + or - a two or four digit integer or “hh:mm”. This number is subtracted or added to the given time to give UTC.

Year and week or week

One of the following forms:

  • YYYYwWW
  • YYYYwWW-D
  • wWW
  • wWW-D

Note that the “WW” component may be a single digit. The exact time that the week specifies depends on if the bound is the start or end (in the case of a single time parse it is assumed to be the start).

Year and quarter or quarter

One of the following forms:

  • YYYYqQ
  • qQ

The exact time that the quarter specifies depends on if the bound is the start or end (in the case of a single time parse it is assumed to be the start).

Year and DOY or DOY

A four digit year separated from a DOY by any of ”:”, ”;”, ”,” or space(s). The DOY starts with 1.0 being midnight January 1st of that year. The separator may also be omitted or replaced with ”-” if there are exactly three digits in the integer component of the DOY. Some examples include:

  • 2010:1
  • 2010,1.2345
  • 2010;023.12456
  • 2010023.1234
  • 2010-023
  • 12.45632
  • 15

Unlike the other cases, this always specifies the “start” of the given time. So specifying an integer for the end would actually be midnight of that DOY.

A fractional year

This is a number with a fractional component between 1970.0 and 2999.0. The integer component specifies the year and the fractional component specifies the fraction of the time though that year. For example, 2010.0 is 2010-01-01T00:00:00Z while 2010.5 is 2010-07-02T12:00:00Z.

An epoch time

This is a decimal number of seconds since 1970-01-01T00:00:00Z. This may also be begun with “E:” to disambiguate from ISO time strings.

Infinite bounds

If the program supports infinite or undefined bounds then on of the following may be accepted:

  • Empty - All space (or zero length)
  • 0 - The number zero
  • none
  • undef or undefined
  • inf or infinity
  • all
  • forever

Note that an offset is meaningless on an infinite bound and results in an error.

Relative Bounds

When parsing a pair that specifies bounds one of the bounds may be a non-negative offset as described above. This is treated as an offset in the logical direction for that bound. For example specifying “2w” as the end bound would result in an end that is two weeks from the start.