Intl::Format::DateTime

A module to format time in a localized manner

IntlFormatDateTime

Hoy es siempre todavía, toda la vida es ahora. Y ahora, ahora es el momento de cumplir las promesas que nos hicimos. Porque ayer no lo hicimos, porque mañana es tarde. Ahora.Proverbios y cantares (Antonio Machado)

A module for formatting dates and times in a variety of languages and styles. To use, simple include the module:

use Intl::Format::DateTime

my $dt = DateTime.new: now;

format-date $dt;      # Format the date only
format-time $dt;      # Format the time only
format-datetime $dt;  # Format the date and time together

The command options are

  • :lengthThe main option, sets the length. Acceptable values are either full, long, medium (default), short. For the most verbose, choose wide. Defaults to medium which should be optimal in most cases.

  • :skeleton (alias :like)Accepts a string representing various formatting options documented in TR 35.4.8. The optimal pattern is chosen based on the given skeleton, deferring to the skeleton for minor differences (e.g. number of digits). If used, length option is ignored.

  • :languageSets the language to be used in formatting. Acceptable values are a LanguageTag or a Str representation thereof. Defaults to whatever User::Language provides, which itself defaults to en (English).

  • :relative-toNYI. This option will create a relative time offset based on the the interval. Generally :relative-to(now) is what you will want to use, but you can use anything that can coerce to a DateTime.

If you will be constantly reusing a formatter, you can also obtain a Callable form which will reduce some of the overhead and be more performant:

my &formatter =    local-datetime-formatter :$language, :$length, :$skeleton;
              # or local-date-formatter
              # or local-time-formatter

formatter DateTime.now

Current performance is about an order of magnitude slower than DateTime.Str and is about as fast as vanilla Raku can get. The performance gap can be narrowed if alternate nqp versions of formatters are written, but that is not a priority at the moment.

To do

  • Finish skeleton patterns support (allowing selection of more specific formats).

  • Respect capitalization rules per CLDR casing data.

  • Handle non-Gregorian calendars (once a DateTime::Calendars module or similar is available)

  • Handle relative time formats (though this may ultimately go into a separate module).

Dependencies

  • Intl::LanguageTagUsed for introspection of language tags.

  • Intl::UserLanguageDetermines the default language for formatting).

  • Intl::CLDRContains formatting information.

  • DateTime::TimezonesEnsures that DateTime objects are timezone aware.

These modules are designed to work together, and as of 2023, are maintained by the same person so should not have issues if fully updated.

Version history

  • v0.3.0

    • All code now runs with RakuAST for improved performance

    • Added local-datetime-formatter calls for enhanced performance in some situations

    • Proper week-of-year/weekyear support

    • Non-Latin digit support

    • Restructured file hierarchy for better long term maintenance

  • v0.2.0

    • Skeleton formats supported for format-datetime (NYI: missing fields and C/j/J formatters NYI)

  • v0.1

    • Initial release

Copyright and License

© 2021–2023 Matthew Stephen Stuckwisch. All files licensed under the Artistic License 2.0 except for resources/metaZones.xml which is owned by Unicode, Inc. and licensed under the Unicode License Agreement (found at resources/unicode-license.txt)

Intl::Format::DateTime v0.3.0

A module to format time in a localized manner

Authors

  • Matthew Stephen Stuckwisch

License

Artistic-2.0

Dependencies

DateTime::Timezones:auth<zef:guifa>ver<0.3.5+>Intl::CLDR:auth<zef:guifa>ver<0.7.4+>Intl::LanguageTag:auth<zef:guifa>:ver<0.12.3+>Intl::UserLanguage:auth<zef:guifa>ver<0.5.2+>

Test Dependencies

Provides

  • Intl::Format::DateTime
  • Intl::Format::DateTime::Constants
  • Intl::Format::DateTime::ExemplarCities
  • Intl::Format::DateTime::FieldMeta
  • Intl::Format::DateTime::Formatters::A-uc
  • Intl::Format::DateTime::Formatters::B-uc
  • Intl::Format::DateTime::Formatters::D-uc
  • Intl::Format::DateTime::Formatters::E-uc
  • Intl::Format::DateTime::Formatters::F-uc
  • Intl::Format::DateTime::Formatters::G-uc
  • Intl::Format::DateTime::Formatters::H-uc
  • Intl::Format::DateTime::Formatters::K-uc
  • Intl::Format::DateTime::Formatters::L-uc
  • Intl::Format::DateTime::Formatters::M-uc
  • Intl::Format::DateTime::Formatters::O-uc
  • Intl::Format::DateTime::Formatters::Q-uc
  • Intl::Format::DateTime::Formatters::S-uc
  • Intl::Format::DateTime::Formatters::U-uc
  • Intl::Format::DateTime::Formatters::V-uc
  • Intl::Format::DateTime::Formatters::W-uc
  • Intl::Format::DateTime::Formatters::X-uc
  • Intl::Format::DateTime::Formatters::Y-uc
  • Intl::Format::DateTime::Formatters::Z-uc
  • Intl::Format::DateTime::Formatters::a-lc
  • Intl::Format::DateTime::Formatters::b-lc
  • Intl::Format::DateTime::Formatters::c-lc
  • Intl::Format::DateTime::Formatters::d-lc
  • Intl::Format::DateTime::Formatters::e-lc
  • Intl::Format::DateTime::Formatters::g-lc
  • Intl::Format::DateTime::Formatters::h-lc
  • Intl::Format::DateTime::Formatters::k-lc
  • Intl::Format::DateTime::Formatters::l-lc
  • Intl::Format::DateTime::Formatters::m-lc
  • Intl::Format::DateTime::Formatters::q-lc
  • Intl::Format::DateTime::Formatters::r-lc
  • Intl::Format::DateTime::Formatters::s-lc
  • Intl::Format::DateTime::Formatters::u-lc
  • Intl::Format::DateTime::Formatters::v-lc
  • Intl::Format::DateTime::Formatters::w-lc
  • Intl::Format::DateTime::Formatters::x-lc
  • Intl::Format::DateTime::Formatters::y-lc
  • Intl::Format::DateTime::Formatters::z-lc
  • Intl::Format::DateTime::MetazoneNames
  • Intl::Format::DateTime::Metazones
  • Intl::Format::DateTime::Parsing::Actions
  • Intl::Format::DateTime::Parsing::Classes
  • Intl::Format::DateTime::Parsing::Grammar
  • Intl::Format::DateTime::Parsing::SkeletonActions
  • Intl::Format::DateTime::Parsing::Skeletons
  • Intl::Format::DateTime::Shortnames
  • Intl::Format::DateTime::Util

Documentation

The Camelia image is copyright 2009 by Larry Wall. "Raku" is trademark of the Yet Another Society. All rights reserved.