Formats a date using a given locale.
Text = SRP_Date("Format", Date, Format = "Short", Locale = "") |
Formatted text.
Parameter | Description |
---|---|
Date | A date in OI internal format. (REQUIRED) |
Format | A custom or predefined format. (OPTIONAL) |
Locale | A locale for culture specific formatting. (OPTIONAL) |
The "Format" service converts an OI date into human readable text, much like OConv. Unlike OConv, however, this service supports infinite formatting options and localization.
You can set Format to either "Short" or "Long". In either case, the Locale will determine the format. Here are some examples, all formatting the date January 14, 2020:
Locale | Short Format | Long Format |
---|---|---|
en-US | 1/14/2020 | Tuesday, January 14, 2020 |
es-ES | 14/01/2020 | martes, 14 de enero de 2020 |
fr-FR | 14/01/2020 | mardi 14 janvier 2020 |
If you omit Format or set it to "", then "Short" will be used.
You customize the format using a special syntax. You can use any characters in the Format, but 'Y', 'y', 'M', 'm', 'D', and 'd' are reserved characters. Any other character is treated as a literal and is displayed as is. Thus, you may use literal characters in your format to prefix or suffix the date as you choose. If you need to use any reserved characters literally, then surround your literal text in single or double quotes. If you need to display quotes, place two of them side by side. The reserved characters are interpreted as follows:
Character(s) | Displays | Example using 1/14/2020 | Example using es-ES |
---|---|---|---|
YY | 2-digit year | 20 | 20 |
YYYY | Year | 2020 | 2020 |
M | Month | 1 | 1 |
MM | 2-digit Month | 01 | 01 |
MMM | Abbreviated month name | Jan | ene. |
MMMM | Month name | January | enero |
MMMMM | Month initial | J | e |
D | Day | 14 | 14 |
DD | 2-digit day | 14 | 14 |
DDD | Abbreviate day of the week name | Tue | ma. |
DDDD | Day of the week | Tuesday | martes |
DDDDD | Shortest day of the week name | Tu | M |
As you can see in the table above, the Locale still affects the output, but only when your format requests names. months from minutes.
Here are some example date formats, all them for the date January 14, 2020:
Format | en-US | es-ES | fr-FR |
---|---|---|---|
MMMM D, YYYY | January 14, 2020 | enero 14, 2020 | janvier 14, 2020 |
DDDD, MMM DD, YYYY | Sunday, Jan 01, 2006 | martes, ene. 14, 2020 | mardi, janv. 14, 2020 |
M/D/YY | 1/14/20 | 1/14/20 | 1/14/20 |
YYYY-MM-DD | 2020-01-14 | 2020-01-14 | 2020-01-14 |
"Happy New Year! It's" MMMM DD! | Happy New Year! It's January 14! | Happy New Year! It's enero 14! | Happy New Year! It's janvier 14! |
Only uppercase letters are used in the examples here, but lowercase are supported as well. However, we recommend using uppercase for dates because SRP_DateTime uses 'M' for months and 'm' for minutes.
The Locale parameter specifies the specific culture used to help render the final text. Omitting Locale or setting it "" causes the "Format" service to use the user's current locale setting. If, however, you want to specify your own localization, set this parameter to a locale name. Locale names have a complex syntax that allow you to specify all manner of aspects, but in 99.99% of cases, you'll use the format "language-REGION". Here, language is a lowercase ISO 639-1 language code. REGION specifies an uppercase ISO 3166-1 country/region identifier. The region is optional. For example, the locale name for English is "en", the locale name for English (United States) is "en-US", and the locale name for Divehi (Maldives) is "dv-MV".
Here is a chart for the 200 most common languages and regions:
|
// Create an OI date Date = SRP_Date("Encode", 2020, 1, 14) // Format a date using the default format and the current locale Text = SRP_Date("Format", Date) // Format a date using the long format and the current locale Text = SRP_Date("Format", Date, "Long") // Format a date using the long format and the Spanish language Text = SRP_Date("Format", Date, "Long", "es") // Format a date using a custom format and the Spanish-MEXICAN language Text = SRP_Date("Format", Date, "MMMM D, YYYY", "es-MX") |