info > Date::Manip::TZ

man perldoc info pydoc3 ri search

Date::Manip::TZ(3pm) User Contributed Perl Documentation Date::Manip::TZ(3pm)

📛 NAME

Date::Manip::TZ - an interface to the time zone data

🚀 Quick Reference

Use Case	Command	Description
Create TZ object	use Date::Manip::TZ; $tz = new Date::Manip::TZ;	Initialize a new time zone handler
Convert date to GMT	$tz->convert_to_gmt($date [, $from [, $isdst]])	Convert a date to universal time
Convert date from GMT	$tz->convert_from_gmt($date [, $to])	Convert a GMT date to another zone
Convert between time zones	$tz->convert($date, $from, $to [, $isdst])	Convert a date from one time zone to another
Get all periods for a year	$tz->all_periods($zone, $year)	Return all periods occurring in a given year (GMT)
Get periods starting in a year	$tz->periods($zone, $year)	Return periods that begin in a specified year
Define abbreviation preference	$tz->define_abbrev($abbrev, @zone)	Set order of zones for a given abbreviation
Define alias	$tz->define_alias($alias, $zone)	Add or override a time zone alias
Find matching zones	$tz->zone(@args)	Return zones matching name, offset, abbreviation, date, or dstflag
Get system time zone	$tz->curr_zone()	Return the local time zone

📋 SYNOPSIS

use Date::Manip::TZ;
$tz = new Date::Manip::TZ;

Data for most (and hopefully all) time zones used around the world have been gathered and is publicly available in the zoneinfo (or Olson) database.

This module uses the data from the zoneinfo database to perform various time zone operations.

📖 DESCRIPTION

Every time zone has some of the following characteristics:

• 📛 name – Every time zone has a unique name. In the zoneinfo database, these are something similar to: America/New_York
• 🔗 aliases – Time zones may have one or more unique aliases. An alias can be used exactly like a name.
• 📅 periods – Every time zone is broken up into periods. Each period describes how a portion of time relates to GMT, and how it might be expressed.

Each period includes the following information:

• ⏱️ start time, end time – The period begins and ends at certain times (both absolute GMT and wall clock time).
• 📏 offset – How much the wall clock time differs from GMT.
• 🔤 abbreviation – Typically an abbreviation (such as EST).
• ☀️ daylight saving time flag – 1 if DST, 0 if standard time.

Date::Manip includes all of the data for all of the time zones from the zoneinfo database. This data is available from: ftp://ftp.iana.org/tz/

The zoneinfo database is not necessary to use Date::Manip. Instead, all data has been extracted and stored in a series of other modules. The Date::Manip::Zones document contains detailed information on the data available.

⚙️ METHODS

In all methods, the following variables are used:

• $zone – A string containing a valid time zone name (e.g., America/New_York).
• $alias – A string containing a valid time zone name or alias (e.g., America/New_York, US/Eastern, EST5EDT).
• $abbrev – A string containing a valid time zone abbreviation (e.g., EST).
• $offset – A time zone entered as an offset: string formats +HH, +HHMM, +HHMMSS, +HH:MM, +HH:MM:SS or a list reference [HH,MM,SS]. Sign must be included with all values.
• $dstflag – One of: std, stdonly, dst, dstonly. Defaults to std. Controls whether to check standard or DST times.
• $date – A string in formats YYYYMMDDHH:MN:SS, YYYY-MM-DD-HH:MN:SS, YYYYMMDDHHMNSS or a list reference [Y,M,D,H,MN,S].
• $isdst – 0 for standard time, 1 for daylight saving time.
• $period – A list reference containing: [ $dateUT, $dateLT, $offsetstr, $offset, $abbrev, $isdst, $endUT, $endLT, $begUTs, $begLTs, $endUTs, $endLTs ]. Use only positive indices.

📦 base / config / err / new / new_config

Please refer to the Date::Manip::Obj documentation for these methods.

📅 all_periods

@periods = $tz->all_periods($zone,$year);

Returns the description of all time zone periods that occur (in full or in part) during the given year (GMT).

🔄 convert / convert_to_gmt / convert_from_gmt / convert_to_local / convert_from_local

These functions convert a date from one time zone to another.

($err,$date,$offset,$isdst,$abbrev) =
   $tz->convert($date,$from,$to [,$isdst]);

Converts a date from time zone $from to $to.

($err,$date,$offset,$isdst,$abbrev) =
   $tz->convert_to_gmt($date [,$from] [,$isdst]);

Converts to GMT. If $from omitted, defaults to local time zone. $isdst returned is always 0.

($err,$date,$offset,$isdst,$abbrev) =
   $tz->convert_from_gmt($date [,$to]);

Converts from GMT. If $to omitted, converts to local time zone.

($err,$date,$offset,$isdst,$abbrev) =
   $tz->convert_to_local($date [,$from] [,$isdst]);
($err,$date,$offset,$isdst,$abbrev) =
   $tz->convert_from_local($date [,$to] [,$isdst]);

Similar to GMT functions. If $from or $to are omitted, they default to GMT.

If $date is ambiguous (e.g., repeated during clock fall-back), $isdst can be passed to disambiguate. The returned $isdst is 1 if DST, $offset is a list reference, $abbrev is the abbreviation.

Error codes:

• 0 = No error
• 1 = Invalid arguments
• 2 = Invalid FROM zone
• 3 = Invalid TO zone
• 4 = Invalid date

🏠 curr_zone

$tz->curr_zone();

Returns the system time zone (determined by methods described in DETERMINING THE SYSTEM TIME ZONE). This is the default time zone unless SetDate or ForceDate config variables are set.

$tz->curr_zone(1);

Clears and re-determines the system time zone.

🔧 curr_zone_methods

$tz->curr_zone_methods(@methods);

Sets the list and order of methods to use in determining the local time zone. Arguments may be required after method names. This method may not be used in taint mode.

📅 date_period

$period = $tz->date_period($date,$zone,$wall_clock [,$isdst]);

Returns the period information for the given date. $date defaults to GMT; if $wall_clock is non-zero, it is treated as local time. If wall clock time doesn't exist (spring forward), nothing is returned. If it appears twice (fall back), $isdst is used to pick standard or DST.

🔤 define_abbrev

($err,$val) = $tz->define_abbrev($abbrev,@zone);

Sets the order of zones checked when an abbreviation is encountered. If $abbrev is "reset", all abbreviations are reset to standard. If @zone contains only 'reset', the default list for $abbrev is restored.

Error codes:

• 0 = No error
• 1 = $abbrev is not a valid abbreviation in any time zone
• 2 = A zone (returned as $val) is not a valid time zone
• 3 = A zone (returned as $val) does not use the abbreviation

🔗 define_alias

$err = $tz->define_alias($alias,$zone);

Defines a new alias (or overrides an existing one). $zone must be valid. If $alias is "reset", all aliases reset. If $zone is "reset", $alias is reset to default.

📏 define_offset

($err,$val) = $tz->define_offset($offset, [$dstflag,] @zone);

Similar to define_abbrev but for offsets. $offset can be "reset" to reset all lists. If @zone contains only 'reset', the default list is restored for $offset (without $dstflag).

Error codes:

• 0 = No error
• 1 = $offset is not a valid offset in any time zone
• 2 = $offset is not a valid offset in the selected time (if doing "dstonly" or "stdonly")
• 3 = A zone (returned as $val) is not a valid time zone
• 4 = A zone (returned as $val) does not use the offset
• 5 = A zone (returned as $val) does not include the offset in the selected time
• 9 = Offset is not a valid offset

📅 periods

@periods = $tz->periods($zone,$year);

Returns periods that begin during the given year (GMT).

@periods = $tz->periods($zone,undef,$year);

Returns all periods that begin in any year from 0001 to $year.

@periods = $tz->periods($zone,$year0,$year1);

Returns periods that begin from $year0 to $year1.

📦 tzdata / tzcode

$vers = $tz->tzdata();
$vers = $tz->tzcode();

Returns the versions of the tzdata and tzcode packages used to generate the modules.

🌐 zone

$zone = $tz->zone(@args);
@zone = $tz->zone(@args);

Returns a list of zones matching all supplied information. In scalar context, returns the default zone. @args may include: a zone name/alias, abbreviation, offset, dstflag, or date. Do not include two of the same type. If an error occurs, undef is returned. If no match, empty string or list.

Order is determined by abbreviation (if given) or offset (if given), with standard times first unless $dstflag is "dst". If a date is given, only zones where that date appears are included. If no zone/abbrev/offset, the local time zone may be returned.

Note: When using an offset with a date, the default $dstflag is "dst" (not "std") to get DST zones.

🕐 TIME ZONE INFORMATION IN DATE::MANIP

Date::Manip uses three potentially different time zones:

• 🌍 Local time zone – The actual time zone the computer runs in.
• 🕰️ Working time zone – Defaults to local time zone, can be changed via SetDate or ForceDate config variables.
• 📅 Parsed time zone – The time zone specified in a date string. If none, defaults to working time zone.

🔍 DETERMINING THE SYSTEM TIME ZONE

There are many methods for determining the time zone. The default list can be overridden by curr_zone_methods. Available methods:

Method	Argument(s)	Procedure
main	VAR	Check the main variable named VAR (e.g., main TZ checks $::TZ)
env	TYPE VAR	Check environment variable; TYPE can be zone or offset (seconds from UTC)
file	FILE	Look in the given file for lines like ZONE, tz = ZONE, etc.
command	COMMAND	Run a command that outputs a time zone
cmdfield	COMMAND N	Run a command and take the Nth whitespace-separated field (0-based or -1 from end)
gmtoff		Use the current offset from GMT as a best guess
tzdata	FILE DIR	Use a system config file that points to local tzdata files (e.g., /etc/localtime and /usr/share/zoneinfo)
registry		Look up in Windows registry (Windows only)

Note: "main" and "env" should only be used to specify the actual system time zone. Use SetDate/ForceDate for alternate working zones.

Default methods for Unix:

main     TZ
env      zone TZ
file     /etc/TIMEZONE
file     /etc/timezone
file     /etc/sysconfig/clock
file     /etc/default/init
command  "/bin/date +%Z"
command  "/usr/bin/date +%Z"
command  "/usr/local/bin/date +%Z"
cmdfield /bin/date             -2
cmdfield /usr/bin/date         -2
cmdfield /usr/local/bin/date   -2
command  "/bin/date +%z"
command  "/usr/bin/date +%z"
command  "/usr/local/bin/date +%z"
tzdata   /etc/localtime /usr/share/zoneinfo
gmtoff

Default methods for Windows:

main     TZ
env      zone TZ
registry
gmtoff

Default methods for VMS:

main     TZ
env      zone TZ
env      zone SYS$TIMEZONE_NAME
env      zone UCX$TZ
env      zone TCPIP$TZ
env      zone MULTINET_TIMEZONE
env      offset SYS$TIMEZONE_DIFFERENTIAL
gmtoff

Default methods for other systems:

main     TZ
env      zone TZ
gmtoff

The returned value can be a full zone name, an alias, an abbreviation, or an offset.

🏗️ DESIGN ISSUES

• Why not use existing zoneinfo files? – Not all OSes have them accessible, and formats vary. Including data directly bypasses bugs and dependencies.
• Why not use native tzdata files? – For speed. Parsing tzdata files is complex; storing data in Perl modules avoids runtime parsing.
• Why store information in so many files? – Performance: only necessary data is loaded. The Linux zoneinfo directory has over 1700 files; this approach is similar.
• Disk space seems excessive? – Currently ~9 MB vs ~4 MB for binary zoneinfo. Text format is larger but provides documentation and testability. Not considered excessive.

⚠️ KNOWN PROBLEMS OR ISSUES

• Unable to determine Time Zone – If initialization fails, the script exits with "Unable to determine Time Zone". Refer to DETERMINING THE SYSTEM TIME ZONE. Report such cases for improvement.
• Asia/Jerusalem time zone – Uses Hebrew calendar for DST rules. Supports only up to year 2037 (current zoneinfo data). Do not use for distant future dates.
• LMT and zzz abbreviations – Used for pre-Gregorian times or undefined periods. These are ignored in parsing and treated as local time zone.

🐛 KNOWN BUGS

None known.

❓ BUGS AND QUESTIONS

Please refer to the Date::Manip::Problems documentation for information on submitting bug reports or questions to the author.

👁️ SEE ALSO

Date::Manip - main module documentation

📜 LICENSE

This script is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

👤 AUTHOR

Sullivan Beck (sbeck@cpan.org)

perl v5.32.1 2021-11-20 Date::Manip::TZ(3pm)

📛 NAME 🚀 Quick Reference 📋 SYNOPSIS 📖 DESCRIPTION ⚙️ METHODS 🕐 TIME ZONE INFORMATION IN DATE::MANIP 🔍 DETERMINING THE SYSTEM TIME ZONE 🏗️ DESIGN ISSUES ⚠️ KNOWN PROBLEMS OR ISSUES 🐛 KNOWN BUGS ❓ BUGS AND QUESTIONS 👁️ SEE ALSO 📜 LICENSE 👤 AUTHOR