Improve docs for specifying formats

Author: kipcole9

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

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,14 +128,20 @@ 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,
     :mm_md, :y_m, :m_ed, :ms, :d, :y_mm_md, :y, :ehms]
 
     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

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`.

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

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`.

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 `<date> at <time>` if such

lib/cldr/format/date_time_format.ex

@@ -498,7 +498,7 @@ defmodule Cldr.DateTime.Format do
        :yM, :yMEd, :yMMM, :yMMMEd, :yMMMM, :yMMMd, :yMd, :yQQQ, :yQQQQ, :yw]
 
   """
-  @spec common_date_time_format_names(backend :: Cldr.backend()) :: [atom]
+  @spec common_date_time_format_names(backend :: Cldr.backend()) :: [format_id()]
   def common_date_time_format_names(backend \\ Cldr.Date.default_backend()) do
     datetime_module = Module.concat(backend, DateTime.Format)
 

lib/cldr/time.ex

@@ -78,7 +78,8 @@ defmodule Cldr.Time 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/3`.
+    `Cldr.Time.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`.
@@ -194,7 +195,8 @@ defmodule Cldr.Time 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/3`.
+    `Cldr.Time.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`.