perldoc > Date::Manip::TZ

man perldoc info pydoc3 ri search

📛 NAME

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

🚀 Quick Reference

Use Case	Command	Description
Convert date between timezones	$tz->convert($date, $from, $to)	Convert a date from one time zone to another
Convert date to GMT	$tz->convert_to_gmt($date, $from)	Convert a date to GMT
Convert from GMT	$tz->convert_from_gmt($date, $to)	Convert a date from GMT to another time zone
Convert to local time	$tz->convert_to_local($date, $from)	Convert a date to the local time zone
Convert from local time	$tz->convert_from_local($date, $to)	Convert a date from the local time zone
Get current system time zone	$tz->curr_zone()	Return the system time zone
List all periods for a zone in a year	$tz->periods($zone, $year)	Return all time zone periods starting in a given year
Get period for a specific date	$tz->date_period($date, $zone, $wall_clock)	Return period information for a given date
Define abbreviation preferences	$tz->define_abbrev($abbrev, @zone)	Set order of zones to check for an abbreviation
Define alias	$tz->define_alias($alias, $zone)	Define a new alias or override an existing one
Define offset preferences	$tz->define_offset($offset, $dstflag, @zone)	Set order of zones to check for an offset
Find matching zones	$tz->zone(@args)	Return a list of zones matching criteria
Change current zone detection methods	$tz->curr_zone_methods(@methods)	Override the list of methods used to detect 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 (but are not required to have) one or more aliases. Each alias is unique, and is not the same as any time zone name. An alias can be used in exactly the same way as 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. The times are included both as an absolute GMT time, and as a wall clock time. The wall clock start time is the time that will be on a clock just as the period starts (i.e. after a time change). The wall clock end time is the time on a clock immediately before the period ends.
  • 📏 offset – The entire period has an offset which is how much the wall clock time differs from GMT.
  • 📛 abbreviation – When expressing the time period, an abbreviation (such as EST) is typically used.
  • ☀️ daylight saving time flag – Every period is categorized as a standard time or a daylight saving time. The flag will be 1 if it is a daylight saving time, or 0 if it is a 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/

Additional data from other standards are also used.

The zoneinfo database is not necessary in order to use Date::Manip. Instead, all of that data has been extracted and stored in a series of other modules which are used to handle each time zone. In that way, Date::Manip has no dependency on any other source of data.

The Date::Manip::Zones document contains detailed information on the data available.

⚙️ METHODS

In all methods, the following variables are used:

• 🏷️ $zone – a string which contains a valid time zone name. For example: America/New_York
• 🔗 $alias – a string which contains a valid time zone name, or a valid time zone alias. For example: America/New_York, US/Eastern, EST5EDT
• 📛 $abbrev – a string containing a valid time zone abbreviation. For example: EST
• 📏 $offset – a time zone entered as an offset. Can be a string of formats +HH, +HHMM, +HHMMSS, +HH:MM, +HH:MM:SS or a list reference [HH,MM,SS].
• ☀️ $dstflag – one of: std, stdonly, dst, dstonly. Defaults to std. Controls preference for standard vs. daylight saving time.
• 📅 $date – a string containing a date in formats: YYYYMMDDHH:MN:SS, YYYY-MM-DD-HH:MN:SS, YYYYMMDDHHMNSS, or a list reference [Y,M,D,H,MN,S].
• 🔘 $isdst – 0 if a date is in standard time, 1 if in daylight saving time.
• 📦 $period – a list reference containing: [ $dateUT, $dateLT, $offsetstr, $offset, $abbrev, $isdst, $endUT, $endLT, $begUTs, $begLTs, $endUTs, $endLTs ]. Details described in the periods method.

The following methods are available:

• base
  config
  err
  new
  new_config

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

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

  This returns the description of all time zone periods that occur (in full or in part) during the given year. The year is measured in universal (GMT) time.

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

  Converts a date in the time zone given by $from to the time zone given by $to.

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

  Converts a date to GMT. If $from is given, it is the current time zone of the date. If omitted, defaults to the local time zone.

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

  Converts a date from GMT to another time zone. If $to is given, the date is converted to that time zone. Otherwise, it is converted to the 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 the convert_to_gmt and convert_from_gmt functions. If $from or $to are omitted, they default to GMT.

  If there is any ambiguity about whether $date is in DST, the $isdst option can be passed in (0 or 1) to specify which time to use.

  Error codes:

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

• $tz->curr_zone();

  Returns the system time zone. Determined using methods described in "DETERMINING THE SYSTEM TIME ZONE".

  $tz->curr_zone(1);

  Clears the system time zone and re-determines it.

• $tz->curr_zone_methods(@methods);

  Sets the list and order of methods to use in determining the local time zone. See "DETERMINING THE SYSTEM TIME ZONE" for available methods. This method may not be used in taint-checked environments (will warn but not change).

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

  Returns the period information for the given date. $date defaults to GMT, but may be given as local (wall clock) time if $wall_clock is non-zero. If the wall clock time doesn't appear (skipped) or appears twice (repeated), the $isdst variable is used to disambiguate.

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

  Sets the list of zones to check when encountering an abbreviation, and the order in which they are checked. If $abbrev is "reset", all abbreviations are reset to standard values. If @zone includes only 'reset', the default list for $abbrev is restored.

  Error codes:

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

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

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

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

  Similar to define_abbrev. Sets the order of zones to check when an offset is encountered. $dstflag can restrict to standard or daylight saving only.

  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 using dstonly or stdonly)
  • 3 – A zone (returned as $val) is not a valid time zone
  • 4 – A zone does not use the offset
  • 5 – A zone does not include the offset in the selected time
  • 9 – Offset is not a valid offset

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

  Returns the description of all time zone periods that begin during the given year (GMT). If no period starts, nothing is returned.

  @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 all periods that begin in any year from $year0 to $year1.

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

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

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

  Returns a list of all zones (or the default zone) that match all supplied information. In scalar context, returns the default zone; in list context, returns all zones.

  @args may include any of: a zone name/alias ($alias), abbreviation ($abbrev), offset ($offset), dstflag ($dstflag), date ($date). It is NOT valid to include two of any item.

  If an error occurs, undef is returned. If no zone matches, an empty string or empty list is returned.

  Order of zones: if $abbrev is given, that determines order (standard times first, then saving, unless $dstflag is "dst"). If $abbrev not given but $offset is, $offset determines order similarly. If $date is given, only zones where that date appears (as wall clock) are returned.

  Note: when working with a timezone expressed as an offset and a date is passed in, the default $dstflag is "dst" (not "std") because standard offsets always match a standard timezone.

🕐 TIME ZONE INFORMATION IN DATE::MANIP

Date::Manip makes use of three potentially different time zones when working with a date:

• 🏠 Local time zone – The actual time zone the computer is running in.
• 💼 Working time zone – The default time zone for operations; usually the local time zone, but can be changed with SetDate or ForceDate config variables.
• 📅 Parsed time zone – The time zone explicitly specified in a date string. If absent, defaults to the working time zone.

The local time zone is determined using the methods described in the next section. The working time zone can be changed via config variables (see Date::Manip::Config).

🔍 DETERMINING THE SYSTEM TIME ZONE

There are many ways to determine the time zone. A list of methods to use is provided by default, and may be overridden by the curr_zone_methods function. The following methods are available:

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

Note: The main and env methods should only be used to specify the actual system time zone. Use SetDate and ForceDate config variables to specify an alternate working time zone.

Default methods for Unix systems:

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 systems:

main     TZ
env      zone TZ
registry
gmtoff

Default methods for VMS systems:

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 all other systems:

main     TZ
env      zone TZ
gmtoff

The value returned from any method may be a full time zone name (e.g. America/New_York), an alias, an abbreviation (e.g. EDT), or an offset (+hh, +hhmn, +hh:mm, +hh:mm:ss) from GMT.

💡 DESIGN ISSUES

The design decisions made in writing this module may cause some questions. The time zone modules are all generated using scripts that parse the standard tzdata files and store information in perl modules.

Why not use existing zoneinfo files?

Some may think I should have written an interface to the zoneinfo files distributed with most operating systems. I rejected the idea because:

• Not all operating systems come with zoneinfo databases in a user-accessible state (e.g. Microsoft).
• I encountered a bug in Solaris zoneinfo tools and decided I didn't want to depend on an implementation where I could not control and fix bugs.

Why not use the native tzdata files directly?

I parse the tzdata files and store the data in perl modules instead of creating an interface to the tzdata files directly. This was done for speed — Date::Manip is already slow, and complex parsing of tzdata files would slow it further. By storing data in modules, little or no parsing is done at runtime.

Why store information in so many files?

The data is stored in almost 500 Date::Manip::Offset::* modules and almost 450 Date::Manip::TZ::* modules. This is similar to the /usr/share/zoneinfo directory which contains over 1700 files. The modules are loaded only when the time zone or offset is actually used, so only a small number are loaded in most applications.

The disk space seems excessive?

Currently, the perl files use about 9 MB, while /usr/share/zoneinfo uses about 4 MB. The difference is due to the binary format of zoneinfo vs. plain text in perl modules. The modules include pod documentation, which is useful but adds space. Disk usage is not considered excessive.

⚠️ KNOWN PROBLEMS OR ISSUES

Unable to determine Time Zone

When Date::Manip is initialized, it must determine the local time zone. If it fails, an error "Unable to determine Time Zone" occurs and the script exits. This is less common with release 6.00. Refer to the "DETERMINING THE SYSTEM TIME ZONE" section for help.

Asia/Jerusalem time zone

The Asia/Jerusalem time zone uses a non-standard way of specifying DST based on the Hebrew calendar. This module supports all time zone changes currently specified in the zoneinfo database (up to year 2037) but does not attempt to handle changes beyond that date. Do not use Date::Manip for Jerusalem dates far in the future.

LMT and zzz abbreviations

Both LMT and zzz abbreviations are used in zoneinfo databases. LMT is used for most time zones before the Gregorian calendar was adopted, and zzz for a few others. Both are ignored in parsing dates (because there is no reasonable way to determine which zone they refer to) and will be treated as the 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 AT cpan.org)

📛 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