Datetime R←X ⎕DT Y

This function validates datetimes, converts datetimes between one representation and another, and converts datetimes to and from text.

A datetime is a date and time of day represented by a time number, a timestamp, a military time-zone character, or a text-formatted datetime.

• A time number is a datetime expressed as a scalar numeric value, of which there are several different sorts (principally a Dyalog Date Number).
• A timestamp is a datetime expressed as a multiple element numeric vector, of which there are several different sorts (principally ⎕TS format).
• A military time zone character is a scalar character that represents the current datetime ("now") in a particular time zone. For example, 'A' represents the current datetime (UTC) + 1 hour.
• A text-formatted datetime is a datetime expressed as a character vector, formatted according to a formatting pattern.

Y is an array of any shape whose elements contain a time number, timestamp, military time zone character, or text-formatted datetime, in any combination.

X describes the representation to which the elements of Y are to be converted (the output format) and, optionally, the representation of the elements of Y (the input format). These are referred to below as XR and XY respectively.

X can be a single element (XR) or a 2-element vector (XY XR). Each of XY and XR can be:

• an integer datetime code (see Table 1 and Table 2)
• a character vector containing a pattern that describes how a datetime is formatted as text (see Formatting Patterns).

When XR is an integer it must be either 0 or a code from Table 1 or Table 2. 0 specifies that the elements of Y are to be validated; a non-zero value specifies the datetime representation to which the elements of Y are to be converted. When XR is a pattern, the elements of R are character vectors, each derived by formatting the corresponding element of Y as text according to the pattern.

XY can be omitted only when the elements of Y are Dyalog Date Numbers, ⎕TS-style timestamps, or military time zone characters. When XY is omitted, 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 XY is an integer datetime code it explicitly specifies the datetime representation of the numeric elements of Y. When XY is a pattern, the corresponding character vectors in Y are matched against the pattern and the resulting datetime are returned in the representation given by XR (see Pattern matching rules). A pattern XY cannot be omitted, even when the elements of Y are character vectors that could unambiguously be assumed to be text-formatted datetimes.

Text-formatted datetimes and patterns are character vectors; no scalar extension occurs when character scalars appear in X or Y. A single text-formatted datetime in Y must be enclosed (nested); an unenclosed character vector in Y is interpreted as a vector of military time zone characters. As a convenience, a simple (not nested) character vector X is implicitly enclosed and processed as XR meaning that a single pattern can be supplied on its own to format datetimes as text.

Character scalars in Y are always interpreted as meaning "now".

R is an array of the same shape as Y, where each element is a timestamp, time number, character vector or Boolean value, as determined by XR (the second or only element of X).

Time numbers in R can be of type DECF even when ⎕FR is 645 if their magnitude could be too great to store precisely in a double. See Table 1 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.

Timestamps

If a value in X is negative it indicates that a timestamp type is expected in Y or generated in R, as follows:

Military Time Zone Characters

Any element in Y can 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 and their characters are detailed in Table 3.

The resolutions of system clocks vary by platform.

Formatting Patterns

Either or both of XR and XY can be a character vector containing a pattern which describes how a datetime is, or is to be, formatted as text.

When used as XR, the pattern controls how each element of Y is formatted into a character vector in R. When used as XY, the same pattern describes the text supplied in Y and controls how it is matched and decoded into the representation given by XR (see Pattern-matching Rules).

The formatting pattern allows a datetime to be converted to a user-configurable plain-text format. When a datetime is formatted, elements in the result are copies of the format pattern with format sequences replaced by the elements they represent.

The format sequences are intended to be visually reminiscent of the generated text. They use alphabetic characters easily associated with the substitution (for example D, M, and Y for Day, Month, and Year respectively) repeated one or more times to indicate format. Some sequences allow the first character to be replaced by a _, or the casing to be altered.

The upper and lower case letters, underscore _, dollar $, and percent % are all reserved for introducing format sequences, even though not all currently have meaning. The remaining, non-reserved, characters are copied to the result unchanged; this means that the format string hh:mm represents the hour of the day and minute of the hour, separated by a colon (for example 12:00). All characters or sequences of characters can be delimited by " or ' at any point in the format string to prevent them from being interpreted as a part of a format sequence, and, within these delimiters, two adjacent delimiter characters produce a single delimiter.

Language

Unless overridden, English is used for text substitutions. Different languages can be selected using the Language variant option and/or the use of language specifiers within the format pattern. In either case, the language is specified as either a two letter ISO 639-1 language code in lower case (for example, en) or as a five character language with an additional underscore and two character region in upper case (for example, en_GB). Within the format pattern, __xx__ (where xx is the two or five character specifier) will switch the language of the subsequent generated or matched text. { #languages } shows the languages that are built into the interpreter.

Predefined Patterns

Any pattern can contain (in part or in whole) a named predefined pattern, which allows common date and time formats to be specified in abbreviated form. Predefined patterns can be specified for each language, allowing patterns to be tailored for the selected language.

Predefined patterns are included in a pattern using % delimiters. For example, %ISO% includes the named predefined pattern ISO.

The following global predefined pattern is built into the interpreter:

Additional predefined patterns can be defined using the Dictionary variant option. Predefined patterns must not contain references to other predefined patterns.

Pattern-matching Rules

When XY is a pattern, the corresponding character vectors in Y are matched against it and decoded into datetime. The following additional rules apply to the matching.

Two-digit Years

Two digit years (that is, those corresponding to the formatting pattern elements YY and WW) are, by default, interpreted according to the same rules used for ⎕SM and GUI edit fields, which are configurable using the YY_WINDOW configuration parameter.

Ambiguities and Precision

Formatting to a text-formatted datetime can be lossy, that is, the formatted text does not necessarily contain sufficient information to regenerate the original datetime. A pattern used to convert from a text-formatted datetime is not permitted to be ambiguous, that is, it must not be possible to deduce multiple disjoint datetimes from text generated by it (for example, a pattern which contains a year and a day-of-month but no month, because there could be twelve disjoint dates for which the pattern would generate identical text). Such a pattern is rejected.

Patterns are, however, permitted to have limited precision (for example, a pattern that includes a date but no time elements, or a date plus only hour and minute time elements). Elements with lower significance than the least significant provided element can be elided and take a default value; this is analogous to the way ⎕DT infers elements elided from timestamps.

There are three principal means of specifying a date:

• year, month, day-of-month
• year, day-of-year
• ISO-year-of-week, ISO-week, day-of-week

If a text-formatted datetime contains elements from more than one of these three principal formats, then:

1. at least one of them must be unambiguous;
2. when more than one of them is unambiguous, the date is determined from the most precise one;
3. all element values must be consistent with the date so deduced.

Elided elements of a year, month, day-of-month date are all (including the year) implicitly 1. Elided elements of times are all implicitly 0.

Some combinations of variable-length substitutions can make particular texts impossible to parse unambiguously. For example, the pattern MD (1 to 2 digits of month immediately followed by 1 to 2 digits of day-of-month) formats both 3 December and 23 January as 123, so the text 123 cannot be matched against MD and an error is signalled. Whether such an ambiguity actually arises depends on the text being parsed: the text 1231 can only mean 31 December and is matched without error. Where two or more variable-length numeric or alphanumeric substitutions are adjacent, you can place literal text between them that cannot be confused with the substitution text to avoid such ambiguities.

Consistency

The formatted text is parsed and used to compute a datetime according to the given pattern, and must precisely match the text that would be produced if the resulting datetime were formatted using that same pattern. That is:

• The formatted text must contain valid substitution text where a format sequence appears in the pattern — for example, a full month name where Mmmm appears in the pattern.
• All other characters, including spaces and literal characters, must exactly match the pattern.
• All characters must be in the correct case.
• The elements in the formatted text must be consistent with one another. If the pattern contains the same element (or variations of the same element) more than once, they must have the same value in each case. Elements that are not independent must not be contradictory. For example, the text Mon 5 Feb 2025 superficially appears to match the pattern Ddd D Mmm YYYY but is contradictory, because 5 February 2025 was a Wednesday, not a Monday.

If a pattern is rejected, or a text-formatted datetime cannot be matched against the pattern for any of the reasons above, a DOMAIN ERROR is signalled and an explanatory message is included.

Variant Options

⎕DT supports the Language and Dictionary variant options, specified using the variant operator ⍠. These only apply when XY and/or XR are patterns.

Variant Option: Language

The Language variant option specifies the language used for formatting and matching datetimes and defaults to 'en' (English). A language is named by a two or five character value (for example 'en' or 'en_GB'). The value can be one of the following:

• a single character vector, which applies to whichever of XY and/or XR are patterns.
• A 2-element vector of two character vectors, which apply to XY and XR respectively (each is used only if the corresponding value is a pattern).

The setting can be explicitly overridden within a format pattern using the __xx__ specifier described under Language.

Variant Option: Dictionary

The Dictionary variant option specifies a namespace that contains additional or replacement names for the months (and so on) and/or predefined patterns, for languages and language regions. If XY and XR are both patterns, the dictionary is applied to both.

At the top level there can be zero or more sub-namespaces with two or five character names, according to the rules for language and language regions. Within each of these, month names (and so on) are defined as shown in Table 7.

The top level of the dictionary namespace can contain a sub-namespace named Patterns and, within this, further sub-namespaces named Global and/or two or five character language names, containing definitions of predefined patterns. Predefined patterns are defined in the same way as the formatting pattern except that they must not contain references to other predefined patterns.

If the namespace contains a definition that is supplied built into the interpreter, it replaces the built-in one.

If a dictionary is incomplete (for example, is missing one of the expected named items, or one of the named items contains too few elements), an error is signalled if the missing content would be needed.

See the Dictionary example.

Examples

Creating a Dictionary

The following creates a dictionary defined by the namespace dict. See formatting examples for uses of this dictionary.

dict←(
  Patterns: (
    Global: (
      ISOweek: 'YYYY-"W"ww'
      DateCompact: 'D-MMM-YYYY'
      DateVerbose: '"the date is" DD _mm YYYY'
    )
    fr: ( DateVerbose: '"la date est le" DD mmm YYYY' )
    en_US: ( DateVerbose: '"the date is" Mmm DD, YYYY' )
  )
  en_US: (
    ShortMonthNames: (
      'Jan.' ⋄ 'Feb.' ⋄ 'Mar.' ⋄ 'Apr.' ⋄ 'May' ⋄ 'June'
      'July' ⋄ 'Aug.' ⋄ 'Sept.' ⋄ 'Oct.' ⋄ 'Nov.' ⋄ 'Dec.'
    )
  )
  cy: (
    MonthNames: (
      'Ionawr' ⋄ 'Chwefror' ⋄ 'Mawrth' ⋄ 'Ebrill' ⋄ 'Mai' ⋄ 'Mehefin'
      'Gorffennaf' ⋄ 'Awst' ⋄ 'Medi' ⋄ 'Hydref' ⋄ 'Tachwedd' ⋄ 'Rhagfyr'
    )
    ShortMonthNames: (
      'Ion' ⋄ 'Chw' ⋄ 'Maw' ⋄ 'Ebr' ⋄ 'Mai' ⋄ 'Meh'
      'Gor' ⋄ 'Awst' ⋄ 'Medi' ⋄ 'Hyd' ⋄ 'Tach' ⋄ 'Rhag'
    )
    WeekdayNames: (
      'Dydd Sul' ⋄ 'Dydd Llun' ⋄ 'Dydd Mawrth' ⋄ 'Dydd Mercher'
      'Dydd Iau' ⋄ 'Dydd Gwener' ⋄ 'Dydd Sadwrn'
    )
    ShortWeekdayNames: (
      'Sul' ⋄ 'Llun' ⋄ 'Maw' ⋄ 'Mer' ⋄ 'Iau' ⋄ 'Gwen' ⋄ 'Sad'
    )
    MorningAfternoon: ( 'yb' ⋄ 'yh' )
    Ordinals: (
      'af' ⋄ 'il' ⋄ 'ydd' ⋄ 'ydd' ⋄ 'ed' ⋄ 'ed' ⋄ 'fed' ⋄ 'fed' ⋄ 'fed'
      'fed' ⋄ 'eg' ⋄ 'fed' ⋄ 'eg' ⋄ 'eg' ⋄ 'fed' ⋄ 'eg' ⋄ 'eg' ⋄ 'fed'
      'eg' ⋄ 'fed' ⋄ 'ain' ⋄ 'ain' ⋄ 'ain' ⋄ 'ain' ⋄ 'ain' ⋄ 'ain'
      'ain' ⋄ 'ain' ⋄ 'ain' ⋄ 'ain' ⋄ 'ain'
    )
  )
)

In the above example:

• the predefined pattern ISOweek is defined globally and is not redefined. This means that it has the same value for all languages. Similarly, DateCompact has the same value for all languages, but although the definition is global, it contains the pattern MMM and this will be substituted with the month name in the selected language.
• The predefined patterns DateVerbose is defined globally, and redefined for languages fr and en_US. The global definition will be used when any language other than fr and en_US is selected. If there was no global definition it would only be defined for fr, all regional variations of fr, and en_US.
• There is no explicit definition of patterns or names for language region en_GB. If this language is selected, the definitions for en will be used.
• There is an explicit definition for ShortMonthNames for language region en_US. If this language is selected, the definition of ShortMonthNames is as defined, and as for en for other names. As en is not defined in the dictionary, the built-in defaults are used.

Time Number to Time Number

      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

Time Number to Timestamp

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

Timestamp to Time Number

      ¯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

Timestamp to Timestamp

      ¯30 ⎕DT ⊂⎕TS
┌─────────────┐
│44216 16 5 46│
└─────────────┘

      ¯30 ¯1 ⎕DT⊂32000 15 10 0
┌───────────────────┐
│1987 8 12 15 10 0 0│
└───────────────────┘

Formatting Datetimes

      dt←1 ⎕DT ⊂2019 2 13 10 16 56
      dt
43508.42843
      'Dddd, DDoo Mmmm YYYY; hh:mm:ss' ⎕DT dt
┌───────────────────────────────────────┐
│Wednesday, 13th February 2019; 10:16:56│
└───────────────────────────────────────┘
      '__en__Dddd, DDoo Mmmm YYYY; hh:mm:ss' ⎕DT dt
┌───────────────────────────────────────┐
│Wednesday, 13th February 2019; 10:16:56│
└───────────────────────────────────────┘
      '"ISO date": %ISO%' ⎕DT dt
┌─────────────────────────────┐
│ISO date: 2019-02-13T10:16:56│
└─────────────────────────────┘
      '%DateVerbose%'(⎕DT⍠'Dictionary'dict) dt
┌───────────────────────┐
│the date is 13 Feb 2019│
└───────────────────────┘

Parsing Text Formats

      'DD/MM/YYYY' 1 ⎕DT ⊂'13/02/2019'
43508
      'DD/MM/YYYY' ¯1 ⎕DT ⊂'13/02/2019'
┌─────────────────┐
│2019 2 13 0 0 0 0│
└─────────────────┘
      'Dddd, DDoo Mmmm YYYY; hh:mm:ss' ¯1 ⎕DT ⊂'Wednesday, 13th February 2019; 10:16:56'
┌────────────────────┐
│2019 2 13 10 16 56 0│
└────────────────────┘
      '__da__Dddd, DDoo mmmm YYYY' 1 ⎕DT ⊂'Onsdag, 13. februar 2019'
43508

Languages and Dictionaries

      '__da__Dddd, DDoo mmmm YYYY; hh:mm:ss' ⎕DT dt
┌──────────────────────────────────┐
│Onsdag, 13. februar 2019; 10:16:56│
└──────────────────────────────────┘
      fmt←'Dddd, DDoo mmmm YYYY; hh:mm:ss'
      fmt(⎕DT⍠'Language' 'da') dt
┌──────────────────────────────────┐
│Onsdag, 13. februar 2019; 10:16:56│
└──────────────────────────────────┘
      '%DateVerbose%'(⎕DT⍠('Dictionary' dict)('Language' 'en_US')) dt
┌─────────────────────────┐
│the date is Feb. 13, 2019│
└─────────────────────────┘
      '__cy__Dddd, DDoo mmmm YYYY; hh:mm:ss'(⎕DT⍠'Dictionary' dict) dt
┌──────────────────────────────────────────┐
│Dydd Mercher, 13eg chwefror 2019; 10:16:56│
└──────────────────────────────────────────┘
      '__cy__%DateVerbose%'(⎕DT⍠'Dictionary' dict) dt
┌───────────────────────┐
│the date is 13 Chw 2019│
└───────────────────────┘

Validating Datetimes

      0 ⎕DT ⎕TS (2020 13 1) 'J' 'DT' #
1 0 1 0 0

      ¯30 0 ⎕DT⊂32000 15 10 0
1

      'DD/MM/YYYY' 0 ⎕DT '13/02/2019' '31/02/2019'
1 0

      'YYYY-MM-DD' 0 ⎕DT '1900-02-29' '2000-02-29'
0 1