txt: ## dist_zef-tbrowder-Timezones-US.md
  [![Actions Status](https://github.com/tbrowder/Timezones-US/actions/workflows/linux.yml/badge.svg)](https://github.com/tbrowder/Timezones-US/actions) [![Actions Status](https://github.com/tbrowder/Timezones-US/actions/workflows/macos.yml/badge.svg)](https://github.com/tbrowder/Timezones-US/actions) [![Actions Status](https://github.com/tbrowder/Timezones-US/actions/workflows/windows.yml/badge.svg)](https://github.com/tbrowder/Timezones-US/actions)
  
  # NAME
  
  **Timezones::US** - Provides US time zone data and subroutines for use with modules 'DateTime::US' and 'LocalTime'
  
  # SYNOPSIS
  
  ```
  use Timezones::US;
  
  ```
  
  # DESCRIPTION
  
  Raku module **Timezones::US** provides constant US time zone data (currently valid through the year 2030) to be used by related date and time dynamic modules.
  
  The following table shows the time zones included:
  
  US Time Zones
  
  | Name | Symbol | UTC offset (hrs) |
  | --- | --- | --- |
  | Atlantic | AST | -4, |
  | Eastern | EST | -5 |
  | Central | CST | -6 |
  | Mountain | MST | -7 |
  | Pacific | PST | -8 |
  | Alaska | AKST | -9 |
  | Hawaii-Aleutian | HAST | -10 |
  | Samoa | WST | -11 |
  | Chamorro | CHST | +10 |
  
  ### Exported constants
  
  The following constants are automatically exported into the using environment:
  
  * `SEC-PER-HOUR`
  
    Seconds per hour: 3600
  * `@tz`
  
    A list of time zones (lower-case symbols)
  * `%tzones`
  
    A hash of all US time zone abbreviations keyed by their symbols (lower-case) with values of names and UTC offsets
  * `%dst-exceptions`
  
    A hash of US time zone abbreviations keyed by their symbols (lower-case) with values of states or regions and details of Daylight Saving exceptions (**CAUTION**: this an incomplete list at the moment)
  * `%utc-offsets`
  
    A hash of US time zone abbreviations keyed by their symbols (lower-case) with value of their UTC offset in hours
  * `%offsets-utc`
  
    A hash of US time zone offsets keyed by their hours with value of their symbols (lower-case)
  
  ### Exported subroutines
  
  The following subroutines are automatically exported into the using environment:
  
  * **begin-dst**($year --> DateTime) {...}
  
    Return the time when DST (Daylight Saving Time) begins.
  * **end-dst**($year --> DateTime) {...}
  
    Return the time when DST ends.
  * **is-dst**(DateTime :$localtime! --> Bool) {...}
  
    Return True if the local time is DST, otherwise return False.
  * **is-dst**(:$year!, :$month, :$day, :$hour, :$minute, :$second --> Bool) {...}
  
    Return True if the local time is DST, otherwise return False.
  * **show-us-data**(--> Str) {...}
  
    List the time zone and DST data being used.
  
  Note some of these routines are now duplicated in module `DateTime::US`, but those are (1) perpetual and (2) return `Date` objects instead of `DateTime` objects which are preferred for use by the author's module `Calendar`. As well, this module was designed to be completely standalone.
  
  If the user requires "perpetual" DST dates for all all years affected under current US federal law, please use the routines in `DateTime::US`.
  
  # AUTHOR
  
  Tom Browder [tbrowder@acm.org](mailto:tbrowder@acm.org)
  
  # COPYRIGHT AND LICENSE
  
  © 2022-2024 Tom Browder
  
  This library is free software; you may redistribute it or modify it under the Artistic License 2.0.
  