From 1a05fd1bb1a5fa2d6e232de814c041e15dcf7b97 Mon Sep 17 00:00:00 2001 From: Kip Cole Date: Fri, 26 Jul 2024 11:27:15 +1000 Subject: [PATCH] Update :prefer docs --- CHANGELOG.md | 6 +- lib/cldr/backend/formatter.ex | 2 +- lib/cldr/backend/interval.ex | 8 +- lib/cldr/backend/interval/date.ex | 8 +- lib/cldr/backend/interval/date_time.ex | 8 +- lib/cldr/backend/interval/time.ex | 4 +- lib/cldr/date.ex | 62 +++++++-- lib/cldr/date_time.ex | 44 +++++++ lib/cldr/format/date_time_format.ex | 2 +- lib/cldr/interval/date.ex | 130 +++++++++++++++--- lib/cldr/interval/date_time.ex | 176 +++++++++++++++++++------ lib/cldr/interval/time.ex | 86 +++++++++--- lib/cldr/time.ex | 62 +++++++-- mix.exs | 5 +- mix.lock | 2 +- mix/my_app_backend.ex | 2 +- test/cldr_dates_times_test.exs | 8 -- test/interval_test.exs | 2 +- test/variant_test.exs | 22 ++++ 19 files changed, 510 insertions(+), 129 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index a538cb2..0b80d78 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,9 +2,9 @@ **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 @@ -12,7 +12,7 @@ This is the changelog for Cldr_Dates_Times v2.19.3 released on _____, 2024. For ### 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 index 052d5e2..cea2ab7 100644 --- 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 index 8107905..69fec46 100644 --- 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 index 7151e9c..7d3a815 100644 --- 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 index 120a032..2e6c2a7 100644 --- 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 index db409b1..69356b9 100644 --- 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 index 7bcabf1..c41aaa3 100644 --- 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 index d71840d..532130e 100644 --- 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 index 6598640..6bc576c 100644 --- 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`. diff --git a/lib/cldr/interval/date.ex b/lib/cldr/interval/date.ex index ca9673a..ac06337 100644 --- a/lib/cldr/interval/date.ex +++ b/lib/cldr/interval/date.ex @@ -168,7 +168,32 @@ defmodule Cldr.Date.Interval do 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 + be transliterated. + + * `:prefer` expresses the preference for one of the possible alternative + sub-formats. See the variant preference notes below. + + ### 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 @@ -247,7 +272,7 @@ defmodule Cldr.Date.Interval do Returns a localised string representing the formatted interval formed by two dates. - ## Arguments + ### Arguments * `from` is any map that conforms to the `Calendar.date` type. @@ -266,7 +291,7 @@ defmodule Cldr.Date.Interval do interval is formatted as an open interval with the non-nil side formatted as a standalone date. - ## Options + ### Options * `:format` is one of `:short`, `:medium` or `:long` or a specific format type or a string representing of an interval @@ -276,13 +301,38 @@ defmodule Cldr.Date.Interval do alternatives are `:date`, `:month_and_day`, `:month` and `:year_and_month`. The default is `:date`. - * `locale` is any valid locale name returned by `Cldr.known_locale_names/0` + * `:locale` is any valid locale name returned by `Cldr.known_locale_names/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. - ## Returns + * `:prefer` expresses the preference for one of the possible alternative + sub-formats. See the variant preference notes below. + + ### 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, string}` or @@ -301,7 +351,7 @@ defmodule Cldr.Date.Interval do * In the case where `from` and `to` are equal, a single date is formatted instead of an interval. - ## Examples + ### Examples iex> Cldr.Date.Interval.to_string ~D[2020-01-01], ~D[2020-12-31], MyApp.Cldr {:ok, "Jan 1 – Dec 31, 2020"} @@ -463,7 +513,7 @@ defmodule Cldr.Date.Interval do Returns a `Date.Range` or `CalendarInterval` as a localised string or raises an exception. - ## Arguments + ### Arguments * `range` is either a `Date.Range.t` returned from `Date.range/2` or a `CalendarInterval.t` @@ -474,7 +524,7 @@ defmodule Cldr.Date.Interval do * `options` is a keyword list of options. The default is `[format: :medium, style: :date]`. - ## Options + ### Options * `:format` is one of `:short`, `:medium` or `:long` or a specific format type or a string representing of an interval @@ -490,13 +540,38 @@ defmodule Cldr.Date.Interval do * `number_system:` a number system into which the formatted date digits should be transliterated. + * `:prefer` expresses the preference for one of the possible alternative + sub-formats. See the variant preference notes below. + + ### 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 * `string` or * raises an exception - ## Notes + ### Notes * `CalendarInterval` support requires adding the dependency [calendar_interval](https://hex.pm/packages/calendar_interval) @@ -513,7 +588,7 @@ defmodule Cldr.Date.Interval do * In the case where `from` and `to` are equal, a single date is formatted instead of an interval. - ## Examples + ### Examples iex> Cldr.Date.Interval.to_string! Date.range(~D[2020-01-01], ~D[2020-12-31]), MyApp.Cldr "Jan 1 – Dec 31, 2020" @@ -565,7 +640,7 @@ defmodule Cldr.Date.Interval do interval formed by two dates or raises an exception. - ## Arguments + ### Arguments * `from` is any map that conforms to the `Calendar.date` type. @@ -580,7 +655,7 @@ defmodule Cldr.Date.Interval do * `options` is a keyword list of options. The default is `[format: :medium, style: :date]`. - ## Options + ### Options * `:format` is one of `:short`, `:medium` or `:long` or a specific format type or a string representing of an interval @@ -596,13 +671,38 @@ defmodule Cldr.Date.Interval do * `number_system:` a number system into which the formatted date digits should be transliterated. - ## Returns + * `:prefer` expresses the preference for one of the possible alternative + sub-formats. See the variant preference notes below. + + ### 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 * `string` or * raises an exception - ## Notes + ### Notes * For more information on interval format string see `Cldr.Interval`. @@ -615,7 +715,7 @@ defmodule Cldr.Date.Interval do * In the case where `from` and `to` are equal, a single date is formatted instead of an interval. - ## Examples + ### Examples iex> Cldr.Date.Interval.to_string! ~D[2020-01-01], ~D[2020-12-31], MyApp.Cldr "Jan 1 – Dec 31, 2020" diff --git a/lib/cldr/interval/date_time.ex b/lib/cldr/interval/date_time.ex index 8f97201..699bdf4 100644 --- a/lib/cldr/interval/date_time.ex +++ b/lib/cldr/interval/date_time.ex @@ -43,7 +43,7 @@ defmodule Cldr.DateTime.Interval do Returns a localised string representing the formatted `CalendarInterval`. - ## Arguments + ### Arguments * `range` is a `CalendarInterval.t` @@ -52,7 +52,7 @@ defmodule Cldr.DateTime.Interval do * `options` is a keyword list of options. The default is `[]`. - ## Options + ### Options * `:format` is one of `:short`, `:medium` or `:long` or a specific format type or a string representing of an interval @@ -70,19 +70,44 @@ defmodule Cldr.DateTime.Interval do `:short`, `:medium`, `:long`, `:full`. If `:time_format` is not specified then the time format is defined by the `:format` option. - * `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` + * `:locale` is any valid locale name returned by `Cldr.known_locale_names/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 + * `:number_system` a number system into which the formatted date digits should + be transliterated. + + * `:prefer` expresses the preference for one of the possible alternative + sub-formats. See the variant preference notes below. + + ### 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 + ### Returns * `{:ok, string}` or * `{:error, {exception, reason}}` - ## Notes + ### Notes * `CalendarInterval` support requires adding the dependency [calendar_interval](https://hex.pm/packages/calendar_interval) @@ -99,7 +124,7 @@ defmodule Cldr.DateTime.Interval do * In the case where `from` and `to` are equal, a single datetime is formatted instead of an interval - ## Examples + ### Examples iex> Cldr.DateTime.Interval.to_string ~I"2020-01-01 10:00/12:00", MyApp.Cldr {:ok, "Jan 1, 2020, 10:00:00 AM – 12:00:00 PM"} @@ -201,7 +226,7 @@ defmodule Cldr.DateTime.Interval do Returns a localised string representing the formatted interval formed by two dates. - ## Arguments + ### Arguments * `from` is any map that conforms to the `Calendar.datetime` type. @@ -219,7 +244,7 @@ defmodule Cldr.DateTime.Interval do result is an "open" interval and the non-nil parameter is formatted using `Cldr.DateTime.to_string/3`. - ## Options + ### Options * `:format` is one of `:short`, `:medium` or `:long` or a specific format type or a string representation of an interval @@ -237,19 +262,44 @@ defmodule Cldr.DateTime.Interval do `:short`, `:medium`, `:long`, `:full`. If `:time_format` is not specified thenthe time format is defined by the `:format` option. - * `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` + * `:locale` is any valid locale name returned by `Cldr.known_locale_names/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` expresses the preference for one of the possible alternative + sub-formats. See the variant preference notes below. + + ### 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`. - * `number_system:` a number system into which the formatted date digits should - be transliterated + * 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. - ## Returns + * 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, string}` or * `{:error, {exception, reason}}` - ## Notes + ### Notes * For more information on interval format string see the `Cldr.Interval`. @@ -262,7 +312,7 @@ defmodule Cldr.DateTime.Interval do * In the case where `from` and `to` are equal, a single date is formatted instead of an interval - ## Examples + ### Examples iex> Cldr.DateTime.Interval.to_string ~U[2020-01-01 00:00:00.0Z], ...> ~U[2020-12-31 10:00:00.0Z], MyApp.Cldr @@ -408,7 +458,7 @@ defmodule Cldr.DateTime.Interval do interval formed by two dates or raises an exception. - ## Arguments + ### Arguments * `from` is any map that conforms to the `Calendar.datetime` type. @@ -422,7 +472,7 @@ defmodule Cldr.DateTime.Interval do * `options` is a keyword list of options. The default is `[]`. - ## Options + ### Options * `:format` is one of `:short`, `:medium` or `:long` or a specific format type or a string representing of an interval @@ -440,19 +490,44 @@ defmodule Cldr.DateTime.Interval do `:short`, `:medium`, `:long`, `:full`. If `:time_format` is not specified then the time format is defined by the `:format` option. - * `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`. + * `:locale` is any valid locale name returned by `Cldr.known_locale_names/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 + * `:number_system` a number system into which the formatted date digits should be transliterated. - ## Returns + * `:prefer` expresses the preference for one of the possible alternative + sub-formats. See the variant preference notes below. + + ### 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 * `string` or * raises an exception - ## Notes + ### Notes * For more information on interval format string see the `Cldr.Interval`. @@ -463,9 +538,9 @@ defmodule Cldr.DateTime.Interval do is the underlying CLDR calendar type. * In the case where `from` and `to` are equal, a single - date is formatted instead of an interval + date is formatted instead of an interval. - ## Examples + ### Examples iex> use CalendarInterval iex> Cldr.DateTime.Interval.to_string! ~I"2020-01-01 00:00/10:00", MyApp.Cldr @@ -492,7 +567,7 @@ defmodule Cldr.DateTime.Interval do interval formed by two dates or raises an exception. - ## Arguments + ### Arguments * `from` is any map that conforms to the `Calendar.datetime` type. @@ -506,7 +581,7 @@ defmodule Cldr.DateTime.Interval do * `options` is a keyword list of options. The default is `[]`. - ## Options + ### Options * `:format` is one of `:short`, `:medium` or `:long` or a specific format type or a string representation of an interval @@ -524,19 +599,44 @@ defmodule Cldr.DateTime.Interval do `:short`, `:medium`, `:long`, `:full`. If `:time_format` is not specified then the time format is defined by the `:format` option. - * `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`. + * `:locale` is any valid locale name returned by `Cldr.known_locale_names/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 + * `:number_system` a number system into which the formatted date digits should be transliterated. - ## Returns + * `:prefer` expresses the preference for one of the possible alternative + sub-formats. See the variant preference notes below. + + ### 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 * `string` or * raises an exception - ## Notes + ### Notes * For more information on interval format string see the `Cldr.Interval`. @@ -549,7 +649,7 @@ defmodule Cldr.DateTime.Interval do * In the case where `from` and `to` are equal, a single date is formatted instead of an interval - ## Examples + ### Examples iex> Cldr.DateTime.Interval.to_string! ~U[2020-01-01 00:00:00.0Z], ...> ~U[2020-12-31 10:00:00.0Z], MyApp.Cldr @@ -568,13 +668,13 @@ defmodule Cldr.DateTime.Interval do time unit that is the greatest difference between two date/times. - ## Arguments + ### Arguments * `from` is any `t:DateTime.t/0` or `t:NaiveDateTine.t/0` * `to` is any `t:DateTime.t/0` or `t:NaiveDateTine.t/0` - ## Returns + ### Returns * `{:ok, format_code}` where `format_code` is one of @@ -586,7 +686,7 @@ defmodule Cldr.DateTime.Interval do * `{:error, :no_practical_difference}` - ## Example + ### Example iex> Cldr.DateTime.Interval.greatest_difference ~U[2022-04-22 02:00:00.0Z], ~U[2022-04-22 03:00:00.0Z] {:ok, :H} diff --git a/lib/cldr/interval/time.ex b/lib/cldr/interval/time.ex index 43a9ad6..2b4c19c 100644 --- a/lib/cldr/interval/time.ex +++ b/lib/cldr/interval/time.ex @@ -137,7 +137,7 @@ defmodule Cldr.Time.Interval do Returns a string representing the formatted interval formed by two times. - ## Arguments + ### Arguments * `from` is any map that conforms to the `Calendar.time` type. @@ -156,7 +156,7 @@ defmodule Cldr.Time.Interval do interval is formatted as an open interval with the non-nil side formatted as a standalone time. - ## Options + ### Options * `:format` is one of `:short`, `:medium` or `:long` or a specific format type or a string representing of an interval @@ -166,13 +166,38 @@ defmodule Cldr.Time.Interval do alternatives are `:time`, `:zone`, 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 `Cldr.get_locale/0`. + * `:locale` is any valid locale name returned by `Cldr.known_locale_names/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 + * `:number_system` a number system into which the formatted date digits should be transliterated. - ## Returns + * `:prefer` expresses the preference for one of the possible alternative + sub-formats. See the variant preference notes below. + + ### 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, string}` or @@ -191,7 +216,7 @@ defmodule Cldr.Time.Interval do * In the case where `from` and `to` are equal, a single time is formatted instead of an interval. - ## Examples + ### Examples iex> Cldr.Time.Interval.to_string ~T[10:00:00], ~T[10:03:00], MyApp.Cldr, format: :short {:ok, "10 – 10 AM"} @@ -308,7 +333,7 @@ defmodule Cldr.Time.Interval do Returns a string representing the formatted interval formed by two times. - ## Arguments + ### Arguments * `from` is any map that conforms to the `Calendar.time` type. @@ -322,7 +347,7 @@ defmodule Cldr.Time.Interval do * `options` is a keyword list of options. The default is `[format: :medium, style: :time]`. - ## Options + ### Options * `:format` is one of `:short`, `:medium` or `:long` or a specific format type or a string representing of an interval @@ -332,19 +357,44 @@ defmodule Cldr.Time.Interval do alternatives are `:time`, `:zone`, 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 `Cldr.get_locale/0` + * `:locale` is any valid locale name returned by `Cldr.known_locale_names/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 + * `:number_system` a number system into which the formatted date digits should be transliterated. - ## Returns + * `:prefer` expresses the preference for one of the possible alternative + sub-formats. See the variant preference notes below. + + ### 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 * `string` or * raises an exception - ## Notes + ### Notes * For more information on interval format string see `Cldr.Interval`. @@ -357,7 +407,7 @@ defmodule Cldr.Time.Interval do * In the case where `from` and `to` are equal, a single time is formatted instead of an interval. - ## Examples + ### Examples iex> Cldr.Time.Interval.to_string! ~T[10:00:00], ~T[10:03:00], MyApp.Cldr, format: :short "10 – 10 AM" @@ -422,13 +472,13 @@ defmodule Cldr.Time.Interval do Only differences in hours or minutes are considered. - ## Arguments + ### Arguments * `from` is any `t:Time.t/0`. * `to` is any `t:Time.t/0`. - ## Returns + ### Returns * `{:ok, format_code}` where `format_code` is one of: @@ -437,7 +487,7 @@ defmodule Cldr.Time.Interval do * `{:error, :no_practical_difference}` - ## Example + ### Example iex> Cldr.Time.Interval.greatest_difference ~T[10:11:00], ~T[10:12:00] {:ok, :m} diff --git a/lib/cldr/time.ex b/lib/cldr/time.ex index 5097e71..c6b2523 100644 --- a/lib/cldr/time.ex +++ b/lib/cldr/time.ex @@ -89,16 +89,35 @@ defmodule Cldr.Time 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.Time.available_formats/3` - to see which formats have these variants. + * `:prefer` expresses the preference for one of the possible alternative + sub-formats. See the variant preference notes below. * `period: :variant` will use a variant for the time period and flexible time period if 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`. + ### Examples iex> Cldr.Time.to_string(~T[07:35:13.215217], MyApp.Cldr) @@ -205,20 +224,39 @@ defmodule Cldr.Time 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 time 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.Time.available_formats/3` - to see which formats have these variants. + * `:prefer` expresses the preference for one of the possible alternative + sub-formats. See the variant preference notes below. * `period: :variant` will use a variant for the time period and flexible time period if one is available in the locale. For example, in the `:en` locale `period: :variant` will - return "pm" instead of "PM" + 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`. ### Returns diff --git a/mix.exs b/mix.exs index 0ffd511..564e514 100644 --- a/mix.exs +++ b/mix.exs @@ -1,7 +1,7 @@ defmodule Cldr.DatesTimes.Mixfile do use Mix.Project - @version "2.19.2" + @version "2.20.0" def project do [ @@ -70,8 +70,7 @@ defmodule Cldr.DatesTimes.Mixfile do defp deps do [ - {:ex_cldr, path: "../cldr", override: true}, - + {:ex_cldr, "~> 2.40"}, {:ex_cldr_calendars, "~> 1.25"}, {:calendar_interval, "~> 0.2", optional: true}, {:ex_doc, "~> 0.25", optional: true, only: [:dev, :release], runtime: false}, diff --git a/mix.lock b/mix.lock index b75acb6..336180a 100644 --- a/mix.lock +++ b/mix.lock @@ -10,7 +10,7 @@ "earmark": {:hex, :earmark, "1.4.14", "d04572cef64dd92726a97d92d714e38d6e130b024ea1b3f8a56e7de66ec04e50", [:mix], [{:earmark_parser, ">= 1.4.12", [hex: :earmark_parser, repo: "hexpm", optional: false]}], "hexpm", "df338b8b1852ee425180b276c56c6941cb12220e04fe8718fe4acbdd35fd699f"}, "earmark_parser": {:hex, :earmark_parser, "1.4.41", "ab34711c9dc6212dda44fcd20ecb87ac3f3fce6f0ca2f28d4a00e4154f8cd599", [:mix], [], "hexpm", "a81a04c7e34b6617c2792e291b5a2e57ab316365c2644ddc553bb9ed863ebefa"}, "erlex": {:hex, :erlex, "0.2.7", "810e8725f96ab74d17aac676e748627a07bc87eb950d2b83acd29dc047a30595", [:mix], [], "hexpm", "3ed95f79d1a844c3f6bf0cea61e0d5612a42ce56da9c03f01df538685365efb0"}, - "ex_cldr": {:hex, :ex_cldr, "2.39.2", "4a3a77797da8f900369822ea9353adfa035a5bbbbfff09b2d3d1b6fa461768e3", [:mix], [{:cldr_utils, "~> 2.25", [hex: :cldr_utils, repo: "hexpm", optional: false]}, {:decimal, "~> 1.6 or ~> 2.0", [hex: :decimal, repo: "hexpm", optional: false]}, {:gettext, "~> 0.19", [hex: :gettext, repo: "hexpm", optional: true]}, {:jason, "~> 1.0", [hex: :jason, repo: "hexpm", optional: true]}, {:nimble_parsec, "~> 0.5 or ~> 1.0", [hex: :nimble_parsec, repo: "hexpm", optional: true]}], "hexpm", "02fd8913ef28d1b2a4190fd8016c2dec1f2291c9ce56c17d7649848c0261a6eb"}, + "ex_cldr": {:hex, :ex_cldr, "2.40.0", "624717778dbf0a8cd307f1576eabbd44470c16190172abf293fed24150440a5a", [:mix], [{:cldr_utils, "~> 2.28", [hex: :cldr_utils, repo: "hexpm", optional: false]}, {:decimal, "~> 1.6 or ~> 2.0", [hex: :decimal, repo: "hexpm", optional: false]}, {:gettext, "~> 0.19", [hex: :gettext, repo: "hexpm", optional: true]}, {:jason, "~> 1.0", [hex: :jason, repo: "hexpm", optional: true]}, {:nimble_parsec, "~> 0.5 or ~> 1.0", [hex: :nimble_parsec, repo: "hexpm", optional: true]}], "hexpm", "113394b6dd23aaf7912da583aab103d9cf082b9821bc4a6e287543a895af7cb4"}, "ex_cldr_calendars": {:hex, :ex_cldr_calendars, "1.25.2", "7c6c84503a52edb512b09d62ad1a2946996b47dbfe29211a99c3a3ffb6043991", [:mix], [{:calendar_interval, "~> 0.2", [hex: :calendar_interval, repo: "hexpm", optional: true]}, {:ex_cldr_lists, "~> 2.10", [hex: :ex_cldr_lists, repo: "hexpm", optional: true]}, {:ex_cldr_numbers, "~> 2.31", [hex: :ex_cldr_numbers, repo: "hexpm", optional: false]}, {:ex_cldr_units, "~> 3.16", [hex: :ex_cldr_units, repo: "hexpm", optional: true]}, {:ex_doc, "~> 0.21", [hex: :ex_doc, repo: "hexpm", optional: true]}, {:jason, "~> 1.0", [hex: :jason, repo: "hexpm", optional: false]}], "hexpm", "a04b0a189bcf38bad919b03fd586938b75454f3a4d56d049b7159bb1cadd7843"}, "ex_cldr_currencies": {:hex, :ex_cldr_currencies, "2.16.1", "29317f533cb5ec046d04523256cca4090291e9157028f28731395149b06ff8b2", [:mix], [{:ex_cldr, "~> 2.38", [hex: :ex_cldr, repo: "hexpm", optional: false]}, {:jason, "~> 1.0", [hex: :jason, repo: "hexpm", optional: true]}], "hexpm", "095d5e973bf0ee066dd1153990d10cb6fa6d8ff0e028295bdce7a7821c70a0e4"}, "ex_cldr_numbers": {:hex, :ex_cldr_numbers, "2.33.1", "49dc6e77e6d9ad22660aaa2480a7408ad3aedfbe517e4e83e5fe3a7bf5345770", [:mix], [{:decimal, "~> 1.6 or ~> 2.0", [hex: :decimal, repo: "hexpm", optional: false]}, {:digital_token, "~> 0.3 or ~> 1.0", [hex: :digital_token, repo: "hexpm", optional: false]}, {:ex_cldr, "~> 2.38", [hex: :ex_cldr, repo: "hexpm", optional: false]}, {:ex_cldr_currencies, "~> 2.16", [hex: :ex_cldr_currencies, repo: "hexpm", optional: false]}, {:jason, "~> 1.0", [hex: :jason, repo: "hexpm", optional: true]}], "hexpm", "c003bfaa3fdee6bab5195f128b94038c2ce1cf4879a759eef431dd075d9a5dac"}, diff --git a/mix/my_app_backend.ex b/mix/my_app_backend.ex index de478c8..3a9711c 100644 --- a/mix/my_app_backend.ex +++ b/mix/my_app_backend.ex @@ -1,6 +1,6 @@ defmodule MyApp.Cldr do use Cldr, - locales: ["en", "fr", "af", "ja", "de", "pl", "th", "fa", "es", "da", "en-CA"], + locales: ["en", "fr", "af", "ja", "de", "pl", "th", "fa", "es", "da", "en-*"], providers: [Cldr.Number, Cldr.Calendar, Cldr.DateTime], precompile_number_formats: ["#,##0"], precompile_transliterations: [{:latn, :thai}] diff --git a/test/cldr_dates_times_test.exs b/test/cldr_dates_times_test.exs index d7a5a6d..3129366 100644 --- a/test/cldr_dates_times_test.exs +++ b/test/cldr_dates_times_test.exs @@ -144,14 +144,6 @@ defmodule Cldr.DatesTimes.Test do assert {:ok, "Sun 9:36 PM"} = Cldr.DateTime.to_string(datetime, format: :Ehm) end - test "Unicode or ASCII preference" do - datetime = ~U[2024-07-07 21:36:00.440105Z] - - unicode = Cldr.DateTime.to_string(datetime, format: :Ehm, prefer: :unicode) - ascii = Cldr.DateTime.to_string(datetime, format: :Ehm, prefer: :ascii) - assert unicode != ascii - end - test "'at' formats" do datetime = ~U[2024-07-07 21:36:00.440105Z] diff --git a/test/interval_test.exs b/test/interval_test.exs index 7a3e1a6..bfde5f2 100644 --- a/test/interval_test.exs +++ b/test/interval_test.exs @@ -39,7 +39,7 @@ defmodule Cldr.DateTime.Interval.Test do assert Cldr.Time.Interval.to_string(~T[10:00:00], ~T[22:03:00], MyApp.Cldr, format: :short, locale: "en-GB" - ) == {:ok, "10 – 22"} + ) == {:ok, "10–22"} end test "right option time interval" do diff --git a/test/variant_test.exs b/test/variant_test.exs index 716b24e..6b37d3b 100644 --- a/test/variant_test.exs +++ b/test/variant_test.exs @@ -1,6 +1,28 @@ defmodule Cldr.DateTime.VariantTest do use ExUnit.Case, async: true + test "Time Unicode or ASCII preference" do + datetime = ~U[2024-07-07 21:36:00.440105Z] + + unicode = Cldr.DateTime.to_string(datetime, format: :Ehm, prefer: :unicode, locale: :en) + ascii = Cldr.DateTime.to_string(datetime, format: :Ehm, prefer: :ascii, locale: :en) + assert unicode != ascii + end + + test "Time preference" do + datetime = ~U[2024-07-07 21:36:00.440105Z] + + assert {:ok, "Sun 9:36 PM"} = + Cldr.DateTime.to_string(datetime, format: :Ehm, prefer: :unicode, locale: :en) + assert {:ok, "Sun 9:36 PM"} = + Cldr.DateTime.to_string(datetime, format: :Ehm, prefer: :ascii, locale: :en) + + assert {:ok, "Sun 9:36 PM"} = + Cldr.DateTime.to_string(datetime, format: :Ehm, prefer: [:unicode], locale: :en) + assert {:ok, "Sun 9:36 PM"} = + Cldr.DateTime.to_string(datetime, format: :Ehm, prefer: [:ascii], locale: :en) + end + test "Date interval variant" do assert {:ok, "1/1/2024 – 1/2/2024"} = Cldr.Date.Interval.to_string ~D[2024-01-01], ~D[2024-02-01], format: :yMd, prefer: :variant, locale: "en-CA"