Rand Stats

DateTime::US

zef:tbrowder

Actions Status Actions Status Actions Status

NAME

DateTime::US - Provides time zone (TZ) and Daylight Saving Time (DST) information for US states and territories

SYNOPSIS

use DateTime::US;
use DateTime::Subs; # part of the 'DateTime::US' distribution

DESCRIPTION

Module DateTime::US provides a class with methods used to help Raku programs needing US time zone and DST information. The user creates a DateTime::US object by providing a US time zone abbreviation (note the TZ input abbreviation may be in either format for standard or daylight saving time, e.g., 'CST' or 'CDT'). The list of known data may be listed without an object:

$ raku
> use DateTime::US;
> show-us-data;

The main use case that motivated the module is to convert time in UTC to local time for creating calendars and almanacs. For example, local Sunrise is given in UTC and will normally be shown on a calendar in local time:

my $tz = DateTime::US.new: :timezone<CST>;
my $sunriseZ = DateTime.new: "2024-02-21T12:23:00Z";
say $sunriseZ; # OUTPUT: «2024-02-21T12:23:00Z␤»
my $localtime = $tz.to-localtime :utc($sunriseZ);
say $localtime; # OUTPUT: «2024-02-21T06:23:00 CST␤»

Class methods

Subroutines

It is useful to have a "perpetual" calculation of the begin/end dates for DST for all years covered by the current governing federal law for the US. Assisted by the Date::Utils module, the following routines do that, and they require an export tag for use to avoid possible conflict from other modules.

The :$year argument defaults to the current year if it is not provided.

The final routine is for use by module Date::Event. The :$set-id argument is used to provide a globally unique ID (GUID) to allow multiple Date::Event objects for a Date in a Hash keyed by Dates.

SEE ALSO

Todo

Provide handling for the exceptions to the use of DST where indicated.

Note

The author is happy to create or collaborate on a similar module for other regions. If interested, simply file an issue or discuss it on IRC #raku (author's handle is 'tbrowder').

AUTHOR

Tom Browder tbrowder@acm.org

COPYRIGHT AND LICENSE

© 2021-2024 Tom Browder

This library is free software; you may redistribute or modify it under the Artistic License 2.0.