From fc8dcc4151e3a1e6544200375c7cd629fbc78574 Mon Sep 17 00:00:00 2001 From: Kip Cole Date: Mon, 8 Jul 2024 09:10:50 +1000 Subject: [PATCH] Improve docs for specifying formats --- CHANGELOG.md | 10 ++++++++-- README.md | 22 ++++++++++++++-------- lib/cldr/backend/date_time.ex | 18 ++++++++++++------ lib/cldr/backend/format.ex | 21 +++++++++++++++++++++ lib/cldr/date.ex | 12 +++++++----- lib/cldr/date_time.ex | 6 ++++-- lib/cldr/format/date_time_format.ex | 2 +- lib/cldr/time.ex | 6 ++++-- 8 files changed, 71 insertions(+), 26 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 324cbd2..d520b75 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,7 +4,7 @@ ## Cldr_Dates_Times v2.19.0 -This is the changelog for Cldr_Dates_Times v2.19.0 released on _____, 2024. For older changelogs please consult the release tag on [GitHub](https://github.com/elixir-cldr/cldr_cldr_dates_times/tags) +This is the changelog for Cldr_Dates_Times v2.19.0 released on Jult 8th, 2024. For older changelogs please consult the release tag on [GitHub](https://github.com/elixir-cldr/cldr_cldr_dates_times/tags) ### Bug Fixes @@ -16,10 +16,16 @@ This is the changelog for Cldr_Dates_Times v2.19.0 released on _____, 2024. For * Adds support for partial dates in `Cldr.Date.to_string/2`. Partial dates are maps with one or more of the fields `:year`, `:month`, `:day` and `:calendar`. -* Adds support for deriving the "best match" format for a date based upon the users requested format or deriving from the available date fields. +* Adds support for partial time in `Cldr.Time.to_string/2`. Partial times are maps with one or more of the fields `:hour`, `:minute`, and `:second`. + +* Adds support for partial datetimes in `Cldr.DateTime.to_string/2`. Partial datetimes are maps with one or more of the fields `:year`, `:month`, `:day`, `:hour`, `:minute`, `:second` and `:calendar`. + +* Adds support for deriving the "best match" format for a date, time or datetime based upon the users requested format or deriving from the available date, time or datetime fields. * Adds support for formatting using format IDs (atoms that are keys to locale-independent formats) in `Cldr.Date.to_string/2` and `Cldr.Time.to_string/2`. They have been previously supported in `Cldr.DateTime.to_string/2` only. +* Add `MyApp.Cldr.DateTime.Format.common_date_time_format_names/0`. + * Improve the error message if `:hour` is outside the valid range. ## Cldr_Dates_Times v2.18.1 diff --git a/README.md b/README.md index 0973c27..3adbedd 100644 --- a/README.md +++ b/README.md @@ -52,7 +52,7 @@ A `backend` module is required that is used to host the functions that manage CL default_backend: MyApp.Cldr ``` -## Usage Introduction +## Introduction `ex_cldr_dates_times` is an addon library application for [ex_cldr](https://hex.pm/packages/ex_cldr) that provides localisation and formatting for dates, times and date_times. @@ -83,11 +83,11 @@ iex> h MyApp.Cldr.DateTime.to_string iex> h MyApp.Cldr.DateTime.Relative.to_string ``` -## Date, Time and DateTime Localization Formatting +## Date, Time and DateTime Localization Formats -Dates, Times and DateTimes can be formatted using: +Dates, Times and DateTimes can be formatted using standard formats, format strings or format IDs. -* The format types defined for each locale. These format types provide cross-locale standardisation and therefore should be preferred where possible. The format types, implemented for `MyApp.Cldr.Date.to_string/2`, `MyApp.Cldr.Time.to_string/2`,`MyApp.Cldr.DateTime.to_string/2` are `:short`, `:medium`, `:long` and `:full`. The default is `:medium`. For example, assuming a configured backend called `MyApp.Cldr`: +* Standard formats provide cross-locale standardisation and therefore should be preferred where possible. The format types, implemented for `MyApp.Cldr.Date.to_string/2`, `MyApp.Cldr.Time.to_string/2`,`MyApp.Cldr.DateTime.to_string/2` are `:short`, `:medium`, `:long` and `:full`. The default is `:medium`. For example, assuming a configured backend called `MyApp.Cldr`: ```elixir iex> MyApp.Cldr.DateTime.to_string ~U[2020-05-30 03:52:56Z], format: :short @@ -103,17 +103,17 @@ Dates, Times and DateTimes can be formatted using: {:ok, "30 mai 2020 à 03:52:56 UTC"} ``` -* A user specified format string. A format string uses one or more formatting symbols to define what date and time elements should be places in the format. A simple example to format the time into hours and minutes: +* Format strings use one or more formatting symbols to define what date and time elements should be places in the format. A simple example to format the time into hours and minutes: ```elixir iex> MyApp.Cldr.DateTime.to_string ~U[2020-05-30 03:52:56Z], format: "hh:mm" {:ok, "03:52"} ``` -* For `DateTime`s there is also a set of predefined format name. These format names are returned by `MyApp.Cldr.DateTime.Format.date_time_available_formats/0` (assuming your backend is `MyApp.Cldr`). The set of common format names across all locales configured in `ex_cldr` can be returned by `Cldr.DateTime.Format.common_date_time_format_names`. These format names can be used with the `:format` parameter to `Cldr.DateTime.to_string/2` module only. +* Format IDs are an atom that is a key into a map of formats defined by CLDR. These format IDs are returned by `MyApp.Cldr.DateTime.Format.date_time_available_formats/2` (assuming your backend is `MyApp.Cldr`). The set of common format names across all locales configured in `ex_cldr` can be returned by `MyApp.Cldr.DateTime.Format.common_date_time_format_names/0`. ```elixir - iex> MyApp.Cldr.DateTime.Format.date_time_available_formats + iex> MyApp.Cldr.DateTime.Format.date_time_available_formats() %{mmmm_w_count_one: "'week' W 'of' MMMM", gy_mmm: "MMM y G", md: "M/d", mmm_md: "MMMM d", e_hms: "E HH:mm:ss", ed: "d E", y_mmm: "MMM y", e_hm: "E HH:mm", mmm_ed: "E, MMM d", y_mmm_ed: "E, MMM d, y", @@ -128,7 +128,7 @@ Dates, Times and DateTimes can be formatted using: # These format types can be invoked for any locale - meaning # these format names are defined for all configured locales. - iex> Cldr.DateTime.Format.common_date_time_format_names(MyApp.Cldr) + iex> MyApp.Cldr.DateTime.Format.common_date_time_format_names() [:gy_mmm, :md, :mmm_md, :e_hms, :ed, :y_mmm, :e_hm, :mmm_ed, :y_mmm_ed, :gy_mm_md, :mmm, :y_md, :gy, :hms, :hm, :y_mmmm, :m, :gy_mmm_ed, :y_qqq, :e, :y_qqqq, :hmsv, :mmmm_w_count_other, :ehm, :y_m_ed, :h, :hmv, :yw_count_other, @@ -136,6 +136,12 @@ Dates, Times and DateTimes can be formatted using: iex> Cldr.DateTime.to_string ~U[2020-05-30 03:52:56Z], MyApp.Cldr, format: :gy_mmm_ed {:ok, "Sat, May 30, 2020 AD"} + + iex(2)> Cldr.Time.to_string ~U[2020-05-30 03:52:56Z], MyApp.Cldr, format: :hm + {:ok, "3:52 AM"} + + iex(3)> Cldr.Date.to_string ~U[2020-05-30 03:52:56Z], MyApp.Cldr, format: :yMd + {:ok, "5/30/2020"} ``` ## Format strings diff --git a/lib/cldr/backend/date_time.ex b/lib/cldr/backend/date_time.ex index c03e274..2f22384 100644 --- a/lib/cldr/backend/date_time.ex +++ b/lib/cldr/backend/date_time.ex @@ -24,7 +24,8 @@ defmodule Cldr.DateAndTime.Backend do * `:format` is one of `:short`, `:medium`, `:long`, `:full` or a format string or any of the keys in the map returned by `Cldr.DateTime.date_time_formats/3`. - The default is `:medium`. + The default is `:medium`. See [here](README.md#date-time-and-datetime-localization-formats) + for more information about specifiying formats. * `:date_format` is any one of `:short`, `:medium`, `:long`, `:full`. If defined, this option is used to format the date part of the date time. This option is @@ -110,7 +111,8 @@ defmodule Cldr.DateAndTime.Backend do * `:format` is one of `:short`, `:medium`, `:long`, `:full` or a format string or any of the keys in the map returned by `Cldr.DateTime.date_time_formats/3`. - The default is `:medium`. + The default is `:medium`. See [here](README.md#date-time-and-datetime-localization-formats) + for more information about specifiying formats. * `:date_format` is any one of `:short`, `:medium`, `:long`, `:full`. If defined, this option is used to format the date part of the date time. This option is @@ -192,7 +194,8 @@ defmodule Cldr.DateAndTime.Backend do dates having `:year`, `:month`, `:day` and `:calendar` fields). The default for partial dates is to derive a candidate format id from the date and find the best match from the formats returned by - `Cldr.Date.available_formats/3`. + `Cldr.Date.available_formats/3`. See [here](README.md#date-time-and-datetime-localization-formats) + for more information about specifiying formats. * `:locale:` any locale returned by `Cldr.known_locale_names/1`. The default is `Cldr.get_locale/0`. @@ -276,7 +279,8 @@ defmodule Cldr.DateAndTime.Backend do dates having `:year`, `:month`, `:day` and `:calendar` fields). The default for partial dates is to derive a candidate format id from the date and find the best match from the formats returned by - `Cldr.Date.available_formats/3`. + `Cldr.Date.available_formats/3`. See [here](README.md#date-time-and-datetime-localization-formats) + for more information about specifiying formats. * `:locale:` any locale returned by `Cldr.known_locale_names/1`. The default is `Cldr.get_locale/0`. @@ -361,7 +365,8 @@ defmodule Cldr.DateAndTime.Backend do times having `:hour`, `:minute` and `:second` fields). The default for partial times is to derive a candidate format from the time and find the best match from the formats returned by - `Cldr.Time.available_formats/2`. + `Cldr.Time.available_formats/2`. See [here](README.md#date-time-and-datetime-localization-formats) + for more information about specifiying formats. * `:locale` any locale returned by `Cldr.known_locale_names/1`. The default is `Cldr.get_locale/0`. @@ -438,7 +443,8 @@ defmodule Cldr.DateAndTime.Backend do times having `:hour`, `:minute` and `:second` fields). The default for partial times is to derive a candidate format from the time and find the best match from the formats returned by - `Cldr.Time.available_formats/2`. + `Cldr.Time.available_formats/2`. See [here](README.md#date-time-and-datetime-localization-formats) + for more information about specifiying formats. * `:locale` any locale returned by `Cldr.known_locale_names/1`. The default is `Cldr.get_locale/0`. diff --git a/lib/cldr/backend/format.ex b/lib/cldr/backend/format.ex index f12b9c2..96a5046 100644 --- a/lib/cldr/backend/format.ex +++ b/lib/cldr/backend/format.ex @@ -618,6 +618,27 @@ defmodule Cldr.DateTime.Format.Backend do end end + @doc """ + Returns a list of the date_time format IDs that are + available in all known locales. + + The format IDs returned by `common_date_time_format_names/0` + are guaranteed to be available in all known locales, + + ## Example: + + iex> #{inspect(__MODULE__)}.common_date_time_format_names() + [:Bh, :Bhm, :Bhms, :E, :EBhm, :EBhms, :EHm, :EHms, :Ed, :Ehm, :Ehms, :Gy, + :GyMMM, :GyMMMEd, :GyMMMd, :GyMd, :H, :Hm, :Hms, :Hmsv, :Hmv, :M, :MEd, :MMM, + :MMMEd, :MMMMW, :MMMMd, :MMMd, :Md, :d, :h, :hm, :hms, :hmsv, :hmv, :ms, :y, + :yM, :yMEd, :yMMM, :yMMMEd, :yMMMM, :yMMMd, :yMd, :yQQQ, :yQQQQ, :yw] + + """ + @spec common_date_time_format_names() :: [Format.format_id()] + def common_date_time_format_names do + Cldr.DateTime.Format.common_date_time_format_names(unquote(backend)) + end + @doc """ Returns the fallback format for a given locale and calendar type diff --git a/lib/cldr/date.ex b/lib/cldr/date.ex index 6d81636..171e11b 100644 --- a/lib/cldr/date.ex +++ b/lib/cldr/date.ex @@ -58,12 +58,13 @@ defmodule Cldr.Date do ### Options - * `:format` is one of `:short`, `:medium`, `:long`, `:full`, or a format id + * `:format` is one of `:short`, `:medium`, `:long`, `:full`, or a format ID or a format string. The default is `:medium` for full dates (that is, dates having `:year`, `:month`, `:day` and `:calendar` fields). The - default for partial dates is to derive a candidate format id from the date and + default for partial dates is to derive a candidate format ID from the date and find the best match from the formats returned by - `Cldr.Date.available_formats/3`. + `Cldr.Date.available_formats/3`. See [here](README.md#date-time-and-datetime-localization-formats) + for more information about specifiying formats. * `:locale:` any locale returned by `Cldr.known_locale_names/1`. The default is `Cldr.get_locale/0`. @@ -182,12 +183,13 @@ defmodule Cldr.Date do ### Options - * `:format` is one of `:short`, `:medium`, `:long`, `:full`, or a format id + * `:format` is one of `:short`, `:medium`, `:long`, `:full`, or a format ID or a format string. The default is `:medium` for full dates (that is, dates having `:year`, `:month`, `:day` and `:calendar` fields). The default for partial dates is to derive a candidate format from the date and find the best match from the formats returned by - `Cldr.Date.available_formats/3`. + `Cldr.Date.available_formats/3`. See [here](README.md#date-time-and-datetime-localization-formats) + for more information about specifiying formats. * `:locale` is any valid locale name returned by `Cldr.known_locale_names/0` or a `Cldr.LanguageTag` struct. The default is `Cldr.get_locale/0`. diff --git a/lib/cldr/date_time.ex b/lib/cldr/date_time.ex index 320e66b..08229f0 100644 --- a/lib/cldr/date_time.ex +++ b/lib/cldr/date_time.ex @@ -103,7 +103,8 @@ defmodule Cldr.DateTime do * `:format` is one of `:short`, `:medium`, `:long`, `:full` or a format string or any of the keys in the map returned by `Cldr.DateTime.Format.date_time_formats/3`. - The default is `:medium`. + The default is `:medium`. See [here](README.md#date-time-and-datetime-localization-formats) + for more information about specifiying formats. * `:date_format` is any one of `:short`, `:medium`, `:long`, `:full`. If defined, this option is used to format the date part of the date time. This option is @@ -250,7 +251,8 @@ defmodule Cldr.DateTime do * `:format` is one of `:short`, `:medium`, `:long`, `:full` or a format string or any of the keys returned by `Cldr.DateTime.Format.date_time_formats/3`. - The default is `:medium`. + The default is `:medium`. See [here](README.md#date-time-and-datetime-localization-formats) + for more information about specifiying formats. * `:style` is either `:at` or `:default`. When set to `:at` the datetime may be formatted with a localised string representing ` at