Packages
ex_cldr_dates_times
0.1.0
2.25.6
2.25.5
2.25.4
2.25.3
2.25.2
2.25.1
2.25.0
2.24.2
2.24.1
2.24.0
2.23.0
2.22.0
2.21.0
2.20.3
2.20.2
2.20.0
2.19.2
2.19.1
2.19.0
retired
2.18.1
2.18.0
2.17.1
2.17.0
2.16.0
2.15.0
2.14.3
2.14.2
2.14.1
2.14.0
2.13.3
2.13.2
2.13.1
2.13.0
2.12.0
2.11.0
2.10.2
2.10.1
2.10.0
2.10.0-rc.3
2.10.0-rc.2
2.10.0-rc.1
2.10.0-rc.0
2.9.4
2.9.3
2.9.2
2.9.1
2.9.0
2.8.0
2.7.2
2.7.1
retired
2.7.0
2.7.0-rc.0
2.6.4
2.6.3
2.6.2
2.6.1
retired
2.6.0
2.6.0-rc.0
2.5.4
2.5.3
2.5.2
2.5.1
2.5.0
2.4.0
2.4.0-rc.0
2.3.0
2.2.4
2.2.3
2.2.2
2.2.1
2.2.0
2.1.0
2.0.2
2.0.1
2.0.0
1.4.0
1.3.1
1.3.0
1.2.1
1.2.0
1.0.1
1.0.0
1.0.0-rc.1
1.0.0-rc.0
retired
0.3.3
0.3.2
retired
0.3.1
retired
0.3.0
0.2.2
0.2.1
0.2.0
0.1.2
0.1.1
0.1.0
Date, Time and DateTime localization, internationalization and formatting functions using the Common Locale Data Repository (CLDR).
Current section
Files
Jump to
Current section
Files
lib/cldr/datetime/time.ex
defmodule Cldr.Time do
@moduledoc """
Provides an API for the localization and formatting of a `Time`
struct or any map with the keys `:hour`, `:minute`,
`:second` and optionlly `:microsecond`.
CLDR provides standard format strings for `Time` which
are reresented by the names `:short`, `:medium`, `:long`
and `:full`. This allows for locale-independent
formatting since each locale may define the underlying
format string as appropriate.
"""
alias Cldr.DateTime.{Format, Formatter}
@doc """
Formats a time according to a format string
as defined in CLDR and described in [TR35](http://unicode.org/reports/tr35/tr35-dates.html)
Returns either `{:ok, formatted_time}` or `{:error, reason}`.
* `time` is a `%DateTime{}` or `%NaiveDateTime{}` struct or any map that contains the keys
`hour`, `minute`, `second` and optionally `calendar` and `microsecond`
* `options` is a keyword list of options for formatting. The valid options are:
* `format:` `:short` | `:medium` | `:long` | `:full` or a format string. The default is `:medium`
* `locale:` any locale returned by `Cldr.known_locales()`. The default is `Cldr.get_current_locale()`
* `number_system:` a number system into which the formatted date digits should be transliterated
## Examples
iex> Cldr.Time.to_string ~T[07:35:13.215217]
{:ok, "7:35:13 AM"}
iex> Cldr.Time.to_string ~T[07:35:13.215217], format: :short
{:ok, "7:35 AM"}
iex> Cldr.Time.to_string ~T[07:35:13.215217], format: :medium, locale: "fr"
{:ok, "07:35:13"}
iex> Cldr.Time.to_string ~T[07:35:13.215217], format: :medium
{:ok, "7:35:13 AM"}
iex> {:ok, datetime} = DateTime.from_naive(~N[2000-01-01 23:59:59.0], "Etc/UTC")
iex> Cldr.Time.to_string datetime, format: :long
{:ok, "11:59:59 PM UTC"}
"""
@format_types [:short, :medium, :long, :full]
def to_string(time, options \\ [])
def to_string(%{hour: _hour, minute: _minute} = time, options) do
default_options = [format: :medium, locale: Cldr.get_current_locale()]
options = Keyword.merge(default_options, options)
calendar = Map.get(time, :calendar) || Calendar.ISO
with {:ok, locale} <- Cldr.valid_locale?(options[:locale]),
{:ok, cldr_calendar} <- Formatter.type_from_calendar(calendar),
{:ok, format_string} <- format_string_from_format(options[:format], locale, cldr_calendar),
{:ok, formatted} <- Formatter.format(time, format_string, locale, options)
do
{:ok, formatted}
else
{:error, reason} -> {:error, reason}
end
end
def to_string(time, _options) do
error_return(time, [:hour, :minute, :second])
end
@doc """
Formats a time according to a format string
as defined in CLDR and described in [TR35](http://unicode.org/reports/tr35/tr35-dates.html).
Returns either the formatted time or raises an exception.
* `time` is a `%DateTime{}` or `%NaiveDateTime{}` struct or any map that contains the keys
`hour`, `minute`, `second` and optionally `calendar` and `microsecond`
* `options` is a keyword list of options for formatting. The valid options are:
* `format:` `:short` | `:medium` | `:long` | `:full` or a format string. The default is `:medium`
* `locale:` any locale returned by `Cldr.known_locales()`. The default is `Cldr.get_current_locale()`
* `number_system:` a number system into which the formatted date digits should be transliterated
## Examples
iex> Cldr.Time.to_string! ~T[07:35:13.215217]
"7:35:13 AM"
iex> Cldr.Time.to_string! ~T[07:35:13.215217], format: :short
"7:35 AM"
iex> Cldr.Time.to_string! ~T[07:35:13.215217], format: :medium, locale: "fr"
"07:35:13"
iex> Cldr.Time.to_string! ~T[07:35:13.215217], format: :medium
"7:35:13 AM"
iex> {:ok, datetime} = DateTime.from_naive(~N[2000-01-01 23:59:59.0], "Etc/UTC")
iex> Cldr.Time.to_string! datetime, format: :long
"11:59:59 PM UTC"
"""
def to_string!(time, options \\ [])
def to_string!(time, options) do
case to_string(time, options) do
{:ok, string} -> string
{:error, {exception, message}} -> raise exception, message
end
end
defp format_string_from_format(format, locale, calendar) when format in @format_types do
format_string =
locale
|> Format.time_formats(calendar)
|> Map.get(format)
{:ok, format_string}
end
defp format_string_from_format(%{number_system: number_system, format: format}, locale, calendar) do
{:ok, format_string} = format_string_from_format(format, locale, calendar)
{:ok, %{number_system: number_system, format: format_string}}
end
defp format_string_from_format(format, _locale, _calendar) when is_atom(format) do
{:error, {Cldr.InvalidTimeFormatType, "Invalid time format type. " <>
"The valid types are #{inspect @format_types}."}}
end
defp format_string_from_format(format_string, _locale, _calendar) when is_binary(format_string) do
{:ok, format_string}
end
defp error_return(map, requirements) do
{:error, {ArgumentError, "Invalid time. Time is a map that requires at least #{inspect requirements} fields. " <>
"Found: #{inspect map}"}}
end
end