NimbleStrftime

NimbleStrftime v0.1.1 NimbleStrftime View Source

Simple datetime formatting based on the strftime format found on UNIX-like systems.

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 iself (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:

FormatDescriptionExamples (in ISO)
aAbbreviated name of dayMon
AFull name of dayMonday
bAbbreviated month nameJan
BFull month nameJanuary
cPreferred date+time representation2018-10-17 12:34:56
dDay of the month01, 12
fMicroseconds (does not support width and padding modifiers)000000, 999999, 0123
HHour using a 24-hour clock00, 23
IHour using a 12-hour clock01, 12
jDay of the year001, 366
mMonth01, 12
MMinute00, 59
p"AM" or "PM" (noon is "PM", midnight as "AM")AM, PM
P"am" or "pm" (noon is "pm", midnight as "am")am, pm
qQuarter1, 2, 3, 4
SSecond00, 59, 60
uDay of the week1 (Monday), 7 (Sunday)
xPreferred date (without time) representation2018-10-17
XPreferred time (without date) representation12:34:56
yYear as 2-digits01, 01, 86, 18
YYear-0001, 0001, 1986
z+hhmm/-hhmm time zone offset from UTC (empty string if naive)+0300, -0530
ZTime zone abbreviation (empty string if naive)CET, BRST
%Literal "%" character%

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

Link to this section Summary

Functions

format(date_or_time_or_datetime, string_format, user_options \\ [])

Formats received datetime into a string.

Link to this section Functions

Link to this function

format(date_or_time_or_datetime, string_format, user_options \\ [])

View Source 
format(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 datatime 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 thet 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 thet 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

Examples

Without options:

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

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

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

With options:

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

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