Update :prefer docs

elixir-cldr · Jul 26, 2024 · 1a05fd1 · 1a05fd1
1 parent 58ca64f
commit 1a05fd1
Show file tree

Hide file tree

Showing 19 changed files with 510 additions and 129 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,17 +2,17 @@
 
 **Note that `ex_cldr_dates_times` version 2.18.0 and later are supported on Elixir 1.12 and later only.**
 
-## Cldr_Dates_Times v2.19.3
+## Cldr_Dates_Times v2.20.0
 
-This is the changelog for Cldr_Dates_Times v2.19.3 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.20.0 released on July 26th, 2024.  For older changelogs please consult the release tag on [GitHub](https://github.com/elixir-cldr/cldr_cldr_dates_times/tags)
 
 ### Bug Fixes
 
 * Fix `Cldr.Time.available_formats/3` when the locale parameter is a binary.
 
 ### Enhancements
 
-* Modify the `:prefer` option of `to_string/2` to take a list of preferences. Time formats may sometimes have a `:unicode` or `:ascii` preference. Date formats may have a `:default` or `:variant` preference. The `:prefer` option can no be specified with one or both of these options.
+* Modify the `:prefer` option of `to_string/2` to take a list of preferences. Time formats may sometimes have a `:unicode` or `:ascii` preference. Date and datetime formats may have a `:default` or `:variant` preference. The `:prefer` option can now be specified with one or both of these options.
 
 ## Cldr_Dates_Times v2.19.2
 

diff --git a/lib/cldr/backend/formatter.ex b/lib/cldr/backend/formatter.ex
@@ -34,7 +34,7 @@ defmodule Cldr.DateTime.Formatter.Backend do
         * `format` is a valid format string, for example `yy/MM/dd hh:MM`
 
         * `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`
+          or a `t:Cldr.LanguageTag.t/0` struct. The default is `Cldr.get_locale/0`
 
         * `options` is a keyword list of options.
 

diff --git a/lib/cldr/backend/interval.ex b/lib/cldr/backend/interval.ex
@@ -73,7 +73,7 @@ defmodule Cldr.Interval.Backend do
             for each of the date and time part is used
 
         * `locale` is any valid locale name returned by `Cldr.known_locale_names/0`
-          or a `Cldr.LanguageTag` struct.  The default is `#{backend}.get_locale/0`
+          or a `t:Cldr.LanguageTag.t/0` struct.  The default is `#{backend}.get_locale/0`
 
         * `number_system:` a number system into which the formatted date digits should
           be transliterated
@@ -184,7 +184,7 @@ defmodule Cldr.Interval.Backend do
             for each of the date and time part is used
 
         * `locale` is any valid locale name returned by `Cldr.known_locale_names/0`
-          or a `Cldr.LanguageTag` struct.  The default is `#{backend}.get_locale/0`
+          or a `t:Cldr.LanguageTag.t/0` struct.  The default is `#{backend}.get_locale/0`
 
         * `number_system:` a number system into which the formatted date digits should
           be transliterated.
@@ -315,7 +315,7 @@ defmodule Cldr.Interval.Backend do
             for each of the date and time part is used.
 
         * `locale` is any valid locale name returned by `Cldr.known_locale_names/0`
-          or a `Cldr.LanguageTag` struct.  The default is `#{backend}.get_locale/0`.
+          or a `t:Cldr.LanguageTag.t/0` struct.  The default is `#{backend}.get_locale/0`.
 
         * `number_system:` a number system into which the formatted date digits should
           be transliterated.
@@ -427,7 +427,7 @@ defmodule Cldr.Interval.Backend do
             for each of the date and time part is used.
 
         * `locale` is any valid locale name returned by `Cldr.known_locale_names/0`
-          or a `Cldr.LanguageTag` struct.  The default is `#{backend}.get_locale/0`.
+          or a `t:Cldr.LanguageTag.t/0` struct.  The default is `#{backend}.get_locale/0`.
 
         * `number_system:` a number system into which the formatted date digits should
           be transliterated.

diff --git a/lib/cldr/backend/interval/date.ex b/lib/cldr/backend/interval/date.ex
@@ -62,7 +62,7 @@ defmodule Cldr.Date.Interval.Backend do
           and `:year_and_month`. The default is `:date`.
 
         * `:locale` is any valid locale name returned by `Cldr.known_locale_names/0`
-          or a `Cldr.LanguageTag` struct.  The default is `#{backend}.get_locale/0`
+          or a `t:Cldr.LanguageTag.t/0` struct.  The default is `#{backend}.get_locale/0`
 
         * `:number_system` a number system into which the formatted date digits should
           be transliterated
@@ -176,7 +176,7 @@ defmodule Cldr.Date.Interval.Backend do
           and `:year_and_month`. The default is `:date`.
 
         * `locale` is any valid locale name returned by `Cldr.known_locale_names/0`
-          or a `Cldr.LanguageTag` struct.  The default is `#{backend}.get_locale/0`
+          or a `t:Cldr.LanguageTag.t/0` struct.  The default is `#{backend}.get_locale/0`
 
         * `number_system:` a number system into which the formatted date digits should
           be transliterated
@@ -281,7 +281,7 @@ defmodule Cldr.Date.Interval.Backend do
           and `:year_and_month`. The default is `:date`.
 
         * `locale` is any valid locale name returned by `Cldr.known_locale_names/0`
-          or a `Cldr.LanguageTag` struct.  The default is `#{backend}.get_locale/0`
+          or a `t:Cldr.LanguageTag.t/0` struct.  The default is `#{backend}.get_locale/0`
 
         * `number_system:` a number system into which the formatted date digits should
           be transliterated
@@ -392,7 +392,7 @@ defmodule Cldr.Date.Interval.Backend do
           and `:year_and_month`. The default is `:date`.
 
         * `locale` is any valid locale name returned by `Cldr.known_locale_names/0`
-          or a `Cldr.LanguageTag` struct.  The default is `#{backend}.get_locale/0`.
+          or a `t:Cldr.LanguageTag.t/0` struct.  The default is `#{backend}.get_locale/0`.
 
         * `number_system:` a number system into which the formatted date digits should
           be transliterated.

diff --git a/lib/cldr/backend/interval/date_time.ex b/lib/cldr/backend/interval/date_time.ex
@@ -56,7 +56,7 @@ defmodule Cldr.DateTime.Interval.Backend do
             format. The default is `:medium`.
 
           * `:locale` is any valid locale name returned by `Cldr.known_locale_names/0`
-            or a `Cldr.LanguageTag` struct.  The default is `#{backend}.get_locale/0`
+            or a `t:Cldr.LanguageTag.t/0` struct.  The default is `#{backend}.get_locale/0`
 
           * `:number_system` a number system into which the formatted datetime
              digits should be transliterated
@@ -129,7 +129,7 @@ defmodule Cldr.DateTime.Interval.Backend do
           format. The default is `:medium`.
 
         * `locale` is any valid locale name returned by `Cldr.known_locale_names/0`
-          or a `Cldr.LanguageTag` struct.  The default is `#{backend}.get_locale/0`
+          or a `t:Cldr.LanguageTag.t/0` struct.  The default is `#{backend}.get_locale/0`
 
         * `number_system:` a number system into which the formatted date digits should
           be transliterated
@@ -219,7 +219,7 @@ defmodule Cldr.DateTime.Interval.Backend do
             format. The default is `:medium`.
 
           * `:locale` is any valid locale name returned by `Cldr.known_locale_names/0`
-            or a `Cldr.LanguageTag` struct.  The default is `#{backend}.get_locale/0`
+            or a `t:Cldr.LanguageTag.t/0` struct.  The default is `#{backend}.get_locale/0`
 
           * `:number_system` a number system into which the formatted datetime
              digits should be transliterated
@@ -293,7 +293,7 @@ defmodule Cldr.DateTime.Interval.Backend do
           format. The default is `:medium`.
 
         * `locale` is any valid locale name returned by `Cldr.known_locale_names/0`
-          or a `Cldr.LanguageTag` struct.  The default is `#{backend}.get_locale/0`.
+          or a `t:Cldr.LanguageTag.t/0` struct.  The default is `#{backend}.get_locale/0`.
 
         * `number_system:` a number system into which the formatted date digits should
           be transliterated.

diff --git a/lib/cldr/backend/interval/time.ex b/lib/cldr/backend/interval/time.ex
@@ -53,7 +53,7 @@ defmodule Cldr.Time.Interval.Backend do
           and `:flex`. The default is `:time`.
 
         * `locale` is any valid locale name returned by `Cldr.known_locale_names/0`
-          or a `Cldr.LanguageTag` struct.  The default is `#{backend}.get_locale/0`.
+          or a `t:Cldr.LanguageTag.t/0` struct.  The default is `#{backend}.get_locale/0`.
 
         * `number_system:` a number system into which the formatted date digits should
           be transliterated.
@@ -163,7 +163,7 @@ defmodule Cldr.Time.Interval.Backend do
           and `:flex`. The default is `:time`.
 
         * `locale` is any valid locale name returned by `Cldr.known_locale_names/0`
-          or a `Cldr.LanguageTag` struct.  The default is `#{backend}.get_locale/0`.
+          or a `t:Cldr.LanguageTag.t/0` struct.  The default is `#{backend}.get_locale/0`.
 
         * `number_system:` a number system into which the formatted date digits should
           be transliterated.

diff --git a/lib/cldr/date.ex b/lib/cldr/date.ex
@@ -74,17 +74,35 @@ defmodule Cldr.Date do
   * `:number_system` a number system into which the formatted date digits
     should be transliterated.
 
-  * `:prefer` is either `:unicode` (the default) or `:ascii`. A small number of
-    formats have two variants - one using Unicode spaces (typically non-breaking space) and
-    another using only ASCII whitespace. The `:ascii` format is primarily to support legacy
-    use cases and is not recommended. See `Cldr.Date.available_formats/3`
-    to see which formats have these variants. Currently no date-specific
-    formats have such variants but they may in the future.
+  * `:prefer` expresses the preference for one of the possible alternative
+    sub-formats. See the variant preference notes below.
 
   * `:era` which, if set to `:variant`, will use a variant for the era if one
     is available in the requested locale. In the `:en` locale, for example, `era: :variant`
     will return `CE` instead of `AD` and `BCE` instead of `BC`.
 
+  ### Variant Preference
+
+  * A small number of formats have one of two different alternatives, each with their own
+    preference specifier. The preferences are specified with the `:prefer` option to
+    `Cldr.Date.to_string/3`. The preference is expressed as an atom, or a list of one or two
+    atoms with one atom being either `:unicode` or `:ascii` and one atom being either
+    `:default` or `:variant`.
+
+    * Some formats (at the time of publishng only time formats but that
+      may change in the future) have `:unicode` and `:ascii` versions of the format. The
+      difference is the use of ascii space (0x20) as a separateor in the `:ascii` verison
+      whereas the `:unicode` version may use non-breaking or other space characters. The
+      default is `:unicode` and this is the strongly preferred option. The `:ascii` format
+      is primarily to support legacy use cases and is not recommended. See
+      `Cldr.Date.available_formats/3` to see which formats have these variants.
+
+    * Some formats (at the time of publishing, only date and datetime formats) have
+      `:default` and `:variant` versions of the format. These variant formats are only
+      included in a small number of locales. For example, the `:"en-CA"` locale, which has
+      a `:default` format respecting typical Canadian formatting and a `:variant` that is
+      more closely aligned to US formatting. The default is `:default`.
+
   ### Returns
 
   * `{:ok, formatted_string}` or
@@ -201,22 +219,40 @@ defmodule Cldr.Date do
     for more information about specifying 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`.
+    or a `t:Cldr.LanguageTag.t/0` struct.  The default is `Cldr.get_locale/0`.
 
   * `:number_system` a number system into which the formatted date digits should
     be transliterated.
 
-  * `:prefer` is either `:unicode` (the default) or `:ascii`. A small number of
-    formats have two variants - one using Unicode spaces (typically non-breaking space) and
-    another using only ASCII whitespace. The `:ascii` format is primarily to support legacy
-    use cases and is not recommended. See `Cldr.Date.available_formats/3`
-    to see which formats have these variants. Currently no date-specific
-    formats have such variants but they may in the future.
+  * `:prefer` expresses the preference for one of the possible alternative
+    sub-formats. See the variant preference notes below.
 
   * `:era` which, if set to `:variant`, will use a variant for the era if one
     is available in the requested locale. In the `:en` locale, for example, `era: :variant`
     will return `CE` instead of `AD` and `BCE` instead of `BC`.
 
+  ### Variant Preference
+
+  * A small number of formats have one of two different alternatives, each with their own
+    preference specifier. The preferences are specified with the `:prefer` option to
+    `Cldr.Date.to_string/3`. The preference is expressed as an atom, or a list of one or two
+    atoms with one atom being either `:unicode` or `:ascii` and one atom being either
+    `:default` or `:variant`.
+
+    * Some formats (at the time of publishng only time formats but that
+      may change in the future) have `:unicode` and `:ascii` versions of the format. The
+      difference is the use of ascii space (0x20) as a separateor in the `:ascii` verison
+      whereas the `:unicode` version may use non-breaking or other space characters. The
+      default is `:unicode` and this is the strongly preferred option. The `:ascii` format
+      is primarily to support legacy use cases and is not recommended. See
+      `Cldr.Date.available_formats/3` to see which formats have these variants.
+
+    * Some formats (at the time of publishing, only date and datetime formats) have
+      `:default` and `:variant` versions of the format. These variant formats are only
+      included in a small number of locales. For example, the `:"en-CA"` locale, which has
+      a `:default` format respecting typical Canadian formatting and a `:variant` that is
+      more closely aligned to US formatting. The default is `:default`.
+
   ### Returns
 
   * `formatted_date` or

diff --git a/lib/cldr/date_time.ex b/lib/cldr/date_time.ex
@@ -148,6 +148,28 @@ defmodule Cldr.DateTime do
     one is available in the locale.  For example, in the `:en` locale `period: :variant` will
     return "pm" instead of "PM".
 
+  ### Variant Preference
+
+  * A small number of formats have one of two different alternatives, each with their own
+    preference specifier. The preferences are specified with the `:prefer` option to
+    `Cldr.Date.to_string/3`. The preference is expressed as an atom, or a list of one or two
+    atoms with one atom being either `:unicode` or `:ascii` and one atom being either
+    `:default` or `:variant`.
+
+    * Some formats (at the time of publishng only time formats but that
+      may change in the future) have `:unicode` and `:ascii` versions of the format. The
+      difference is the use of ascii space (0x20) as a separateor in the `:ascii` verison
+      whereas the `:unicode` version may use non-breaking or other space characters. The
+      default is `:unicode` and this is the strongly preferred option. The `:ascii` format
+      is primarily to support legacy use cases and is not recommended. See
+      `Cldr.Time.available_formats/3` to see which formats have these variants.
+
+    * Some formats (at the time of publishing, only date and datetime formats) have
+      `:default` and `:variant` versions of the format. These variant formats are only
+      included in a small number of locales. For example, the `:"en-CA"` locale, which has
+      a `:default` format respecting typical Canadian formatting and a `:variant` that is
+      more closely aligned to US formatting. The default is `:default`.
+
   ### Notes
 
   * If the provided `datetime` contains only date fields, the call is delegated to
@@ -290,6 +312,28 @@ defmodule Cldr.DateTime do
     one is available in the locale.  For example, in the `:en` locale `period: :variant` will
     return "pm" instead of "PM".
 
+  ### Variant Preference
+
+  * A small number of formats have one of two different alternatives, each with their own
+    preference specifier. The preferences are specified with the `:prefer` option to
+    `Cldr.Date.to_string/3`. The preference is expressed as an atom, or a list of one or two
+    atoms with one atom being either `:unicode` or `:ascii` and one atom being either
+    `:default` or `:variant`.
+
+    * Some formats (at the time of publishng only time formats but that
+      may change in the future) have `:unicode` and `:ascii` versions of the format. The
+      difference is the use of ascii space (0x20) as a separateor in the `:ascii` verison
+      whereas the `:unicode` version may use non-breaking or other space characters. The
+      default is `:unicode` and this is the strongly preferred option. The `:ascii` format
+      is primarily to support legacy use cases and is not recommended. See
+      `Cldr.Time.available_formats/3` to see which formats have these variants.
+
+    * Some formats (at the time of publishing, only date and datetime formats) have
+      `:default` and `:variant` versions of the format. These variant formats are only
+      included in a small number of locales. For example, the `:"en-CA"` locale, which has
+      a `:default` format respecting typical Canadian formatting and a `:variant` that is
+      more closely aligned to US formatting. The default is `:default`.
+
   ### Notes
 
   * If the provided `datetime` contains only date fields, the call is delegated to

diff --git a/lib/cldr/format/date_time_format.ex b/lib/cldr/format/date_time_format.ex
@@ -77,7 +77,7 @@ defmodule Cldr.DateTime.Format do
   ## Arguments
 
   * `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`.
+    or a `t:Cldr.LanguageTag.t/0` struct. The default is `Cldr.get_locale/0`.
 
   * `backend` is any module that includes `use Cldr` and therefore
     is a `Cldr` backend module. The default is `Cldr.default_backend/0`.