txt: ## dist_zef-lizmat-DateTime-strftime.md
  [![Actions Status](https://github.com/lizmat/DateTime-strftime/actions/workflows/linux.yml/badge.svg)](https://github.com/lizmat/DateTime-strftime/actions) [![Actions Status](https://github.com/lizmat/DateTime-strftime/actions/workflows/macos.yml/badge.svg)](https://github.com/lizmat/DateTime-strftime/actions) [![Actions Status](https://github.com/lizmat/DateTime-strftime/actions/workflows/windows.yml/badge.svg)](https://github.com/lizmat/DateTime-strftime/actions)
  
  # NAME
  
  DateTime::strftime - provide strftime() formatting for DateTime objects
  
  # SYNOPSIS
  
  ```
  use DateTime::strftime;
  
  say strftime(DateTime.now, '%c');  # default": EN
  # Sun Jan 19 13:19:02 +0100 2025
  
  say strftime(DateTime.now, '%c', "NL");
  # zon 19 jan 13:19:02 +0100 2025
  
  ```
  
  # DESCRIPTION
  
  The `DateTime::strftime` distribution provides a `strftime` subroutine that takes a `DateTime` object, a [`strftime`](https://linux.die.net/man/3/strftime) format string (or its `:text:` equivalent), and an optional locale indicator (which defaults to the dynamic variable `$*LOCALE-DATES` or `"EN"`).
  
  It returns the representation of the `DateTime` object according to that format and locale.
  
  # FORMAT SPECIFICATION
  
  The supported formats are a (large) subset of `strftime`. The `E` and `O` modifiers are **not** supported.
  
  Since the `strftime` format codes are rather cryptic (although very widely in use), one can also use an alternate `:text:` format. So instead of the rather cryptic `"%c"`, one can also use `":datetime:"`.
  
  | Code | :text: | Value |
  | --- | --- | --- |
  | %a | wkdname | abbreviated weekday name |
  | %A | weekdayname | full weekday name |
  | %b | mnthname | abbreviated month name |
  | %B | monthname | full month name |
  | %c | datetime | preferred date/time representation |
  | %C | century | century number (year div 100) |
  | %d | 0day | day of month ("01" .. "31") |
  | %D | usadate | short for: %m/%d/%y |
  | %e | day | day of month (" 1" .. "31") |
  | %f |  | same as %M |
  | %F | isodate | short for: %Y/%m/%d |
  | %g | weekYY | YY of this week ("00" .. "99") |
  | %G | weekYYYY | full year of this week |
  | %h |  | same as %b |
  | %H | 0hour | 24-hour hour ("00" .. "23") |
  | %I | 0amhour | 12-hour hour ("01" .. "12") |
  | %j | yearday | day of the year ("001" .. "366") |
  | %k | hour | 24-hour hour (" 1" .. "23") |
  | %l | amhour | 12-hour hour (" 1" .. "12") |
  | %L |  | same as %Y |
  | %m | month | month ("01" .. "12") |
  | %M | minute | minute ("00" .. "59") |
  | %n | newline | "\n" |
  | %p | AMPM | "AM" | "PM" |
  | %P | ampm | "am" | "pm" |
  | %r | amtime | short for: %I:%M:%S %p |
  | %R | HHMM | short for: %H:%M |
  | %s | epoch | seconds since epoch (midnight 1970-01-01 UTC) |
  | %S | second | second ("00" .. "59") |
  | %t | tab | "\t" |
  | %T | HHMMSS | short for: %H:%M:%S |
  | %u | weekday | weekday (1 .. 7) |
  | %U | weekSun | week number (first Sunday) ("00" .. "53") |
  | %v | DD-MON-YYYY | short for: %e-%b-%Y |
  | %V | weekISO | week number (ISO 8601) ("00" .. "53") |
  | %w | 0weekday | weekday (0 .. 6) |
  | %W | weekMon | week number (first Monday) ("00" .. "53") |
  | %x | date | preferred date representation |
  | %X | time | preferred time representation |
  | %y | YY | year without century ("00" .. "99") |
  | %Y | year | year (yyyy) |
  | %z | tzoffset | numeric timezone (±HHMM) |
  | %Z | timezone | timezone (no name: %z) |
  | %+ | unixdate | short for: %a %b %e %T %Z %Y |
  | %% | percent | "%" |
  
  Please note that one probably shouldn't use the `%g` and `%y` formats for anything that is persistent. Data and programs stay around longer then anybody expects, and we don't want another [Y2K](https://en.wikipedia.org/wiki/Year_2000_problem) problem, especially in a 100-year programming language!
  
  # DEFAULT LOCALIZATION
  
  ```
  my $*LOCALE-DATES = "NL";
  say strftime($dt, ':weekdayname:');        # zondag
  say strftime($dt, ':weekdayname:', "EN");  # Sunday
  
  ```
  
  The `$*LOCALE-DATES` dynamic variable can be set with the string of the desired localization, or with an instantiated `Locale::Dates` object. It will then affect any call to `strftime` that does **not** have an explicit localization specified.
  
  # LEXICAL REFINEMENT
  
  ```
  use DateTime::strftime :refine;
  
  say DateTime.now.strftime('%c');  # default": EN
  # Sun Jan 19 13:19:02 +0100 2025
  
  say DateTime.now.strftime(':datetime:', "NL");
  # zon 19 jan 13:19:02 +0100 2025
  
  ```
  
  You can also use `DateTime::strftime` with the `:refine` parameter. This will add a `strftime` method to the `DateTime` class in the lexical scope in which the `use` statement is located. This allows one to not to have to change existing code using the `DateTime` class, while still having the added functionality of a `DateTime.strftime` method.
  
  # OTHER SOFTWARE
  
  See also Jean Forget's [`Date::Calendar::Strftime`](https://raku.land/zef:jforget/Date::Calendar::Strftime) and [`Date::Calendar::Gregorian`](https://raku.land/zef:jforget/Date::Calendar::Gregorian).
  
  # AUTHOR
  
  Elizabeth Mattijsen [liz@raku.rocks](mailto:liz@raku.rocks)
  
  Source can be located at: <https://github.com/lizmat/DateTime-strftime> . Comments and Pull Requests are welcome.
  
  If you like this module, or what I'm doing more generally, committing to a [small sponsorship](https://github.com/sponsors/lizmat/) would mean a great deal to me!
  
  # COPYRIGHT AND LICENSE
  
  Copyright 2025 Elizabeth Mattijsen
  
  This library is free software; you can redistribute it and/or modify it under the Artistic License 2.0.
  