| window.runtime property | window.runtime.flash.globalization.DateTimeFormatter |
| Inheritance | DateTimeFormatter  Object |
| Runtime Versions: | 2 |
There are two ways to select a date time format: using a predefined pattern
or a custom pattern. For most applications the predefined styles specified by the
DateTimeStyle constants (LONG, MEDIUM, NONE, or SHORT
should be used. These constants
specify the default patterns for the requested locale or the default patterns based on the
user's operating system settings.
For example the following code creates a date string using the default short date format:
var df:DateTimeFormatter = new DateTimeFormatter(LocaleID.DEFAULT, DateTimeStyle.SHORT, DateTimeStyle.NONE);
var currentDate:Date = new Date();
var shortDate:String = df.format(currentDate);
When an instance of this class is created, if the requested locale is supported by the
operating system then the properties of the instance are set according to the conventions and
defaults of the requested locale and the constructor's dateStyle and timeStyle parameters.
If the requested locale is not available, then the properties are set according to a fallback or
default system locale, which can be retrieved using the actualLocaleIDName property.
This class contains additional methods to get localized strings for month names and weekday names, and to retrieve the first day of the week that can be used in a calendar picker or other similar application.
Due to the use of the user's settings, the use of formatting patterns provided by the operating system, and the use of a fallback locale when a requested locale is not supported, different users can see different formatting results even when using the same locale ID.
See also
Hide Inherited Public Properties
Show Inherited Properties| Property | Defined By | ||
|---|---|---|---|
| actualLocaleIDName : String [read-only]
The name of the actual locale ID used by this DateTimeFormatter object. | DateTimeFormatter | ||
 | constructor : Object
A reference to the class object or constructor function for a given object instance. | Object | |
| lastOperationStatus : String [read-only]
The status of previous operation that this DateTimeFormatter object performed. | DateTimeFormatter | ||
| prototype : Object [static]
A reference to the prototype object of a class or function object. | Object | |
| requestedLocaleIDName : String [read-only]
The name of the requested locale ID that was passed to the constructor of this DateTimeFormatter object. | DateTimeFormatter | ||
| Method | Defined By | ||
|---|---|---|---|
DateTimeFormatter(requestedLocaleIDName:String, dateStyle:String = "long", timeStyle:String = "long")
Constructs a new DateTimeFormatter object to format dates and times according to the conventions of the
specified locale and the provided date and time formatting styles. | DateTimeFormatter | ||
format(dateTime:Date):String
Formats a display string for a Date object that is interpreted as being in the user's local time
(using the local time components of the Date object such as: date, day, fullYear, hours, minutes, month, and seconds). | DateTimeFormatter | ||
formatUTC(dateTime:Date):String
Formats a display string for a Date object that is interpreted as being in UTC time
(using the UTC components of the Date object such as: dateUTC, dayUTC, fullYearUTC, hoursUTC, minutesUTC, monthUTC,
and secondsUTC), according to the dateStyle, timeStyle or date time pattern. | DateTimeFormatter | ||
getAvailableLocaleIDNames():Vector.<String> [static]
Lists all of the locale ID names supported by this class. | DateTimeFormatter | ||
getDateStyle():String
Gets the date style for this instance of the DateTimeFormatter. | DateTimeFormatter | ||
getDateTimePattern():String
Returns the pattern string used by this DateTimeFormatter object to format dates and times. | DateTimeFormatter | ||
getFirstWeekday():int
Returns an integer corresponding to the first day of the week for this locale and calendar system. | DateTimeFormatter | ||
getMonthNames(nameStyle:String = "full", context:String = "standalone"):Vector.<String>
Retrieves a list of localized strings containing the month names for the current calendar system. | DateTimeFormatter | ||
getTimeStyle():String
Gets the time style for this instance of the DateTimeFormatter. | DateTimeFormatter | ||
getWeekdayNames(nameStyle:String = "full", context:String = "standalone"):Vector.<String>
Retrieves a list of localized strings containing the names of weekdays for the current calendar system. | DateTimeFormatter | ||
| hasOwnProperty(name:String):Boolean
Indicates whether an object has a specified property defined. | Object | |
| isPrototypeOf(theClass:Object):Boolean
Indicates whether an instance of the Object class is in the prototype chain of the object specified
as the parameter. | Object | |
| propertyIsEnumerable(name:String):Boolean
Indicates whether the specified property exists and is enumerable. | Object | |
setDateTimePattern(pattern:String):void
Sets the pattern string used by this DateTimeFormatter object to format dates and times. | DateTimeFormatter | ||
setDateTimeStyles(dateStyle:String, timeStyle:String):void
Sets the date and time styles for this instance of the DateTimeFormatter. | DateTimeFormatter | ||
| setPropertyIsEnumerable(name:String, isEnum:Boolean = true):void
Sets the availability of a dynamic property for loop operations. | Object | |
| toLocaleString():String
Returns the string representation of this object, formatted according to locale-specific conventions. | Object | |
| toString():String
Returns the string representation of the specified object. | Object | |
| valueOf():Object
Returns the primitive value of the specified object. | Object | |
actualLocaleIDName | property |
actualLocaleIDName:String [read-only] | Runtime Versions: | 2 |
The name of the actual locale ID used by this DateTimeFormatter object.
There are three possibilities for the value of the name, depending on operating system and the
value of the requestedLocaleIDName parameter passed to the Collator() constructor.
- If the requested locale was not
LocaleID.DEFAULTand the operating system provides support for the requested locale, then the name returned is the same as therequestedLocaleIDNameproperty. - If
LocaleID.DEFAULTwas used as the value for therequestedLocaleIDNameparameter to the constructor, then the name of the current locale specified by the user's operating system is used. TheLocaleID.DEFAULTvalue preserves user's customized setting in the OS. Passing an explicit value as therequestedLocaleIDNameparameter does not necessarily give the same result as using theLocaleID.DEFAULTeven if the two locale ID names are the same. The user might have customized the locale settings on their machine, and by requesting an explicit locale ID name rather than usingLocaleID.DEFAULTyour application would not retrieve those customized settings. - If the system does not support the
requestedLocaleIDNamespecified in the constructor then a fallback locale ID name is provided.
See also
lastOperationStatus | property |
lastOperationStatus:String [read-only] | Runtime Versions: | 2 |
The status of previous operation that this DateTimeFormatter object performed.
The lastOperationStatus property is set whenever the constructor or a method of
this class is called, or another property is set. For the possible values see the description for each method.
See also
requestedLocaleIDName | property |
requestedLocaleIDName:String [read-only] | Runtime Versions: | 2 |
The name of the requested locale ID that was passed to the constructor of this DateTimeFormatter object.
If the LocaleID.DEFAULT value was used then the name returned is "i-default".
The actual locale used can differ from the requested locale when a fallback locale is applied.
The name of the actual locale can be retrieved using the actualLocaleIDName property.
See also
DateTimeFormatter | () | Constructor |
public function DateTimeFormatter(requestedLocaleIDName:String, dateStyle:String = "long", timeStyle:String = "long")| Runtime Versions: | 2 |
Constructs a new DateTimeFormatter object to format dates and times according to the conventions of the specified locale and the provided date and time formatting styles. Date and time styles are used to set date and time formatting patterns to predefined, locale dependent patterns from the operating system.
This constructor determines if the current operating system supports the requested locale ID name.
If it is not supported then a fallback locale is used instead.
The name of the fallback locale ID can be determined from the actualLocaleIDName property.
If a fallback is used for any of the requestedLocaleIDName, dateStyle or
timeStyle parameters then the lastOperationStatus property is set
to indicate the type of fallback.
To format based on the user's current operating system preferences, pass the value LocaleID.DEFAULT
in the requestedLocaleIDName parameter to the constructor.
When the constructor is called and it completes successfully, the lastOperationStatus property is set to:
LastOperationStatus.NO_ERROR
When the requested locale ID name is not available then the lastOperationStatus
is set to one of the following:
LastOperationStatus.USING_FALLBACK_WARNINGLastOperationStatus.USING_DEFAULT_WARNING
Otherwise the lastOperationStatus property is set to one of the constants defined in
the LastOperationStatus class.
For details on the warnings listed above and other possible values of the
lastOperationStatus property see the descriptions in the LastOperationStatus class.
requestedLocaleIDName:String — The preferred locale ID name to use when determining date or time formats.
| |
dateStyle:String (default = "long")
| |
timeStyle:String (default = "long")
|
Throws
ArgumentError — if the dateStyle or timeStyle parameter is not a valid DateTimeStyle constant.
| |
TypeError — if the dateStyle or timeStyle parameter is null.
|
See also
format | () | method |
public function format(dateTime:Date):String| Runtime Versions: | 2 |
Formats a display string for a Date object that is interpreted as being in the user's local time (using the local time components of the Date object such as: date, day, fullYear, hours, minutes, month, and seconds). The formatting is done using the conventions of the locale ID and the date style and time style, or customized date pattern and time pattern, specified for this DateTimeFormatter instance.
When this method is called and it completes successfully, the lastOperationStatus property is set to:
LastOperationStatus.NO_ERROR
Otherwise the lastOperationStatus property is set to one of the constants defined in the
LastOperationStatus class.
Parameters
dateTime:Date — A Date value to be formatted. Valid range is from Jan 1, 1601 to Dec 31, 30827.
|
String — A formatted string representing the date or time value.
|
See also
formatUTC | () | method |
public function formatUTC(dateTime:Date):String| Runtime Versions: | 2 |
Formats a display string for a Date object that is interpreted as being in UTC time (using the UTC components of the Date object such as: dateUTC, dayUTC, fullYearUTC, hoursUTC, minutesUTC, monthUTC, and secondsUTC), according to the dateStyle, timeStyle or date time pattern. The formatting is done using the conventions of the locale ID and the date style and time style, or customized date pattern and time pattern, specified for this DateTimeFormatter instance.
When this method is called and it completes successfully, the lastOperationStatus property is set to:
LastOperationStatus.NO_ERROR
Otherwise the lastOperationStatus property is set to one of the constants defined in the
LastOperationStatus class.
Parameters
dateTime:Date — A Date value to be formatted. Valid range is from Jan 1, 1601 to Dec 31, 30827.
|
String — A formatted string representing the date or time value.
|
See also
getAvailableLocaleIDNames | () | method |
public function getAvailableLocaleIDNames():Vector.<String>| Runtime Versions: | 2 |
Lists all of the locale ID names supported by this class.
If this class is not supported on the current operating system, this method returns a null value.
When this method is called and it completes successfully, the lastOperationStatus property is set to:
LastOperationStatus.NO_ERROR
Otherwise the lastOperationStatus property is set to one of the constants defined in the
LastOperationStatus class.
Vector.<String> — A vector of strings containing all of the locale ID names supported by this class.
|
See also
getDateStyle | () | method |
public function getDateStyle():String| Runtime Versions: | 2 |
Gets the date style for this instance of the DateTimeFormatter. The date style is used to retrieve a
predefined date formatting pattern from the operating system.
The date style value can be set by the DateTimeFormatter() constructor, the setDateTimeStyles()
method or the setDateTimePattern() method.
When this method is called and it completes successfully, the lastOperationStatus property is set to:
LastOperationStatus.NO_ERROR
Otherwise the lastOperationStatus property is set to one of the constants defined in the
LastOperationStatus class.
String — The date style string for this formatter.
Possible values:
|
See also
getDateTimePattern | () | method |
public function getDateTimePattern():String| Runtime Versions: | 2 |
Returns the pattern string used by this DateTimeFormatter object to format dates and times.
This pattern can be set in one of three ways:
- By the
dateStyleandtimeStyleparameters used in the constructor - By the
setDateTimeStyles()method - By the
setDateTimePattern()method.
For a description of the pattern syntax, see the
setDateTimePattern() method.
When this method is called and it completes successfully, the lastOperationStatus property is set to:
LastOperationStatus.NO_ERROR
Otherwise the lastOperationStatus property is set to one of the constants defined in the
LastOperationStatus class.
String — A string containing the pattern used by this DateTimeFormatter object to format dates and times.
|
See also
getFirstWeekday | () | method |
public function getFirstWeekday():int| Runtime Versions: | 2 |
Returns an integer corresponding to the first day of the week for this locale and calendar system. A value of 0 corresponds to Sunday, 1 corresponds to Monday, and so on, with 6 corresponding to Saturday.
When this method is called and it completes successfully, the lastOperationStatus property is set to:
LastOperationStatus.NO_ERROR
Otherwise the lastOperationStatus property is set to one of the constants defined in the
LastOperationStatus class.
int — An integer corresponding to the first day of the week for this locale and calendar system.
|
See also
getMonthNames | () | method |
public function getMonthNames(nameStyle:String = "full", context:String = "standalone"):Vector.<String>| Runtime Versions: | 2 |
Retrieves a list of localized strings containing the month names for the current calendar system. The first element in the list is the name for the first month of the year.
When this method is called and it completes successfully, the lastOperationStatus property is set to:
LastOperationStatus.NO_ERROR
Otherwise the lastOperationStatus property is set to one of the constants defined in the
LastOperationStatus class.
Parameters
nameStyle:String (default = "full")
| |
context:String (default = "standalone")
|
Vector.<String> — A vector of localized strings containing the month names for the specified locale, name style, and context.
The first element in the vector, at index 0, is the name for the first month of the year; the next element is
the name for the second month of the year; and so on.
|
Throws
TypeError — if the nameStyle or context parameter is null.
|
See also
getTimeStyle | () | method |
public function getTimeStyle():String| Runtime Versions: | 2 |
Gets the time style for this instance of the DateTimeFormatter. The time style is used to retrieve a
predefined time formatting pattern from the operating system.
The time style value can be set by the DateTimeFormatter() constructor, the setDateTimeStyles()
method or the setDateTimePattern() method.
When this method is called and it completes successfully, the lastOperationStatus property is set to:
LastOperationStatus.NO_ERROR
Otherwise the lastOperationStatus property is set to one of the constants defined in the
LastOperationStatus class.
String — The time style string for this formatter.
Possible values:
|
See also
getWeekdayNames | () | method |
public function getWeekdayNames(nameStyle:String = "full", context:String = "standalone"):Vector.<String>| Runtime Versions: | 2 |
Retrieves a list of localized strings containing the names of weekdays for the current calendar system. The first element in the list represents the name for Sunday.
When this method is called and it completes successfully, the lastOperationStatus property is set to:
LastOperationStatus.NO_ERROR
Otherwise the lastOperationStatus property is set to one of the constants defined in the
LastOperationStatus class.
Parameters
nameStyle:String (default = "full")
| |
context:String (default = "standalone")
|
Vector.<String> — A vector of localized strings containing the month names for the specified locale, name style, and context.
The first element in the vector, at index 0, is the name for Sunday; the next element is the name
for Monday; and so on.
|
Throws
TypeError — if the nameStyle or context parameter is null.
|
See also
setDateTimePattern | () | method |
public function setDateTimePattern(pattern:String):void| Runtime Versions: | 2 |
Sets the pattern string used by this DateTimeFormatter object to format dates and times.
The pattern used to format dates can be set in one of three ways:
- By the
dateStyleandtimeStyleparameters used in the constructor - By the
setDateTimeStyles()method - By this
setDateTimePattern()method.
As a side effect this method overrides the current time and date styles for this DateTimeFormatter object and set them
to the value DateTimeStyle.CUSTOM.
A pattern string defines how date and times are formatted. The pattern contains sequences of letters that are replaced with date and time values in the formatted string. For example, in the pattern "yyyy/MM" the characters "yyyy" are replaced with a four-digit year, followed by a "/" character, and the characters "MM" are replaced with a two-digit month.
Many of the letters used in patterns can be repeated more than once to produce different outputs, as described in the table below.
If a sequence exceeds the maximum number of letters supported by a pattern, it is mapped back to the longest supported sequence for that pattern letter. For example:
- MMMMMM is replaced with MMMM
- dddd is replaced with dd
- EEEEEEE is replaced with EEEE
- aa is replaced with a
- hhh is replaced with hh
- mmmm is replaced with mm
In theory a pattern can contain up to 255 characters, but some platforms have stricter limit.
If the pattern exceeds the pattern character limit, the lastOperationStatus property is set to the value
LastOperationStatus.PATTERN_SYNTAX_ERROR.
Not all possible patterns are supported on each operating system. If a pattern is not supported on the platform
then a fallback pattern is used
and the lastOperationStatus property is set to indicate the use of a fallback.
If no reasonable fallback pattern can be provided, an empty string is used
and the lastOperationStatus property is set to indicate that the pattern was unsupported.
The following table describes the valid pattern letters and their meaning.
| Pattern letter | Description |
| G | Era. Replaced by the Era string for the current date and calendar. This pattern is not supported on all
operating systems. On operating systems that do not support the era, the letters of the input pattern
are replaced by an empty string.
There can be one to five letters in era patterns that are interpreted as follows:
Examples with the Gregorian Calendar(for operating systems that support this pattern):
|
| y | Year. If the number of pattern letters is two, the last two digits of the year are displayed; otherwise the number of letters determines
the number of digits. If the year value requires more digits than provided by the number of letters, then the full
year value is provided. If there are more letters than required by the value, then the year values are padded with zeros.
The following list shows the results for the years 1 and 2005.
Examples:
|
| M | Month in year. There can be one to five letters in month patterns that are interpreted as follows:
Examples:
|
| d | Day of the month. There can be one or two letters in day of the month patterns that are interpreted as follows:
Examples:
|
| E | Day in week. There can be one to five letters in day of the week patterns that are interpreted as follows:
Examples:
|
| Q | Quarter. Some platforms do not support this pattern. There can be one to four letters in quarter patterns that are interpreted as follows:
Examples (for operating systems that support this pattern):
|
| w | Week of the year. Some platforms do not support this pattern. There can be one to two letters in this pattern that are interpreted as follows.
Examples for the second week of the year (for operating systems that support this pattern):
|
| W | Week of the month. Some platforms do not support this pattern. This pattern allows one letter only.
Examples for the second week of July (for operating systems that support this pattern):
|
| D | Day of the year. Some platforms do not support this pattern. There can be one to three letters in this pattern.
Examples for the second day of the year (for operating systems that support this pattern):
|
| F | Occurrence of a day of the week within a calendar month. For example, this element displays "3"
if used to format the date for the third Monday in October. This pattern allows one letter only.
Examples for the second Wednesday in July (for operating systems that support this pattern):
|
| a | AM/PM indicator. This pattern allows one letter only, a or p.
Examples:
|
| h | Hour of the day in a 12-hour format [1 - 12]. This pattern must be one or two letters.
Examples:
|
| H | Hour of the day in a 24-hour format [0 - 23]. This pattern must be one or two letters.
Examples:
|
| K | Hour in the day in a 12-hour format [0 - 11]. This pattern must be one or two letters.
This pattern is not supported on all operating systems.
Examples (for operating systems that support this pattern):
|
| k | Hour of the day in a 24-hour format [1 - 24]. This pattern must be one or two letters.
This pattern is not supported on all operating systems.
Examples (for operating systems that support this pattern):
|
| m | Minute of the hour [0 - 59]. This pattern must be one or two letters.
Examples:
|
| s | Seconds in the minute [0 - 59]. This pattern must be one or two letters.
Examples:
|
| S | Milliseconds. This pattern must be one to five letters. The value is rounded according to the
number of letters used. When five characters are used (SSSSS) it denotes fractional milliseconds.
Examples:
|
| z | Time Zone. Represents the time zone as a string that respects standard or daylight time, without referring to a specific
location. This pattern is not supported on all operating systems. On operating systems that do not support
time zone patterns, the letters of the input pattern are replaced by an empty string. On operating
systems that do support this pattern, not all locales have a defined string. Those locales fall back
to a localized GMT format such as GMT-08:00 or GW-08:00
There must be one to four letters in this time zone pattern, interpreted as follows:
Examples for operating systems that support this format:
|
| Z | Time Zone. Represents the time zone as an offset from GMT. This pattern is not supported on all operating systems. On operating systems that do not support
time zone patterns, the letters of the input pattern are replaced by an empty string.
There must be one to four letters in this time zone pattern, interpreted as follows:
Examples for operating systems that support this format:
|
| v | Time Zone. A string reflecting the generic time zone that does not refer to a specific
location or distinguish between daylight savings time or standard time. This pattern is not supported on all operating systems. On operating systems that do not support
time zone patterns the letters of the input pattern are replaced by an empty string. On operating
systems that support this pattern, fallback strings are provided if a localized name is not
available.
There must be one or four letters in this time zone pattern, interpreted as follows:
Examples for operating systems that support this format:
|
| 'Other text' | Text and punctuation may be included in the pattern string. However the characters from a to z and A to Z, are reserved as
syntax characters and must be enclosed in single quotes to be included in
the formatted string. To include a single quote in the result string, two single quotes must be used in the
pattern string. The two single quotes may appear inside or outside a quoted portion of the pattern string.
An unmatched pair of single quotes is terminated at the end of the string.
Examples:
|
When this method is called and it completes successfully, the lastOperationStatus property is set to:
LastOperationStatus.NO_ERROR
Otherwise the lastOperationStatus property is set to one of the constants defined in the
LastOperationStatus class.
Parameters
pattern:String |
Throws
TypeError — if the pattern parameter is null.
|
See also
setDateTimeStyles | () | method |
public function setDateTimeStyles(dateStyle:String, timeStyle:String):void| Runtime Versions: | 2 |
Sets the date and time styles for this instance of the DateTimeFormatter. Date and time styles are used to set
date and time formatting patterns to predefined, locale-dependent patterns from the operating system.
This method replaces the styles that were set using the DateTimeFormatter() constructor or
using the setDateTimePattern() method. The date and time pattern is
also updated based on the styles that are set.
When this method is called and it completes successfully, the lastOperationStatus property is set to:
LastOperationStatus.NO_ERROR
Otherwise the lastOperationStatus property is set to one of the constants defined in the
LastOperationStatus class.
Parameters
dateStyle:String — Specifies the style to use when formatting dates.
The value corresponds to one of the values enumerated by the DateTimeStyle class:
| |
timeStyle:String — Specifies the style to use when formatting times.
The value corresponds to one of the values enumerated by the DateTimeStyle class:
|
Throws
ArgumentError — if the dateStyle or timeStyle parameter is not a valid DateTimeStyle constant.
| |
TypeError — if the dateStyle or timeStyle parameter is null.
|
See also
Thu Sep 29 2011, 02:34 AM -07:00