Datetime

Date-time

R←X ⎕DT Y

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.

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.

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^{1In the Proleptic Gregorian Calendar}represented by 0 (Epoch)	Negative values allowed?^{8No 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^{2There 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^{3Generated as DECF values regardless of the setting of ⎕FR due to their magnitude.} 1ns ticks^{2There are the same number of ticks per day regardless of leap seconds.}	2000-01-01 00:00	Yes
11	Shakti K	Tick count 1ms ticks^{2There 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^{2There 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
UNIX	20	Unix time	Tick count 1s ticks^{2There 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^{3Generated 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^{3Generated 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^{8For 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)^{4Excel 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^{5Count includes the invalid date 1900-02-29.}	1899-12-31 00:00^{6Microsoft Excel converts day 0 to the invalid date 1900-01-00.}	No
41	Excel (1904 Date System)^{4Excel 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^{2There 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^{2There are the same number of ticks per day regardless of leap seconds.}	1582-10-14 00:00	No
44	SAS	Tick count 1s ticks^{2There 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^{9Decimal 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

Group

Code

Description

Timestamps

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^{1All dates must be between 1 January 0001 and 28 February 4000 in the Proleptic Gregorian Calendar}	Elided element implicit values (in Y)^{3If 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
ISO components	¯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^{2Decimal 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	Decimal encoded date, decimal encoded time	10101 0

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

Character

Time zone name

Time zone

Alpha

UTC +1

Bravo

UTC +2

Charlie

UTC +3

Delta

UTC +4

Echo

UTC +5

Foxtrot

UTC +6

Golf

UTC +7

Hotel

UTC +8

India

UTC +9

Juliet

Local time

Kilo

UTC +10

Lima

UTC +11

Mike

UTC +12

November

UTC -1

Oscar

UTC -2

Papa

UTC -3

Quebec

UTC -4

Romeo

UTC -5

Sierra

UTC -6

Tango

UTC -7

Uniform

UTC -8

Victor

UTC -9

Whisky

UTC -10

X-ray

UTC -11

Yankee

UTC -12

Zulu

UTC +0

¯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

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│ └──────────────────────┘

Time Numbers

Timestamps

Military time zone characters

Examples: Timestamp to time number conversion

Examples: Time number to timestamp conversion

Examples: Time number to time number conversion

Example: Validation