@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 the given date, time, or 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.

Examples of common usage:

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"

User 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 the string_format argument 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 string formats

The accepted formats for string_format are:

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

Examples

Without user 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 user 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).