@spec compatible_calendars?(calendar(), calendar()) :: boolean()

Returns true if two calendars have the same moment of starting a new day, false otherwise.

If two calendars are not compatible, we can only convert datetimes and times between them. If they are compatible, this means that we can also convert dates as well as naive datetimes between them.

@spec get_time_zone_database() :: time_zone_database()

Gets the current time zone database.

@spec put_time_zone_database(time_zone_database()) :: :ok

Sets the current time zone database.

@spec strftime(map(), String.t(), keyword()) :: String.t()

Formats received datetime into a string.

The datetime can be any of the Calendar types (Time, Date, NaiveDateTime, and DateTime) or any map, as long as they contain all of the relevant fields necessary for formatting. For example, if you use %Y to format the year, the datetime must have the :year field. Therefore, if you pass a Time, or a map without the :year field to a format that expects %Y, an error will be raised.

Options

• :preferred_datetime - a string for the preferred format to show datetimes, it can't contain the %c format and defaults to "%Y-%m-%d %H:%M:%S" if the option is not received

• :preferred_date - a string for the preferred format to show dates, it can't contain the %x format and defaults to "%Y-%m-%d" if the option is not received

• :preferred_time - a string for the preferred format to show times, it can't contain the %X format and defaults to "%H:%M:%S" if the option is not received

• :am_pm_names - a function that receives either :am or :pm and returns the name of the period of the day, if the option is not received it defaults to a function that returns "am" and "pm", respectively

• :month_names - a function that receives a number and returns the name of the corresponding month, if the option is not received it defaults to a function that returns the month names in English

• :abbreviated_month_names - a function that receives a number and returns the abbreviated name of the corresponding month, if the option is not received it defaults to a function that returns the abbreviated month names in English

• :day_of_week_names - a function that receives a number and returns the name of the corresponding day of week, if the option is not received it defaults to a function that returns the day of week names in English

• :abbreviated_day_of_week_names - a function that receives a number and returns the abbreviated name of the corresponding day of week, if the option is not received it defaults to a function that returns the abbreviated day of week names in English

Formatting syntax

The formatting syntax for strftime is a sequence of characters in the following format:

%<padding><width><format>

where:

• %: indicates the start of a formatted section
• <padding>: set the padding (see below)
• <width>: a number indicating the minimum size of the formatted section
• <format>: the format itself (see below)

Accepted padding options

• -: no padding, removes all padding from the format
• _: pad with spaces
• 0: pad with zeroes

Accepted formats

The accepted formats are:

Any other character will be interpreted as an invalid format and raise an error

Examples

Without options:

iex> Calendar.strftime(~U[2019-08-26 13:52:06.0Z], "%y-%m-%d %I:%M:%S %p")
"19-08-26 01:52:06 PM"

iex> Calendar.strftime(~U[2019-08-26 13:52:06.0Z], "%a, %B %d %Y")
"Mon, August 26 2019"

iex> Calendar.strftime(~U[2020-04-02 13:52:06.0Z], "%B %-d, %Y")
"April 2, 2020"

iex> Calendar.strftime(~U[2019-08-26 13:52:06.0Z], "%c")
"2019-08-26 13:52:06"

With options:

iex> Calendar.strftime(~U[2019-08-26 13:52:06.0Z], "%c", preferred_datetime: "%H:%M:%S %d-%m-%y")
"13:52:06 26-08-19"

iex> Calendar.strftime(
...>  ~U[2019-08-26 13:52:06.0Z],
...>  "%A",
...>  day_of_week_names: fn day_of_week ->
...>    {"segunda-feira", "terça-feira", "quarta-feira", "quinta-feira",
...>    "sexta-feira", "sábado", "domingo"}
...>    |> elem(day_of_week - 1)
...>  end
...>)
"segunda-feira"

iex> Calendar.strftime(
...>  ~U[2019-08-26 13:52:06.0Z],
...>  "%B",
...>  month_names: fn month ->
...>    {"январь", "февраль", "март", "апрель", "май", "июнь",
...>    "июль", "август", "сентябрь", "октябрь", "ноябрь", "декабрь"}
...>    |> elem(month - 1)
...>  end
...>)
"август"

@spec truncate(microsecond(), :microsecond | :millisecond | :second) :: microsecond()

Returns a microsecond tuple truncated to a given precision (:microsecond, :millisecond or :second).