Skip to main content
Version: 5.1

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:

NameTypeDefaultDescription
calendarCalendarnullThe calendar to use for formatting.
dateStyleDateTimeStylenullThe date style to use when formatting.
dayNumberItemStyleNumberItemStyle.NUMERICThe representation of the day.
dayPeriodStringItemStylenullThe way day periods should be expressed.
eraStringItemStylenullThe representation of the era.
formatMatcherFormatMatchernullThe format matching algorithm to use.
hourNumberItemStylenullThe representation of the hour.
hour12booleanfalseWhether to use 12-hour time (as opposed to 24-hour time).
This option overrides the hourCycle option in case both are present.
hourCycleHourCyclenullThe hour cycle to use.
localeMatcherLocaleMatcherLocaleMatcher.BEST_FITThe locale matching algorithm to use.
minuteNumberItemStylenullThe representation of the minute.
monthMixedItemStyleMixedItemStyle.NUMERICThe representation of the month.
numberingSystemNumberingSystemnullThe numbering system to use for date time formatting.
secondNumberItemStylenullThe representation of the second.
timeStyleDateTimeStylenullThe time style to use when formatting.
timeZoneTimeZonenullThe time zone to use.
timeZoneNameTimeZoneNamenullThe representation of the time zone name.
weekDayStringItemStylenullThe representation of the weekday.
yearNumberItemStyleNumberItemStyle.NUMERICThe 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