From 0572befd049049dff707a0fd8ed68d2ac078c8ba Mon Sep 17 00:00:00 2001 From: Simon McConnell <22566656+simonmcconnell@users.noreply.github.com> Date: Thu, 2 Jan 2025 08:35:05 +0800 Subject: [PATCH 1/3] add note about microsecond precision in Calendar.strftime It was not obvious that the microsecond precision affects the formatting. --- lib/elixir/lib/calendar.ex | 54 +++++++++++++++++++------------------- 1 file changed, 27 insertions(+), 27 deletions(-) diff --git a/lib/elixir/lib/calendar.ex b/lib/elixir/lib/calendar.ex index 63af4f15818..39edb9cfb87 100644 --- a/lib/elixir/lib/calendar.ex +++ b/lib/elixir/lib/calendar.ex @@ -496,33 +496,33 @@ defmodule Calendar do The accepted formats for `string_format` are: - Format | Description | Examples (in ISO) - :----- | :-----------------------------------------------------------------------| :------------------------ - a | Abbreviated name of day | Mon - A | Full name of day | Monday - b | Abbreviated month name | Jan - B | Full month name | January - c | Preferred date+time representation | 2018-10-17 12:34:56 - d | Day of the month | 01, 31 - f | Microseconds *(does not support width and padding modifiers)* | 000000, 999999, 0123 - H | Hour using a 24-hour clock | 00, 23 - I | Hour using a 12-hour clock | 01, 12 - j | Day of the year | 001, 366 - m | Month | 01, 12 - M | Minute | 00, 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 - q | Quarter | 1, 2, 3, 4 - s | Number of seconds since the Epoch, 1970-01-01 00:00:00+0000 (UTC) | 1565888877 - S | Second | 00, 59, 60 - u | Day of the week | 1 (Monday), 7 (Sunday) - x | Preferred date (without time) representation | 2018-10-17 - X | Preferred time (without date) representation | 12:34:56 - y | Year as 2-digits | 01, 01, 86, 18 - Y | Year | -0001, 0001, 1986 - z | +hhmm/-hhmm time zone offset from UTC (empty string if naive) | +0300, -0530 - Z | Time zone abbreviation (empty string if naive) | CET, BRST - % | Literal "%" character | % + Format | Description | Examples (in ISO) + :----- | :-------------------------------------------------------------------------------------------------------- | :------------------------ + a | Abbreviated name of day | Mon + A | Full name of day | Monday + b | Abbreviated month name | Jan + B | Full month name | January + c | Preferred date+time representation | 2018-10-17 12:34:56 + d | Day of the month | 01, 31 + f | Microseconds (truncated to the microsecond precision, but *does not support width and padding modifiers*) | 000000, 999999, 0123 + H | Hour using a 24-hour clock | 00, 23 + I | Hour using a 12-hour clock | 01, 12 + j | Day of the year | 001, 366 + m | Month | 01, 12 + M | Minute | 00, 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 + q | Quarter | 1, 2, 3, 4 + s | Number of seconds since the Epoch, 1970-01-01 00:00:00+0000 (UTC) | 1565888877 + S | Second | 00, 59, 60 + u | Day of the week | 1 (Monday), 7 (Sunday) + x | Preferred date (without time) representation | 2018-10-17 + X | Preferred time (without date) representation | 12:34:56 + y | Year as 2-digits | 01, 01, 86, 18 + Y | Year | -0001, 0001, 1986 + z | +hhmm/-hhmm time zone offset from UTC (empty string if naive) | +0300, -0530 + Z | Time zone abbreviation (empty string if naive) | CET, BRST + % | Literal "%" character | % Any other character will be interpreted as an invalid format and raise an error. From 9e9a6a4c13b3f73626d535b33295b5382646d022 Mon Sep 17 00:00:00 2001 From: Simon McConnell Date: Fri, 3 Jan 2025 08:10:01 +1100 Subject: [PATCH 2/3] explain in more detail and add examples --- lib/elixir/lib/calendar.ex | 71 +++++++++++++++++++++++--------------- 1 file changed, 44 insertions(+), 27 deletions(-) diff --git a/lib/elixir/lib/calendar.ex b/lib/elixir/lib/calendar.ex index 39edb9cfb87..0112ecb6497 100644 --- a/lib/elixir/lib/calendar.ex +++ b/lib/elixir/lib/calendar.ex @@ -496,38 +496,55 @@ defmodule Calendar do The accepted formats for `string_format` are: - Format | Description | Examples (in ISO) - :----- | :-------------------------------------------------------------------------------------------------------- | :------------------------ - a | Abbreviated name of day | Mon - A | Full name of day | Monday - b | Abbreviated month name | Jan - B | Full month name | January - c | Preferred date+time representation | 2018-10-17 12:34:56 - d | Day of the month | 01, 31 - f | Microseconds (truncated to the microsecond precision, but *does not support width and padding modifiers*) | 000000, 999999, 0123 - H | Hour using a 24-hour clock | 00, 23 - I | Hour using a 12-hour clock | 01, 12 - j | Day of the year | 001, 366 - m | Month | 01, 12 - M | Minute | 00, 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 - q | Quarter | 1, 2, 3, 4 - s | Number of seconds since the Epoch, 1970-01-01 00:00:00+0000 (UTC) | 1565888877 - S | Second | 00, 59, 60 - u | Day of the week | 1 (Monday), 7 (Sunday) - x | Preferred date (without time) representation | 2018-10-17 - X | Preferred time (without date) representation | 12:34:56 - y | Year as 2-digits | 01, 01, 86, 18 - Y | Year | -0001, 0001, 1986 - z | +hhmm/-hhmm time zone offset from UTC (empty string if naive) | +0300, -0530 - Z | Time zone abbreviation (empty string if naive) | CET, BRST - % | Literal "%" character | % + Format | Description | Examples (in ISO) + :----- | :----------------------------------------------------------------------- | :------------------------ + a | Abbreviated name of day | Mon + A | Full name of day | Monday + b | Abbreviated month name | Jan + B | Full month name | January + c | Preferred date+time representation | 2018-10-17 12:34:56 + d | Day of the month | 01, 31 + f | Microseconds (uses its precision for width and padding) | 000000, 999999, 0123 + H | Hour using a 24-hour clock | 00, 23 + I | Hour using a 12-hour clock | 01, 12 + j | Day of the year | 001, 366 + m | Month | 01, 12 + M | Minute | 00, 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 + q | Quarter | 1, 2, 3, 4 + s | Number of seconds since the Epoch, 1970-01-01 00:00:00+0000 (UTC) | 1565888877 + S | Second | 00, 59, 60 + u | Day of the week | 1 (Monday), 7 (Sunday) + x | Preferred date (without time) representation | 2018-10-17 + X | Preferred time (without date) representation | 12:34:56 + y | Year as 2-digits | 01, 01, 86, 18 + Y | Year | -0001, 0001, 1986 + z | +hhmm/-hhmm time zone offset from UTC (empty string if naive) | +0300, -0530 + Z | Time zone abbreviation (empty string if naive) | CET, BRST + % | Literal "%" character | % Any other character will be interpreted as an invalid format and raise an error. + ### `%f` Microseconds + + `%f` does not support width and padding modifiers. It will be formatted by truncating + the microseconds to the precision of the `microseconds` field of the struct, with a + minimum precision of 1. + ## Examples + Microsecond formatting: + + iex> Calendar.strftime(~U[2019-08-26 13:52:06Z], "%y-%m-%d %H:%M:%S.%f") + "19-08-26 13:52:06.0" + + iex> Calendar.strftime(~U[2019-08-26 13:52:06.048Z], "%y-%m-%d %H:%M:%S.%f") + "19-08-26 13:52:06.048" + + iex> Calendar.strftime(~U[2019-08-26 13:52:06.048531Z], "%y-%m-%d %H:%M:%S.%f") + "19-08-26 13:52:06.048531" + Without user options: iex> Calendar.strftime(~U[2019-08-26 13:52:06.0Z], "%y-%m-%d %I:%M:%S %p") From fa205fd49ed1975a44ebfddc6372a2f5ac4248ec Mon Sep 17 00:00:00 2001 From: Simon McConnell Date: Sat, 4 Jan 2025 21:51:39 +1100 Subject: [PATCH 3/3] move microseconds examples to the end --- lib/elixir/lib/calendar.ex | 76 +++++++++++++++++++------------------- 1 file changed, 38 insertions(+), 38 deletions(-) diff --git a/lib/elixir/lib/calendar.ex b/lib/elixir/lib/calendar.ex index 0112ecb6497..32feaa192de 100644 --- a/lib/elixir/lib/calendar.ex +++ b/lib/elixir/lib/calendar.ex @@ -496,33 +496,33 @@ defmodule Calendar do The accepted formats for `string_format` are: - Format | Description | Examples (in ISO) - :----- | :----------------------------------------------------------------------- | :------------------------ - a | Abbreviated name of day | Mon - A | Full name of day | Monday - b | Abbreviated month name | Jan - B | Full month name | January - c | Preferred date+time representation | 2018-10-17 12:34:56 - d | Day of the month | 01, 31 - f | Microseconds (uses its precision for width and padding) | 000000, 999999, 0123 - H | Hour using a 24-hour clock | 00, 23 - I | Hour using a 12-hour clock | 01, 12 - j | Day of the year | 001, 366 - m | Month | 01, 12 - M | Minute | 00, 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 - q | Quarter | 1, 2, 3, 4 - s | Number of seconds since the Epoch, 1970-01-01 00:00:00+0000 (UTC) | 1565888877 - S | Second | 00, 59, 60 - u | Day of the week | 1 (Monday), 7 (Sunday) - x | Preferred date (without time) representation | 2018-10-17 - X | Preferred time (without date) representation | 12:34:56 - y | Year as 2-digits | 01, 01, 86, 18 - Y | Year | -0001, 0001, 1986 - z | +hhmm/-hhmm time zone offset from UTC (empty string if naive) | +0300, -0530 - Z | Time zone abbreviation (empty string if naive) | CET, BRST - % | Literal "%" character | % + Format | Description | Examples (in ISO) + :----- | :-----------------------------------------------------------------------| :------------------------ + a | Abbreviated name of day | Mon + A | Full name of day | Monday + b | Abbreviated month name | Jan + B | Full month name | January + c | Preferred date+time representation | 2018-10-17 12:34:56 + d | Day of the month | 01, 31 + f | Microseconds (uses its precision for width and padding) | 000000, 999999, 0123 + H | Hour using a 24-hour clock | 00, 23 + I | Hour using a 12-hour clock | 01, 12 + j | Day of the year | 001, 366 + m | Month | 01, 12 + M | Minute | 00, 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 + q | Quarter | 1, 2, 3, 4 + s | Number of seconds since the Epoch, 1970-01-01 00:00:00+0000 (UTC) | 1565888877 + S | Second | 00, 59, 60 + u | Day of the week | 1 (Monday), 7 (Sunday) + x | Preferred date (without time) representation | 2018-10-17 + X | Preferred time (without date) representation | 12:34:56 + y | Year as 2-digits | 01, 01, 86, 18 + Y | Year | -0001, 0001, 1986 + z | +hhmm/-hhmm time zone offset from UTC (empty string if naive) | +0300, -0530 + Z | Time zone abbreviation (empty string if naive) | CET, BRST + % | Literal "%" character | % Any other character will be interpreted as an invalid format and raise an error. @@ -534,17 +534,6 @@ defmodule Calendar do ## Examples - Microsecond formatting: - - iex> Calendar.strftime(~U[2019-08-26 13:52:06Z], "%y-%m-%d %H:%M:%S.%f") - "19-08-26 13:52:06.0" - - iex> Calendar.strftime(~U[2019-08-26 13:52:06.048Z], "%y-%m-%d %H:%M:%S.%f") - "19-08-26 13:52:06.048" - - iex> Calendar.strftime(~U[2019-08-26 13:52:06.048531Z], "%y-%m-%d %H:%M:%S.%f") - "19-08-26 13:52:06.048531" - Without user options: iex> Calendar.strftime(~U[2019-08-26 13:52:06.0Z], "%y-%m-%d %I:%M:%S %p") @@ -586,6 +575,17 @@ defmodule Calendar do ...>) "серпень" + Microsecond formatting: + + iex> Calendar.strftime(~U[2019-08-26 13:52:06Z], "%y-%m-%d %H:%M:%S.%f") + "19-08-26 13:52:06.0" + + iex> Calendar.strftime(~U[2019-08-26 13:52:06.048Z], "%y-%m-%d %H:%M:%S.%f") + "19-08-26 13:52:06.048" + + iex> Calendar.strftime(~U[2019-08-26 13:52:06.048531Z], "%y-%m-%d %H:%M:%S.%f") + "19-08-26 13:52:06.048531" + """ @doc since: "1.11.0" @spec strftime(map(), String.t(), keyword()) :: String.t()