This function validates date-times or converts date-times between one format and another.
A date-time is a date and time of day represented by a timestamp, a time number or a military time-zone character.
- A timestamp is a date-time expressed as a multiple element numeric vector, of which there are several different sorts (principally ⎕TS format).
- A time number is a date-time expressed as a scalar numeric value, of which there are several different sorts.
- A military time zone character is a scalar character that represents the current date-time ("now") in a particular time zone. For example, 'A' represents the current date-time (UTC) + 1 hour.
Y is an array of any shape whose elements contain a timestamp, time number or military time zone character, in any combination.
X may be a single integer value or a 2-element integer vector.
When X is a single integer value, it must be either 0 or a date-time code listed in the tables below. 0 specifies that the elements of Y are to be validated. A non-zero value specifies the date-time representation to which the elements of Y are to be converted. In this case, the numeric elements of Y are interpreted as follows:
- scalars are assumed to be time numbers of type Dyalog Date Number (code 1)
- vectors are assumed to be ⎕TS timestamps (code ¯1)
When X is a 2-element integer vector, X[1] is a date-time code that explicitly specifies the date-time representation of the numeric elements in Y. X[2] is either 0 or a date-time code listed in the tables below. 0 specifies that the elements of Y are to be validated. A non-zero value specifies the date-time representation to which the elements of Y are to be converted.
Character scalars in Y are always interpreted as meaning "now".
R is an array of the same shape as Y, where each element is either a timestamp, time number or Boolean value as determined by the second or only element in X.
Note: time numbers in R may be of type DECF even if ⎕FR is 645 if their magnitude can be too great to store precisely in a double. See the table below for the type numbers where this is so.
Time Numbers
If a value in X is positive it indicates that a time number type is expected in Y or generated in R, as follows. Note that the last column indicated whether (Yes) or not (No) negative numbers are allowed.
Group | Code | Description | Category | Date and time^{1 In the Proleptic Gregorian Calendar}represented by 0 (Epoch) | Negative values allowed?^{8 No date-time may represent a date earlier than ¯4713-01-01 00:00.} |
---|---|---|---|---|---|
Dyalog APL | 1 | Dyalog Date Number | Day count with fractional part | 1899-12-31 00:00 | Yes |
2 | Dyalog component file time | Tick count 1÷60s ticks^{2 There are the same number of ticks per day regardless of leap seconds.} |
1970-01-01 00:00 | Yes | |
Other languages | 10 | J (J nanosecond time) | Tick count^{3 Generated as DECF values regardless of the setting of ⎕FR due to their magnitude.} 1ns ticks^{2 There are the same number of ticks per day regardless of leap seconds.} |
2000-01-01 00:00 | Yes |
11 | Shakti K7 | Tick count 1ms ticks^{2 There are the same number of ticks per day regardless of leap seconds.} |
2024-01-01 00:00 | Yes | |
12 | JavaScript / D / Q | Tick count 1ms ticks^{2 There are the same number of ticks per day regardless of leap seconds.} |
1970-01-01 00:00 | Yes | |
13 | R (R chron format) | Day count with fractional part | 1970-01-01 00:00 | Yes | |
14 | Shakti K9 | Tick count 1ms ticks^{2 There are the same number of ticks per day regardless of leap seconds.} |
2001-01-01 00:00 | Yes | |
UNIX | 20 | Unix time | Tick count 1s ticks^{2 There are the same number of ticks per day regardless of leap seconds.} |
1970-01-01 00:00 | Yes |
Microsoft | 30 | Microsoft DOS date/time | Encoded broken-down time 2s resolution |
N/A | No |
31 | Microsoft Win32 FILETIME | Tick count^{3 Generated as DECF values regardless of the setting of ⎕FR due to their magnitude.} 100ns ticks |
1601-01-01 00:00 | No | |
32 | Microsoft CLR DateTime (.NET)(Ticks property thereof) | Tick count^{3 Generated as DECF values regardless of the setting of ⎕FR due to their magnitude.} 100ns ticks |
0001-01-01 00:00 | No | |
33 | Microsoft OLE Automation Date(also known as Variant Time) | Day count with fractional part | 1899-12-30 00:00 | Yes^{8 For negative numbers, the integral part counts backward from 1899-12-30 and the fractional part counts forward from the date so reached.} | |
Application | 40 | Excel (1900 Date System)^{4 Excel supports two time number conventions. On Windows the 1900 Date System is the default and on macOS the 1904 Date System is the default. Both systems can use either convention and the convention in use is stored in the worksheet so that the platforms interoperate.}/ Lotus 1-2-3 | Day count with fractional part^{5 Count includes the invalid date 1900-02-29.} | 1899-12-31 00:00^{6 Microsoft Excel converts day 0 to the invalid date 1900-01-00.} | No |
41 | Excel (1904 Date System)^{4 Excel supports two time number conventions. On Windows the 1900 Date System is the default and on macOS the 1904 Date System is the default. Both systems can use either convention and the convention in use is stored in the worksheet so that the platforms interoperate.} | Day count with fractional part | 1904-01-01 00:00 | No | |
42 | Stata statistics package | Tick count 1ms ticks^{2 There are the same number of ticks per day regardless of leap seconds.} |
1960-01-01 00:00 | Yes | |
43 | SPSS statistics package | Tick count 1s ticks^{2 There are the same number of ticks per day regardless of leap seconds.} |
1582-10-14 00:00 | No | |
44 | SAS | Tick count 1s ticks^{2 There are the same number of ticks per day regardless of leap seconds.} |
1960-01-01 00:00 | Yes | |
Julian Date and variants | 50 | Julian Date | Day count with fractional part | ¯4717-11-24 12:00 | No |
51 | J (J dayno) | Day count with fractional part | 1800-01-01 00:00 | No | |
52 | Reduced Julian Date | Day count with fractional part | 1858-11-16 12:00 | Yes | |
53 | Modified Julian Date | Day count with fractional part | 1858-11-17 00:00 | Yes | |
54 | Dublin Julian Date | Day count with fractional part | 1899-12-31 12:00 | Yes | |
55 | CNES Julian Date | Day count with fractional part | 1950-01-01 00:00 | Yes | |
56 | CCSDS Julian Date | Day count with fractional part | 1958-01-01 00:00 | Yes | |
Decimal encoded^{9 Decimal encoded formats encode human-readable dates and times into a single number with the most significant part in the most significant decimal digit, for example 2020/01/23 (year/month/day) is encoded as 20200123, and 13:17:56 (hour:minute:second) is encoded as 131756. The date must be between 1 January 0001 and 28 February 4000 in the Proleptic Gregorian Calendar.} | 60 | Floating-point decimal encoded format Digits take the form yyyymmdd.hhmmss |
Encoded broken-down time 1s resolution |
N/A | No |
61 | Integer decimal encoded format Digits take the form yyyymmddhhmmss(J digit time) |
Encoded broken-down time 1s resolution |
N/A | No |
Time Stamps
If a value in X is negative it indicates that a timestamp type is expected in Y or generated in R, as follows:
Group | Code | Description | Max elements | Element contents^{1}^{1 All dates must be between 1 January 0001 and 28 February 4000 in the Proleptic Gregorian Calendar} | Elided element implicit values (in Y)^{3}^{3 If a timestamp has fewer than the maximum number of elements, the reaimning elements take the default values shown} |
---|---|---|---|---|---|
APL 7-element vector | ¯1 | Millisecond precision (⎕TS) | 7 | Year, month, day-of-month, hour, minute, second, millisecond | 1 1 1 0 0 0 0 |
¯2 | Microsecond precision | 7 | Year, month, day-of-month, hour, minute, second, microsecond | 1 1 1 0 0 0 0 | |
¯3 | Nanosecond precision (J expanded digit time) | 7 | Year, month, day-of-month, hour, minute, second, nanosecond | 1 1 1 0 0 0 0 | |
ISO components | ¯10 | ISO day-of-year components | 6 | Year, day-of-year, hour, minute, second, microsecond | 1 1 0 0 0 0 |
¯11 | ISO day-of-week components | 7 | Year, week, day-of-week, hour, minute, second, microsecond | 1 1 1 0 0 0 0 | |
Decimal encoded^{2 Decimal encoded formats encode human-readable dates and times into a single number with the most significant part in the most significant decimal digit, for example 2020/01/23 (year/month/day) is encoded as 20200123, and 13:17:56 (hour:minute:second) is encoded as 131756.} | ¯20 | Decimal encoded date and time^{2} | 2 | Decimal encoded date, decimal encoded time | 10101 0 |
DateTimePicker | ¯30 | DateTime format | 7 | International Day Number (IDN), hour, minute second | 1 1 1 0 0 0 |
Military time zone characters
Any element in Y may be specified as a military time zone character and is implicitly replaced by the current time in the time zone they represent. The time zones are as follows:
Character | Time zone name | Time zone |
---|---|---|
A | Alpha | UTC +1 |
B | Bravo | UTC +2 |
C | Charlie | UTC +3 |
D | Delta | UTC +4 |
E | Echo | UTC +5 |
F | Foxtrot | UTC +6 |
G | Golf | UTC +7 |
H | Hotel | UTC +8 |
I | India | UTC +9 |
J | Juliet | Local time |
K | Kilo | UTC +10 |
L | Lima | UTC +11 |
M | Mike | UTC +12 |
N | November | UTC -1 |
O | Oscar | UTC -2 |
P | Papa | UTC -3 |
Q | Quebec | UTC -4 |
R | Romeo | UTC -5 |
S | Sierra | UTC -6 |
T | Tango | UTC -7 |
U | Uniform | UTC -8 |
V | Victor | UTC -9 |
W | Whisky | UTC -10 |
X | X-ray | UTC -11 |
Y | Yankee | UTC -12 |
Z | Zulu | UTC +0 |
Note that the resolutions of system clocks vary by platform.
Examples: Timestamp to time number conversion
¯1 1 ⎕DT ⊂⎕TS 43886.48039 1 ⎕DT ⊂⎕TS 43886.48039 1 ⎕DT ⎕TS 'J' 43886.48039 43886.48039 1 ⎕DT ⊂⍬ ⍝ cf Elided element implicit values ¯693594 1 ⎕DT ⊂1 1 1 0 0 0 0 ¯693594 ¯30 1 ⎕DT⊂(44217 15 13 54) 44217.63465
Examples: Time number to timestamp conversion
1 ¯1 ⎕DT 0 43508.42843 ┌──────────────────┬──────────────────────┐ │1899 12 31 0 0 0 0│2019 2 13 10 16 56 352│ └──────────────────┴──────────────────────┘ ¯1 ⎕DT 0 43508.42843 ┌──────────────────┬──────────────────────┐ │1899 12 31 0 0 0 0│2019 2 13 10 16 56 352│ └──────────────────┴──────────────────────┘ 2 ¯1 ⎕DT 3⊃⎕FRDCI 1 1 ┌──────────────────────┐ │2020 2 26 11 33 54 466│ └──────────────────────┘ 1 ¯30 ⎕DT 44217.63465 ┌──────────────┐ │44217 15 13 53│ └──────────────┘
Examples: Time number to time number conversion
2 1 ⎕DT 3⊃⎕FRDCI 1 1 43886.48188 1 ⎕DT 'J' 43886.48371 ⍝ Local time is UTC-05:00 3600÷⍨-/20 ⎕DT 'JZ' ¯5
Examples: Timestamp to timestamp conversions
¯30 ⎕DT ⊂⎕TS ┌─────────────┐ │44216 16 5 46│ └─────────────┘
¯30 ¯1 ⎕DT⊂32000 15 10 0 ┌───────────────────┐ │1987 8 12 15 10 0 0│ └───────────────────┘
Examples: Validation
0 ⎕DT ⎕TS (2020 13 1) 'J' 'DT' # 1 0 1 0 0 ¯30 0 ⎕DT⊂32000 15 10 0 1