Date/time masks

A date/time mask can serve one of two purposes: Determines the format of the output of various functions or guides the conversion from a string representation of a value to the internal form of that value.

Following are two ways that a date/time mask can be used:

  • It determines the format of the output of various functions. For example, in the timetostring function, the date/time mask indicates the format to use for the string output. If the date/time mask is "hh:tt:ss" and the time value is equivalent to 24 seconds past 9:12 a.m., the string output is 09:12:24.
  • It guides the conversion from a string representation of a value to the internal form of that value. For example, in the stringtotime function, the date/time mask indicates the format of the input string so that it will be correctly converted to a time value. If the input string is "05/06/1995", the date/time mask "mm/dd/yyyy" indicates that the substring "05" represents the month, rather than the day.

A date/time mask is a string expression containing any valid combination of components and, optionally, separators. Because the date/time mask is a string, you must surround it with double-quotes.

For usage examples, see the information about date/time mask samples.

Components

Following are the components allowed in a date/time mask. Where applicable, the valid range of each component is listed.

Table 1. Table of date/time mask components
Component Meaning
dd Two-digit day of the month (1-31).
ddd Three-digit day of the year (1-366).
mm One- or two-digit month (1-12).
mon Three-letter abbreviation of the month (Jan-Dec).
month Full name of the month (January-December).
yy Two-digit year (00-99).

We strongly recommend using the four-digit component (yyyy) rather than the two-digit component. With the two-digit component, internally the first two digits are assumed to be "20," which might not be your intention. In addition, using the four-digit component clearly identifies the century and eliminates any ambiguity problems.
yyyy Four-digit year (0000-9999).
w One-digit day of the week (0-6, 0 = Sunday, 6 = Saturday).
day Three-letter abbreviation of the day (Sat-Sun).
dayname Full name of the day (Sunday-Saturday).
hh Hour of day (0-23).
tt Minute of hour (0-59).
ss Second of minute (0-59).
am Indicates the time as am or pm (as opposed to a 24-hour clock).
xs:datetime

Indicates the date and time in XML format as described by W3C XML Schema and ISO 8601. The format is:

CCYY-MM-DDThh:mm:ss

All fields must be present and can optionally be preceded by a sign and leading figures, if needed, and followed by fractional digits for the seconds and a time zone. The time zone can be specified using the letter "Z" which identifies UTC or by the difference of time with UTC.

Separators

The following symbols are valid separators. Using separators is optional.

Table 2. Table of valid separator symbols
Separator symbol Separator symbol Separator symbol
, . /
- < >
? : |
^ ; "
[ ] {
} _ =
@ % +
( ) *
& # <space>

Samples

In all the examples, the time is equivalent to:
  • Wednesday, June 8, 2000 at 32 seconds after 2:05 p.m.
Table 3. Table of time date masks and results for the example
Mask Results 
"mon. dd, yyyy"
 Jun. 8, 2000 
"month dd, yyyy"
 June 8, 2000 
"mon dd, yy (day)"
 Jun 8, 00 (Wed) 
''hhttss"
 140532 
"hh:tt am"
 02:05 pm 
"dd-mm-yy, hh:tt"
 8-6-00, 14:05 
"mm/dd/yyyy, hh:tt:ss am"
 6/8/2000, 02:05:032 pm 
"ddd, hh:tt:ss"
 167, 14:05:32 
"tt:ss am"
 05:32 pm 
"xs:datetime"
 2000-06-08T14:05:32