Final Class: IntlDateTimeConverter

Oracle® JavaScript Extension Toolkit (JET)
9.1.0
F30737-01

Signature:

final class IntlDateTimeConverter

QuickNav

Methods

Type Definitions

IntlDateTimeConverter

Version:
  • 9.1.0
Since:
  • 0.6.0
Module:
  • ojconverter-datetime

Module usage

See JET Module Loading for an overview of module usage within JET.

Javascript Import Format
define(['ojs/ojconverter-datetime'], function(converterDatetime) {
 // Application should call API on converterDatetime.IntlDateTimeConverter 
})
Typescript Import Format
//To import this class, use the format below.
import {IntlDateTimeConverter} from "ojs/ojconverter-datetime";

JET In Typescript

A detailed description of working with JET elements and classes in your typescript project can be found at: JET Typescript Usage.

Final classes in JET

Classes in JET are generally final and do not support subclassing. At the moment, final is not enforced. However, this will likely change in an upcoming JET release.

Description

Constructs an immutable instance and initializes it with the options provided.

The converter instance uses locale symbols for the locale set on the page (returned by oj.Config#getLocale.

There are several ways to initialize the converter.
  • Using options defined by the ECMA 402 Specification, these would be the properties year, month, day, hour, minute, second, weekday, era, timeZoneName, hour12
  • Using a custom date and/or time format pattern using the 'pattern' property
  • Using the standard date, datetime and time format lengths defined by Unicode CLDR, these would include the properties formaType, dateFormat, timeFormat.

The options when specified take precendence in the following order:
1. pattern.
2. ECMA options.
3. formatType/dateFormat/timeFormat.

The converter provides great leniency when parsing a user input value to a date in the following ways:

  • Allows use of any character for separators irrespective of the separator specified in the associated pattern. E.g., if pattern is set to 'y-M-d', the following values are all valid - 2013-11-16, 2013/11-16 and 2013aaa11xxx16.
  • Allows specifying 4 digit year in any position in relation to day and month. E.g., 11-2013-16 or 16-11-2013
  • Supports auto-correction of value, when month and day positions are swapped as long as the date is > 12 when working with the Gregorian calendar. E.g., if the pattern is 'y-M-d', 2013-16-11 will be auto-corrected to 2013-11-16. However if both date and month are less or equal to 12, no assumptions are made about the day or month and the value parsed against the exact pattern.
  • Supports auto-correction of value, for the short and long types of weekday and month names. So they can are used anywhere in the value. E.g., if the expected pattern is E, MMM, d, y, all these values are acceptable - Tue, Nov 26 2013 or Nov, Tue 2013 26 or 2013 Tue 26 Nov.
    NOTE: Lenient parsing of narrow era, weekday or month name is not supported because of ambiguity in choosing the right value. So we expect for narrow era, weekday or month option that values be provided either in their short or long forms. E.g., Sat, March 02, 2013.
  • Specifying the weekday is optional. E.g., if the expected pattern is E, MMM, d, y; then entering Nov 26, 2013, is automatically turned to Tuesday Nov 26, 2013. But entering an invalid weekday, i.e., if the weekday does not match the date, an exception is thrown.
  • Leniency rules apply equally no matter which option is used - pattern, ECMA options or formatType

Lenient parse can be disabled by setting the property lenientParse to "none". In which case the user input must be an exact match of the expected pattern and all the leniency described above will be disabled.

Constructor

new IntlDateTimeConverter(options)

Parameters:
Name Type Argument Description
options oj.IntlDateTimeConverter.ConverterOptions <optional>
 an object literal used to provide an optional information to initialize the converter.

Methods

calculateWeek(value) : {number}

Returns the calculated week for the isoString value
Parameters:
Name Type Description
value string to return the calculated week of
Returns:
calculated week.
Type
number

compareISODates(isoStr, isoStr2) : {number}

Compares 2 ISO 8601 strings, returning the time difference between the two
Parameters:
Name Type Description
isoStr string first iso string
isoStr2 string second iso string
Returns:
the time difference between isoStr and isoStr2
Type
number

format(value) : {string|null}

Formats the isoString value using the options provided and returns a string value.

Parameters:
Name Type Description
value string to be formatted for display which should be an isoString
See:
Throws:
a ConverterError both when formatting fails, and if the options provided during initialization cannot be resolved correctly.
Type
Error
Returns:
the formatted value suitable for display
Type
string | null

formatRelative(value, relativeOptions) : {string|null}

Formats an ISOString as a relative date time, using the relativeOptions.

Parameters:
Name Type Argument Description
value string value to be formatted. This value is compared with the current date on the client to arrive at the relative formatted value.
relativeOptions Object <optional>
 an Object literal containing the following properties. The default options are ignored during relative formatting -
Properties
Name Type Argument Description
formatUsing string <optional>
 Specifies the relative formatting convention to. Allowed values are "displayName" and "calendar". Setting value to 'displayName' uses the relative display name for the instance of the dateField, and one or two past and future instances. When omitted we use the implicit rules.
dateField string <optional>
 To be used in conjunction of 'displayName' value of formatUsing attribute. Allowed values are: "day", "week", "month", "year", "hour", "minute", "second".
relativeTime string <optional>
 Allowed values are: "fromNow", "toNow". "fromNow" means the system's current date is the reference and "toNow" means the value attribute is the reference. Default "fromNow".
dateOnly boolean <optional>
 A boolean value that can be used in conjunction with "calendar" of formatUsing attribute. When set to true date only format is used. Example: "Sunday" instead of "Sunday at 2:30 PM". Default value is false.
timeZone string <optional>
 The timeZone attribute can be used to specify the time zone of the value parameter. The system’s time zone is used for the current time. If timeZone attribute is not specified, we use the system’s time zone for both. The value parameter, which is an iso string, can be Z or contain and offset, in this case the timeZone attribute is overwritten.
See:
Throws:
an instance of oj.ConverterError
Type
Object
Returns:
relative date. null if the value falls out side the supported relative range.
Type
string | null

getAvailableTimeZones : {Array}

Gets the supported timezones for the converter. The returned value is an array of objects. Each object represents a timezone and contains 2 properties:

Property Description
id IANA timezone ID
displayName
    It is the concatenation of 3 string:
  • UTC timezone offset
  • City name
  • Generic time zone name

Since:
  • 4.0.0
Returns:
supported timezones
Type
Array

getHint : {null}

It returns null for the placeholder hint. There is no default placeholder hint when using IntlDateTimeConverter.
Returns:
hint for the converter.
Type
null

getOptions : {oj.IntlDateTimeConverter.ConverterOptions}

Returns the options called with converter initialization.
Returns:
an object of options.
Type
oj.IntlDateTimeConverter.ConverterOptions

isDayNameSet : {boolean}

Returns true if the day name is shown in the date portion; false otherwise.
Returns:
Type
boolean

isDaySet : {boolean}

Returns true if day is shown in the date portion; false otherwise.
Returns:
Type
boolean

isHourInAMPMSet : {boolean}

Returns true if 12-hour is set; false otherwise.
Returns:
Type
boolean

isHourInDaySet : {boolean}

Returns true if a 24-hour format is set; false otherwise.
Returns:
Type
boolean

isMilliSecondSet : {boolean}

Returns true if milliseconds are shown in the time portion; false otherwise.
Returns:
Type
boolean

isMinuteSet : {boolean}

Returns true if minutes are shown in the time portion; false otherwise.
Returns:
Type
boolean

isMonthSet : {boolean}

Returns true if month is shown in the date portion; false otherwise.
Returns:
Type
boolean

isSecondSet : {boolean}

Returns true if seconds are shown in the time portion; false otherwise.
Returns:
Type
boolean

isYearSet : {boolean}

Returns true if year is shown in the date portion; false otherwise.
Returns:
Type
boolean

parse(value) : {string|null}

Parses the value using the options provided and returns the date and time as a string expressed using the ISO-8601 format (http://en.wikipedia.org/wiki/ISO_8601).

For converter options specific to a date, the iso date representation alone is returned.
For time only options, the iso time representation alone is returned.
For options that include both date and time, the iso date and time representation is returned.

For convenience, if one wishes to retrieve a JavaScript Date object from the local isoString, a utility function oj.IntlConverterUtils.isoToLocalDate is provided. Or oj.IntlConverterUtils.isoToDate if one wish to utilize the timezone of the isoString.

Parameters:
Name Type Description
value string to parse
See:
Throws:
a ConverterError both when parsing fails, and if the options provided during initialization cannot be resolved correctly. Parsing can also fail when the value includes a time zone.
Type
Error
Returns:
the parsed value as an ISOString.
Type
string | null

resolvedOptions : {oj.IntlDateTimeConverter.ConverterOptions}

Returns an object literal with locale and formatting options computed during initialization of the object. If options was not provided at the time of initialization, the properties will be derived from the locale defaults.
Throws:
a oj.ConverterError when the options that the converter was initialized with are invalid.
Returns:
an object of resolved options. Properties whose corresponding internal properties are not present are not assigned.
Type
oj.IntlDateTimeConverter.ConverterOptions

Type Definitions

ConverterOptions

Properties:
Name Type Argument Description
year '2-digit' | 'numeric' <optional>
 allowed values are "2-digit", "numeric". When no options are set the default value of "numeric" is used.

Option Description Example
2-digit 2 digit representation of the year, padded: 00-99. 2001 => 01, 2016 => 16
numeric variable digit representation of the year depending on the value. 2010, 199

two-digit-year-start number <optional>
 the 100-year period 2-digit year. During parsing, two digit years will be placed in the range two-digit-year-start to two-digit-year-start + 100 years. The default is 1950.

Example: if two-digit-year-start is 1950, 10 is parsed as 2010

Example: if two-digit-year-start is 1900, 10 is parsed as 1910

month '2-digit' | 'numeric' | 'narrow' | 'short' | 'long' <optional>
 specifies how the month is formatted. Allowed values are "2-digit", "numeric", "narrow", "short", "long". The last 3 values behave in the same way as for weekday, indicating the length of the string used. When no options are set the default value of "numeric" is used.

Option Description Example
2-digit 2 digit representation of the month, padded: 01-12. 1 => 01, 12 => 12
numeric variable digit representation of the month depending on the value. 1, 11
narrow narrow name of the month. J
short abbreviated name of the month. Jan
long wide name of the month. January

day '2-digit' | 'numeric' <optional>
 specifies how the day is formatted. Allowed values are "2-digit", "numeric". When no options are set the default value of "numeric" is used.

Option Description Example
2-digit 2 digit representation of the day in month, padded: 01-31. 1 => 01, 27 => 27
numeric variable digit representation of the day in month depending on the value. 1, 31

hour '2-digit' | 'numeric' <optional>
 specifies how the hour is formatted. Allowed values are "2-digit" or "numeric". The hour is displayed using the 12 or 24 hour clock, depending on the locale. See 'hour12' for details.

Option Description Example
2-digit 2 digit representation of the hour, padded: 01-24 depending on the locale. 1 => 01, 24 => 24
numeric variable digit representation of the day in month depending on the value. 1, 24

minute '2-digit' | 'numeric' <optional>
 specifies how the minute is formatted. Allowed values are "2-digit", "numeric". Although allowed values for minute are numeric and 2-digit, minute is always displayed as 2 digits: 00-59.
second '2-digit' | 'numeric' <optional>
 specifies whether the second should be displayed as "2-digit" or "numeric". Although allowed values for second are numeric and 2-digit, second is always displayed as 2 digits: 00-59.
millisecond 'numeric' <optional>
 specifies how the minute is formatted. Allowed value is "numeric". millisecond is always displayed as 3-digits except the case where only millisecond is present (hour and minute not specified) in which case we display it as no-padded number, example: .5
weekday 'narrow' | 'short' | 'long' <optional>
 specifies how the day of the week is formatted. If absent, it is not included in the date formatting. Allowed values are "narrow", "short", "long" indicating the length of the string used.

Option Description Example
narrow narrow name of the day of week. M
short abbreviated name of the day of week. Mon
long wide name of the day of week. Monday

era 'narrow' | 'short' | 'long' <optional>
 specifies how the era is included in the formatted date. If absent, it is not included in the date formatting. Allowed values are "narrow", "short", "long". Although allowed values are narrow, short, long, we only display era in abbreviated format: BC, AD.
timeZoneName 'short' | 'long' <optional>
 allowed values are "short", "long".

Option Description Example
short short name of the time zone. short: short name of the time zone: PDT, PST, EST, EDT. Note: Not all locales have translations for short time zone names, in this case we display the English short name
long short name of the time zone. Pacific Standard Time, Pacific Daylight Time.

timeZone string <optional>
 The possible values of the timeZone property are valid IANA timezone IDs. If the users want to pass an offset, they can use one of the Etc/GMT timezone IDs.

Option Example
IANA ID America/Los_Angeles, Europe/Paris
Offset Etc/GMT-8. The offset is positive if the local time zone is behind UTC and negative if it is ahead. The offset range is between Etc/GMT-14 and Etc/GMT+12 (UTC-12 and UTC+14). Which means that Etc/GMT-8 is equivalent to UTC+08.

isoStrFormat 'offset' | 'zulu' | 'local' | 'auto' <optional>
 specifies in which format the ISO string is returned. The possible values of isoStrFormat are: "offset", "zulu", "local", "auto". The default format is auto.

Option Description Example
offset time zone offset from UTC. 2016-01-05T11:30:00-08:00
zulu zulu time or UTC time. 2016-01-05T19:30:00Z
local local time, does not contain time zone offset. 2016-01-05T19:30:00
auto auto means the returned ISO string depends on the input string and options

dst boolean <optional>
 The dst option can be used for time only values in conjunction with offset. Setting dst to true indicates the time is in DST. By default the time is interpreted as standard time. The possible values of dst are: "true" or "false". Default is "false".

Due to Daylight Saving Time, there is a possibility that a time exists twice If the time falls in the duplicate window (switching from daylight saving time to standard time). The application can disambiguate the time in the overlapping period using the dst option. Setting dst to true indicates the time is in DST. By default the time is interpreted as standard time.

Example: On November 1st, 2105 in US the time between 1 and 2 AM will be repeated. The dst option can indicate the distinction as follows. Initially the time is in DST, so dst:'true' is specified.
var options = {formatType:'datetime', dateFormat:'short', timeFormat:'medium', timeZone:'America/Los_Angeles', isoStrFormat: 'offset', dst : true};
var localeElements = oj.getLocaleElemnts();
var str= "11/1/15 1:59:59 AM";
cnv.parse(str, localeElements, options);-->2015-11-01T01:59:59-07:00

If the user does not pass the dst option, the time will be interpreted as standard time. var options = {formatType:'datetime', dateFormat:'short', timeFormat:'medium', timeZone:'America/Los_Angeles'};
var localeElements = oj.getLocaleElemnts();
var str= "11/1/15 1:59:59 AM";
cnv.parse(str, localeElements, options);-->2015-11-01T01:59:59-08:00

At 2AM, DST will be over and the clock brings back to 1AM. Then the dst option should be false or not specified. var options = {formatType:'datetime', dateFormat:'short', timeFormat:'medium', timeZone:'America/Los_Angeles', isoStrFormat: 'offset'};
var localeElements = oj.getLocaleElemnts();
var str= "11/1/15 1:00:00 AM";
cnv.parse(str, localeElements, options);-->2015-11-01T01:00:00-08:00

hour12 boolean <optional>
 specifies what time notation is used for formatting the time. A true value uses the 12-hour clock and false uses the 24-hour clock (often called military time in the US). This property is undefined if the hour property is not used when formatting the date.

Option Example
true T13:10 is formatted as "1:10 PM"
false T13:10 is formatted as "13:10"

pattern string <optional>
 a localized string pattern, where the the characters used in pattern conform to Unicode CLDR for date time formats. This will override all other options when present.
NOTE: 'pattern' is provided for backwards compatibility with existing apps that may want the convenience of specifying an explicit format mask. Setting a 'pattern' will override the default locale specific format. NOTE: The supported tokens for timezone are of 'Z', 'VV', and 'X'.

Letter Date or Time Component Examples
G, GG, GGG Era designator AD
y numeric representation of year 1, 2014
yy 2-digit representation of year 01, 14
yyyy 4-digit representation of year 0001, 2014
M Numeric representation of month in year: (1-12) 1, 12
MM 2-digit representation of month in year: (01-12) 01, 12
MMM Formatted name of the month, abbreviated Jan
MMMM Formatted name of the month, wide January
MMMMM Formatted name of the month, narrow J
LLL Stand-alone name of the month, abbreviated Jan
LLLL Stand-alone name of the month, wide January
LLLLL Stand-alone name of the month, narrow J
d Numeric representation of day in month (1-31) 1, 21
dd 2-digit representation of day in month (01-31) 01, 21
E, EE, EEE Formatted name of day in week, abbreviated Tue
EEEE Formatted name of day in week, wide Tuesday
EEEEE Formatted name of day in week, narrow T
c, cc, ccc Stand-alone name of day in week, abbreviated Tue
cccc Stand-alone name of day in week, wide Tuesday
ccccc Stand-alone name of day in week, narrow T
a am/pm marker PM
H Numeric hour in day (0-23) 1, 23
HH 2-digit hour in day (00-23) 01, 23
h Numeric hour in am/pm (1-12) 1, 12
hh 2-digit hour in day (01-12) 01, 12
k Numeric hour in day (1-24) 1, 24
kk 2-digit hour in day (1-24) 01, 24
K Numeric hour in am/pm (0-11) 1, 11
KK 2-digit hour in am/pm (0-11) 01, 11
m, mm 2-digit minute in hour (00-59) 05, 59
s, ss 2-digit second in minute (00-59) 01, 59
S Numeric Millisecond (0-999) 1, 999
SS 2-digit Millisecond (00-999) 01, 999
SSS 3-digit Millisecond (000-999) 001, 999
z, zz, zzz Abbreviated time zone name PDT, PST
zzzz Full time zone name Pacific Standard Time, Pacific Daylight Time
Z, ZZ, ZZZ Sign hours minutes -0800
X Sign hours -08
XX Sign hours minutes -0800
XXX Sign hours:minutes -08:00
VV Time zone ID Americs/Los_Angeles
formatType 'date' | 'time' | 'datetime' <optional>
 determines the 'standard' date and/or time format lengths to use. Allowed values: "date", "time", "datetime". See 'dateFormat' and 'timeFormat' options. When set a value must be specified.

Option Description Example
datetime date and time portions are displayed. "September 20, 2015 12:04 PM", "September 20, 2015 12:05:35 PM Pacific Daylight Time"
date date portion only is displayed. "September 20, 2015"
time time portion only is displayed. “12:05:35�?

dateFormat 'short' | 'medium' | 'long' | 'full' <optional>
 specifies the standard date format length to use when formatType is set to "date" or "datetime". Allowed values are : "short" (default), "medium", "long", "full".

Option Example
short 9/20/15
medium Sep 20, 2015
long September 20, 2015
full Sunday, September 20, 2015

timeFormat 'short' | 'medium' | 'long' | 'full' <optional>
 specifies the standard time format length to use when 'formatType' is set to "time" or "datetime". Allowed values: "short" (default), "medium", "long", "full".

Option Example
short 12:11 PM
medium 12:11:23 PM
long 12:12:19 PM PDT
full 12:12:37 PM Pacific Daylight Time

lenientParse 'full' | 'none' <optional>
 The lenientParse property can be used to enable or disable leninet parsing. Allowed values: "full" (default), "none".

By default the lenient parse is enabled and the leniency rules descibed above will be used. When lenientParse is set to "none" the lenient parse is disabled and the user input must match the expected input otherwise an exception will be thrown.