Date/time masks and format specifiers

The default mask is yyyyMM.

  yyyyyyMM
  yyyyyy
  MM

  ddHHmmssffffff
  HHmmssff
  mmss
  HHmm

  // NOT valid
  ddmmssffffff 
  HHssff

The default mask is yyyyMMddHHmmss.

The rules for a parsing format are similar to those for a display format, with exceptions noted in the following rules.

Create your own format pattern by using letters to indicate the components of the date or time. To include letters in the date/time string without that text being parsed as a component of the date or time, enclose that letter or letters in single quotation marks. To display a single quotation mark in the date, time, or timestamp, use two single quotation marks.

The following table lists the letters and their values in the pattern.

Multiples of the same letter used consecutively in the pattern determine how EGL parses the corresponding numbers, letters, or both in the string. The interpretation depends on the type of letter, and on whether the pattern is being used for formatting or parsing. The following list describes the types of letters and how different quantities of those letters affect the way they are interpreted.

Text

For output, if the number of letters is greater than 4, the full form is used. Otherwise, an abbreviation is used, if available. In parsing, both forms are accepted, independent of the number of pattern letters.

Number

For output, the number of pattern letters represents the minimum number of digits. zeros are added to shorter numbers to make them the designated length. For parsing, the number of pattern letters is ignored unless it is needed to separate two adjacent fields.

Year

For formatting, if the number of pattern letters is 2, the year is truncated to 2 digits. Otherwise, it is interpreted as the Number type.

For parsing, if the number of pattern letters is not 2, the year is interpreted literally, regardless of the number of digits. For example, the pattern MM/dd/yyyy assigned the value 01/11/12 parses to January 11, 12 A.D. The same pattern assigned the value 01/02/3 or 01/02/0003 parses to January 2, 3 A.D. In the same way, the same pattern assigned the value 01/02/-3 parses to January 2, 4 B.C.

For parsing, if the pattern is yy, the parser determines the full year relative to the current year. The parser assumes that the two-digit year is within 80 years before or 20 years after the time of processing. For example, if the current year is 2007, the pattern MM/dd/yy assigned the value 01/11/12 parses to January 11, 2012, while the same pattern assigned the value 05/04/64 parses to May 4, 1964.

Month

If the number of pattern letters is 3 or more, the month is interpreted as the Text type. Otherwise, it is interpreted as the Number type.

Milliseconds

Use SSSS to format an INTERVAL or TIMESTAMP variable. (Use ffff instead when you declare the variable.) Consider the following examples:

t TIMESTAMP( "ssffff" );
s STRING = StrLib.formatTimestamp( t, "ssSSSS" );

General time zone

General time zones are interpreted as the Text type if they have names. For time zones representing a GMT offset value, the following syntax is used:

GMTOffsetTimeZone = GMT Sign Hours Minutes

Sign

Either + or -

Hours

A one-digit or two-digit number from 0 to 23. The format is locale independent and must be taken from the Basic Latin block of the Unicode standard.

Minutes

A two-digit number from 00 to 59. The format is locale independent and must be taken from the Basic Latin block of the Unicode standard.

For parsing, RFC 822 time zones are also accepted.

RFC 822 time zone

For formatting, the RFC 822 4-digit time zone format is used

RFC822TimeZone = Sign TwoDigitHours Minutes

TwoDigitHours must be a two-digit number from 00 to 23. The other definitions are the same as the General time zone type.

For parsing, General time zones are also accepted.

Century

Displayed as a Number type that shows the result of the following calculation: full year divided by 100, with the remainder ignored.

The following table lists some examples of date and time patterns interpreted in the U.S. locale. All use the same date: 4 July, 2001, 12:08:56 in the afternoon, Pacific Daylight Time.

The date/time format specifiers can also include calendar specifiers. These specifiers indicate a calendar system that EGL uses to parse a date string for input, or format a date string for output. EGL performs a conversion between the string date for a specified calendar and the internal value of the DATE, TIME, or TIMESTAMP variable.

This subject becomes complex quickly because localized date strings in the various calendar systems might not be printable in other locales. Different calendars use different starting points for numbering years, as well as different era designators, many of which display properly only in specific localized environments. For example, the Japanese Imperial date system ties dates to the reigns of Japanese emperors as well as to the old-style Julian Calendar (which is several days behind the Gregorian).

myDate DATE;
myJapaneseDate STRING;

strLib.defaultDateFormat = "Gryyyy/MM/dd";
myDate = "1912/08/13";
myJapaneseDate = formatDate(myDate,"JaGyy/MM/dd");

The following table lists sample Gregorian dates as converted to the Japanese era format specified above. The names in brackets represent the four double-byte Japanese characters for a specific Japanese era.

EGL uses the Java™ version of the International Components for Unicode libraries (ICU4J) to perform the necessary date conversions for input and display. However, EGL always stores the dates in Gregorian form using eight digits. This means that if a Thai application requests a date from the Buddhist calendar, EGL stores that date in eight-digit Gregorian form using ICU4J for the conversion. As long as the application is consistent in the patterns it uses, this process remains invisible to both the programmer and the user.