NAME

DateTime::AATW - DateTime All Around The World

SYNOPSIS

use DateTime;
use DateTime::AATW;

my $dt = DateTime->now();
my $aatw = DateTime::AATW->new($dt);

### Return names of all time zones that are in hour '2' of the day
my $zone_names_for_hour_2_ref = $aatw->zone_names_for_hour(2);
my @zone_names_for_hour_2_ary = $aatw->zone_names_for_hour(2);

### Return DateTime::TimeZone objects of all time zones that are
### in hour '2' of the day
my $zones_for_hour_2_ref = $aatw->zones_for_hour(2);
my @zones_for_hour_2_ary = $aatw->zones_for_hour(2);

### Return names of all time zones that are in hours '2' and '5'
### of the day
my $zone_names_for_hours_2and5_ref = $aatw->zone_names_for_hours(2,5);
my @zone_names_for_hours_2and5_ary = $aatw->zone_names_for_hours(2,5);

### Return DateTime::TimeZone objets of all time zones that are in
### hours '2' and '5' of the day
my $zones_for_hours_2and5_ref = $aatw->zones_for_hours(2,5);
my @zones_for_hours_2and5_ary = $aatw->zones_for_hours(2,5);

### Return a DateTime object for a specific time zone
my $dt_for_NewYork = $aatw->dt_for_zone('America/New_York');
my $dt_for_Paris   = $aatw->dt_for_zone('Europe/Paris');

### Return a HASH mapping an hour in the day to an ARRAYREF
### of DateTime::TimeZone objects that are part of that hour.
my $hour_zones_map = $aatw->hour_zones_map();
my $hour_zones_map = $aatw->hour_zones_map(0,4,8,12,16);

### Return a HASH mapping an hour in the day to an ARRAYREF
### of time zone names that are part of that hour.
my $hour_zone_names_map = $aatw->hour_zones_map();
my $hour_zone_names_map = $aatw->hour_zones_map(0,4,8,12,16);

### Return a HASH mapping a DateTime string to an ARRAYREF
### of DateTime::TimeZone objects.
my $dt_zones_map = $aatw->dt_zones_map();
my $dt_zones_map = $aatw->dt_zones_map(0,4,8,12,16);

### Return a HASH mapping a DateTime string to an ARRAYREF
### of time zone names.
my $dt_zones_map = $aatw->dt_zones_map();
my $dt_zones_map = $aatw->dt_zones_map(0,4,8,12,16);

### Return a HASH mapping a zone name to it's current DateTime
### objct
my $zone_name_dt_map = $aatw->zone_name_dt_map();
my $zone_name_dt_map = $aatw->zone_name_dt_map(
                               'America/New_York',
                               'Europe/Paris', 
                               'Asia/Tokyo');

DESCRIPTION

This module intends to make it easy to find what time or hour it is for every time zone known to DateTime::TimeZone::Catalog and provide easy lookup functions for that data based on a single DateTime object.

The inital reason for creating this module grew from a need to run scheduled tasks on servers around the world from a single monitoring / administration server. Some information for example, needed to be collected on the 0,4,8,12,16,20 hours within that servers time zone. The script on the monitoring server could be kicked off every hour, calculate which time zones needed to be collected from, then collect information form servres only in those time zones.

Combining this module with DateTime::Event::Cron helps figure out which time zones need be operated on at a specific time and schedule.

CONSTRUCTOR

new($datetime_object)

Returns a DateTime::AATW object. A vaild DateTime object must be passed.

OBJECT METHODS

zones_for_hour(SCALAR | ARRAY | ARRAYREF)

Returns an ARRAY or ARRAYREF depending on context of DateTime::TimeZone objects for the requests hour(s). The requested hour(s) must be integers between 0 and 23.

If you create a DateTime::AATW object with a DateTime object based on UTC and call $aatw->zones_for_hour(2), the function will return all time zones that are in the second hour of the day based on that DateTime object.

zones_for_hours(SCALAR | ARRAY | ARRAYREF)

Alias for zones_for_hour

zone_names_for_hour(SCALAR | ARRAY | ARRAYREF)

Returns an ARRAY or ARRAYREF depending on context of time zone names for the requests hour(s). The requested hour(s) must be integers between 0 and 23.

zone_names_for_hours(SCALAR | ARRAY | ARRAYREF)

Alias for zone_names_for_hour

hour_zones_map(SCALAR | ARRAY | ARRAYREF)

Returns a HASHREF that maps an hour of the day to an ARRAYREF of DateTime::TimeZone objects. Hour(s) passed must be integers between 0 and 23.

With no parameters a map of all hours between 0 and 23 will be returned.

hour_zone_names_map(SCALAR | ARRAY | ARRAYREF)

Returns a HASHREF that maps an hour of the day to an ARRAYREF of time zone names. Hour(s) passed must be integers between 0 and 23.

With no parameters a map of all hours between 0 and 23 will be returned.

dt_zones_map(SCALAR | ARRAY | ARRAYREF)

Returns a HASHREF that maps a DateTime string to an ARRAYREF of DateTime::TimeZone objects.

Parameters must be valid DateTime objects

With no parameters a map of all DateTime strings will be returned.

dt_zone_names_map(SCALAR | ARRAY | ARRAYREF)

Returns a HASHREF that maps a DateTime string to an ARRAYREF of time zone names.

Parameters must be valid DateTime objects

With no parameters a map of all DateTime strings will be returned.

dt_for_zone(SCALAR | DateTime::TimeZone)

Returns a DateTime object.

Parameters must be a valid DateTime::TimeZone string or a valid DateTime::TimeZone object.

zone_name_dt_map(SCALAR | ARRAY | ARRAYREF)

Returns a HASHREF that maps a zone name to a DateTime object.

Parameters must be valid DateTime::TimeZone string(s) or a valid DateTime::TimeZone object(s).

With no parameters a map of all zone names is returned.

AUTHOR

Kevin C. McGrath
CPAN ID: KMCGRATH
kmcgrath@baknet.com

COPYRIGHT

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

The full text of the license can be found in the LICENSE file included with this module.

SEE ALSO

perl(1).