class sap.ui.core.format.DateFormat

Visiblity: public
UX Guidelines:
Implements:
Available since: N/A
Extends:
Module: sap/ui/core/format/DateFormat
Application Component: CA-UI5-COR

The DateFormat is a static class for formatting and parsing single date and time values or date and time intervals according to a set of format options.

Supported format options are pattern based on Unicode LDML Date Format notation. Please note that only a subset of the LDML date symbols is supported. If no pattern is specified a default pattern according to the locale settings is used.


Constructor


Methods Overview

Method Description
format

Format a date according to the given format options.

sap.ui.core.format.DateFormat.getDateInstance

Get a date instance of the DateFormat, which can be used for formatting.

sap.ui.core.format.DateFormat.getDateTimeInstance

Get a datetime instance of the DateFormat, which can be used for formatting.

sap.ui.core.format.DateFormat.getTimeInstance

Get a time instance of the DateFormat, which can be used for formatting.

parse

Parse a string which is formatted according to the given format options.

format

Format a date according to the given format options.

Param Type DefaultValue Description
vJSDate Date Date[]

the value to format

bUTC boolean false

whether to use UTC

sap.ui.core.format.DateFormat.getDateInstance

Get a date instance of the DateFormat, which can be used for formatting.

Param Type DefaultValue Description
oFormatOptions object

Object which defines the format options

format string

@since 1.34.0 contains pattern symbols (e.g. "yMMMd" or "Hms") which will be converted into the pattern in the used locale, which matches the wanted symbols best. The symbols must be in canonical order, that is: Era (G), Year (y/Y), Quarter (q/Q), Month (M/L), Week (w), Day-Of-Week (E/e/c), Day (d), Hour (h/H/k/K/j/J), Minute (m), Second (s), Timezone (z/Z/v/V/O/X/x) See http://unicode.org/reports/tr35/tr35-dates.html#availableFormats_appendItems

pattern string

a data pattern in LDML format. It is not verified whether the pattern represents only a date.

style string

can be either 'short, 'medium', 'long' or 'full'. If no pattern is given, a locale dependent default date pattern of that style is used from the LocaleData class.

strictParsing boolean

if true, by parsing it is checked if the value is a valid date

relative boolean

if true, the date is formatted relatively to todays date if it is within the given day range, e.g. "today", "yesterday", "in 5 days"

relativeRange int[]

the day range used for relative formatting. If oFormatOptions.relativeScale is set to default value 'day', the relativeRange is by default [-6, 6], which means only the last 6 days, today and the next 6 days are formatted relatively. Otherwise when oFormatOptions.relativeScale is set to 'auto', all dates are formatted relatively.

relativeScale string "day"

if 'auto' is set, new relative time format is switched on for all Date/Time Instances. The relative scale is chosen depending on the difference between the given date and now.

relativeStyle string "wide"

@since 1.32.10, 1.34.4 the style of the relative format. The valid values are "wide", "short", "narrow"

interval boolean false

@since 1.48.0 if true, the format method expects an array with two dates as the first argument and formats them as interval. Further interval "Jan 10, 2008 - Jan 12, 2008" will be formatted as "Jan 10-12, 2008" if the 'format' option is set with necessary symbols. Otherwise the two given dates are formatted separately and concatenated with local dependent pattern.

singleIntervalValue boolean false

Only relevant if oFormatOptions.interval is set to 'true'. This allows to pass an array with only one date object to the format method.

UTC boolean

if true, the date is formatted and parsed as UTC instead of the local timezone

calendarType sap.ui.core.CalendarType

The calender type which is used to format and parse the date. This value is by default either set in configuration or calculated based on current locale.

oLocale sap.ui.core.Locale

Locale to ask for locale specific texts/settings

sap.ui.core.format.DateFormat.getDateTimeInstance

Get a datetime instance of the DateFormat, which can be used for formatting.

Param Type DefaultValue Description
oFormatOptions object

Object which defines the format options

format string

@since 1.34.0 contains pattern symbols (e.g. "yMMMd" or "Hms") which will be converted into the pattern in the used locale, which matches the wanted symbols best. The symbols must be in canonical order, that is: Era (G), Year (y/Y), Quarter (q/Q), Month (M/L), Week (w), Day-Of-Week (E/e/c), Day (d), Hour (h/H/k/K/j/J), Minute (m), Second (s), Timezone (z/Z/v/V/O/X/x) See http://unicode.org/reports/tr35/tr35-dates.html#availableFormats_appendItems

pattern string

a datetime pattern in LDML format. It is not verified whether the pattern represents a full datetime.

style string

can be either 'short, 'medium', 'long' or 'full'. For datetime you can also define mixed styles, separated with a slash, where the first part is the date style and the second part is the time style (e.g. "medium/short"). If no pattern is given, a locale dependent default datetime pattern of that style is used from the LocaleData class.

strictParsing boolean

if true, by parsing it is checked if the value is a valid datetime

relative boolean

if true, the date is formatted relatively to todays date if it is within the given day range, e.g. "today", "yesterday", "in 5 days"@param {boolean} [oFormatOptions.UTC] if true, the date is formatted and parsed as UTC instead of the local timezone

relativeRange int[]

the day range used for relative formatting. If oFormatOptions.relativeScale is set to default value 'day', the relativeRange is by default [-6, 6], which means only the last 6 days, today and the next 6 days are formatted relatively. Otherwise when oFormatOptions.relativeScale is set to 'auto', all dates are formatted relatively.

relativeScale string "day"

if 'auto' is set, new relative time format is switched on for all Date/Time Instances. The relative scale is chosen depending on the difference between the given date and now.

relativeStyle string "wide"

@since 1.32.10, 1.34.4 the style of the relative format. The valid values are "wide", "short", "narrow"

interval boolean false

@since 1.48.0 if true, the format method expects an array with two dates as the first argument and formats them as interval. Further interval "Jan 10, 2008 - Jan 12, 2008" will be formatted as "Jan 10-12, 2008" if the 'format' option is set with necessary symbols. Otherwise the two given dates are formatted separately and concatenated with local dependent pattern.

singleIntervalValue boolean false

Only relevant if oFormatOptions.interval is set to 'true'. This allows to pass an array with only one date object to the format method.

UTC boolean

if true, the date is formatted and parsed as UTC instead of the local timezone

calendarType sap.ui.core.CalendarType

The calender type which is used to format and parse the date. This value is by default either set in configuration or calculated based on current locale.

oLocale sap.ui.core.Locale

Locale to ask for locale specific texts/settings

sap.ui.core.format.DateFormat.getTimeInstance

Get a time instance of the DateFormat, which can be used for formatting.

Param Type DefaultValue Description
oFormatOptions object

Object which defines the format options

format string

@since 1.34.0 contains pattern symbols (e.g. "yMMMd" or "Hms") which will be converted into the pattern in the used locale, which matches the wanted symbols best. The symbols must be in canonical order, that is: Era (G), Year (y/Y), Quarter (q/Q), Month (M/L), Week (w), Day-Of-Week (E/e/c), Day (d), Hour (h/H/k/K/j/J), Minute (m), Second (s), Timezone (z/Z/v/V/O/X/x) See http://unicode.org/reports/tr35/tr35-dates.html#availableFormats_appendItems

pattern string

a time pattern in LDML format. It is not verified whether the pattern only represents a time.

style string

can be either 'short, 'medium', 'long' or 'full'. If no pattern is given, a locale dependent default time pattern of that style is used from the LocaleData class.

strictParsing boolean

if true, by parsing it is checked if the value is a valid time

relative boolean

if true, the date is formatted relatively to todays date if it is within the given day range, e.g. "today", "yesterday", "in 5 days"

relativeRange int[]

the day range used for relative formatting. If oFormatOptions.relativeScale is set to default value 'day', the relativeRange is by default [-6, 6], which means only the last 6 days, today and the next 6 days are formatted relatively. Otherwise when oFormatOptions.relativeScale is set to 'auto', all dates are formatted relatively.

relativeScale string "day"

if 'auto' is set, new relative time format is switched on for all Date/Time Instances. The relative scale is chosen depending on the difference between the given date and now.

relativeStyle string "wide"

@since 1.32.10, 1.34.4 the style of the relative format. The valid values are "wide", "short", "narrow"

interval boolean false

@since 1.48.0 if true, the format method expects an array with two dates as the first argument and formats them as interval. Further interval "Jan 10, 2008 - Jan 12, 2008" will be formatted as "Jan 10-12, 2008" if the 'format' option is set with necessary symbols. Otherwise the two given dates are formatted separately and concatenated with local dependent pattern.

singleIntervalValue boolean false

Only relevant if oFormatOptions.interval is set to 'true'. This allows to pass an array with only one date object to the format method.

UTC boolean

if true, the time is formatted and parsed as UTC instead of the local timezone

calendarType sap.ui.core.CalendarType

The calender type which is used to format and parse the date. This value is by default either set in configuration or calculated based on current locale.

oLocale sap.ui.core.Locale

Locale to ask for locale specific texts/settings

parse

Parse a string which is formatted according to the given format options.

Param Type DefaultValue Description
sValue string

the string containing a formatted date/time value

bUTC boolean

whether to use UTC, if no timezone is contained

bStrict boolean

to use strict value check