Date time formatting
Charba provide a date time format implementation which enables language-sensitive date time formatting, leveraging on INTL platform.
// creates a date time format
DateTimeFormat dateTimeFormat = new DateTimeFormat();
// formats the date, shows the current date,
// for instance "4/1/2021", M/d/YYYY
Console.log(numberFormat.format(new Date()));
// creates a date time format
// with a locale
DateTimeFormat dateTimeFormat = new DateTimeFormat(CLocale.GERMANY);
// formats the date, shows the current date
// for instance "1.4.2021", d.M.YYYY
Console.log(numberFormat.format(new Date()));
Creating
A date time format can be created and consumed as following:
// creates locale
CLocale german = CLocaleBuilder.create(Language.GERMAN).build();
// creates a date time format
// with default locale and
// default options
DateTimeFormat dateTimeFormat = new DateTimeFormat();
// creates a date time format
// with a locale and
// default options
DateTimeFormat dfGerman = new DateTimeFormat(german);
// creates date time format options
DateTimeFormatOptions options = new DateTimeFormatOptions();
// creates a date time format
// with a locale and
// specific options
DateTimeFormat dfGermanOptions = new DateTimeFormat(german, options);
Options
A date time format can be configured, when created, by the set of options which can change the date time formatting, together with the locale.
// creates locale
CLocale german = CLocaleBuilder.create(Language.GERMAN).build();
// creates date format options
DateTimeFormatOptions options = new DateTimeFormatOptions();
// sets the date time styles
options.setDateStyle(DateTimeStyle.LONG);
options.setTimeStyle(DateTimeStyle.MEDIUM);
// creates a date time format
// with a locale and
// specific options
DateTimeFormat dfGermanOptions = new DateTimeFormat(german, options);
// formats the date, shows the current date
// for instance "1. April 2021 um 12:12:04"
Console.log(dfGermanOptions.format(new Date()));
The complete options are described by following table:
Name | Type | Default | Description |
---|---|---|---|
calendar | Calendar | null | The calendar to use for formatting. |
dateStyle | DateTimeStyle | null | The date style to use when formatting. |
day | NumberItemStyle | NumberItemStyle.NUMERIC | The representation of the day. |
dayPeriod | StringItemStyle | null | The way day periods should be expressed. |
era | StringItemStyle | null | The representation of the era. |
formatMatcher | FormatMatcher | null | The format matching algorithm to use. |
hour | NumberItemStyle | null | The representation of the hour. |
hour12 | boolean | false | Whether to use 12-hour time (as opposed to 24-hour time). This option overrides the hourCycle option in case both are present. |
hourCycle | HourCycle | null | The hour cycle to use. |
localeMatcher | LocaleMatcher | LocaleMatcher.BEST_FIT | The locale matching algorithm to use. |
minute | NumberItemStyle | null | The representation of the minute. |
month | MixedItemStyle | MixedItemStyle.NUMERIC | The representation of the month. |
numberingSystem | NumberingSystem | null | The numbering system to use for date time formatting. |
second | NumberItemStyle | null | The representation of the second. |
timeStyle | DateTimeStyle | null | The time style to use when formatting. |
timeZone | TimeZone | null | The time zone to use. |
timeZoneName | TimeZoneName | null | The representation of the time zone name. |
weekDay | StringItemStyle | null | The representation of the weekday. |
year | NumberItemStyle | NumberItemStyle.NUMERIC | The representation of the year. |
See INTL date time format documentation for the details of each option.
Using
The date time format provides a set of methods to enable the date time formatting.
The most important one is format, to format a Date as following:
// creates a date time format
// with a locale
DateTimeFormat dateTimeFormat = new DateTimeFormat(CLocale.GERMANY);
// formats the date, shows the current date
// for instance "1.4.2021", d.M.YYYY
Console.log(numberFormat.format(new Date()));
Resolving options
resolveOptions method provides a object with properties reflecting the locale and date time formatting options computed during initialization.
// creates a date time format
// with a locale
DateTimeFormat dateTimeFormat = new DateTimeFormat(CLocale.US);
// gets the resolved options
IsDefaultDateTimeFormatOptions resolvedOptions = dateTimeFormat.resolveOptions();
// gets date time styles resolved options
resolvedOptions.getDateStyle();
resolvedOptions.getTimeStyle();
Formatting to parts
formatToParts method is useful for custom formatting of date time strings. It returns a list of format part objects containing the locale-specific tokens from which it possible to build custom strings while preserving the locale-specific parts.
// creates a date time format
// with a locale
DateTimeFormat dateTimeFormat = new DateTimeFormat(CLocale.US);
// gets the format parts
List<FormatPart> parts = dateTimeFormat.formatToParts(new Date());
// scans the list , logging them
parts.forEach((element) -> Console.log(element.getType().name()+" : "+element.getValue()));
// result to console:
// MONTH : 4
// LITERAL : /
// DAY : 1
// LITERAL : /
// YEAR : 2021