Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
DateTime::TimeZone::AlUser3Contributed Perl DocumeDateTime::TimeZone::Alias(3)

NAME
       DateTime::TimeZone::Alias - Create aliases for DateTime timezones

SYNOPSIS
	   use DateTime::TimeZone::Alias Hawaii	=> 'Pacific/Honolulu',
					 EST =>	'Australia/Melbourne';

	   or

	   DateTime::TimeZone::Alias->add( Fun => 'America/Tijuana', %hash );

	   or

	   DateTime::TimeZone::Alias->set( Pain	=> 'America/Dawson_Creek', %hash );
	   DateTime::TimeZone::Alias->set( boat	=> 'floating' );
	   DateTime::TimeZone::Alias->set( home	=> 'local' );
	   DateTime::TimeZone::Alias->set( lulu	=> 'Z' );
	   DateTime::TimeZone::Alias->set( cut => 'UTC'	);
	   DateTime::TimeZone::Alias->set( nowhere => '-09:30' );

	   or

	   DateTime::TimeZone::Alias->remove( qw( Hawaii EST Pain Fun )	);

	   or

	   DateTime::TimeZone::Alias->value( 'EST' );

	   or

	   DateTime::TimeZone::Alias->is_defined( 'Hawaii' )
	   DateTime::TimeZone::Alias->is_alias(	'EST' )
	   DateTime::TimeZone::Alias->is_timezone( 'Antarctica/Vostok' )

	   or

	   DateTime::TimeZone::Alias->aliases
	   DateTime::TimeZone::Alias->timezones

DESCRIPTION
       Creates and destroys aliases for	DateTime timezones.  This module
       violates	the encapsulation of the DateTime internals.  User _Beware_.

IMPORT PARAMETERS
       Accepts a hash representing an alias and	the timezone it	should map
       too.  Import has	the exact same behaviors as the	"set" method.

METHODS
       o   set(	alias => timezone, ... )

	   Accepts a hash representing an alias	and the	timezone it should map
	   too.	 If an invalid timezone	value or no parameters are passed an
	   exception is	thrown.	 It is possible	to create an alias to another
	   alias.  This	method will redefine an	existing alias or add a	new
	   alias that overrides	an existing timezone.

	   What	may be aliased:

	       aliases
	       floating
	       local
	       OffsetOnly
	       Olson time zones
	       UTC
	       Z

       o   add(	alias => timezone, ... )

	   Accepts a hash representing an alias	and the	timezone it should map
	   too.	 If an invalid timezone	value or no parameters are passed an
	   exception is	thrown.	 It is possible	to create an alias to another
	   alias.  This	method will _not_ redefine an existing alias or	allow
	   you remap a timezone.  For redefinitions see	the "set" method.

       o   remove( alias, ... )

	   Accepts a list of aliases to	be removed.  If	an the name of an
	   aliases that	doesn't	exist is passed	in then	an exception is
	   thrown.  It's important to note that	you can	remove aliases but not
	   timezones.  However,	a redefined timezone is	actually an alias and
	   can be removed.

       o   value( $str )

	   If $str is a	known alias then the timezone being aliased is
	   returned, otherwise undef.

       o   is_defined( $str )

	   If $str is a	known timezone or alias	this method returns 1,
	   otherwise undef is returned.

       o   is_alias( $str )

	   If $str is a	known alias this method	returns	1, otherwise undef is
	   returned.

       o   is_timezone(	$str )

	   If $str is a	known timezone this method returns 1, otherwise	undef
	   is returned.

       o   aliases

	   In list context a hash of all known aliases and their values	is
	   returned.  In scalar	context	a reference to a hash is returned.

       o   timezones

	   In list context an array of all known timezones is returned.	 In
	   scalar context a reference to an array is returned.

GOTCHAS
   Import
       Multiple	"use DateTime::TimeZone::Alias"	statements in the same package
       may not have the	desired	result if attempting to	redefine existing
       aliases.	 If you	want to	redefine an alias use the "set"	method
       instead.

   Aliasing
       You can _not_ create circular aliases.  E.g.

	   # TSH actually points to value of HST - 'Pacific/Honolulu'
	   # if	HST wasn't already defined this	would be an exception
	   DateTime::TimeZone::Alias->set( TSH => HST );

	   # HST still points to 'Pacific/Honolulu'
	   DateTime::TimeZone::Alias->set( HST => TSH );

       Sorry - no evil here, move along.

   Global Behavior
       It's important to remember that aliases are global in scope. E.g.

	   package Foo;

	   DateTime::TimeZone::Alias->set( EST => 'US/Eastern' );

	   Bar->bar();

	   # this will fail because EST	is no longer defined
	   my $dt = DateTime->now( time_zone =>	'EST' );

	   package Bar;

	   sub bar {
	       DateTime::TimeZone::Alias->set( EST => 'US/Eastern' );
	       .
	       .

	       DateTime::TimeZone::Alias->remove( qw( EST ) );
	   }

       There are many possible ways to avoid this trap.	 The best solution is
       to simply not write code	like this.  If you insist on this style	then
       you can try one of the suggested	work arounds.

       Poor Man's DateTime::TimeZone::Alias

       Sometimes DateTime::TimeZone::Alias may not be the best solution	to
       your problem.  Particularly if your in an environment that has poor
       "sand-boxing" such as "mod_perl".  E.g.

	   use constant	EST => 'US/Eastern';

	   or

	   sub EST () {	'US/Eastern' }
	   .
	   .

	   my $dt = DateTime->new( %params, time_zone => EST );

       store/restore

       This probably isn't thread safe.	 E.g.

	   sub bar {
	       my $my_alias = DateTime::TimeZone::Alias->value(	'EST' );
	       DateTime::TimeZone::Alias->set( EST => 'US/Eastern' );
	       .
	       .

	       DateTime::TimeZone::Alias->set( EST => $my_alias	);
	   }

       If $my_alias is undefined then the "set"	will fail as an	alias must
       point to	a valid	timezone.

DEVELOPER NOTES
       The "aliases" and "timezones" methods preserve encapsulation by
       returning a reference to	a copy of the internal data structures instead
       of a direct reference.

CREDITS
       Ben Bennett (BBENNETT) for a bug	report,	some API suggestions,
       documentation suggestions, and being so darn enthusiastic.  (not
       necessary in that order)

       Everyone	at the DateTime	"Asylum".

SUPPORT
       Support for this	module is provided via the datetime@perl.org email
       list. See http://lists.perl.org/	for more details.

AUTHOR
       Joshua Hoblitt <jhoblitt@cpan.org>

COPYRIGHT
       Copyright (c) 2003-2010 Joshua Hoblitt.	All rights reserved.  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
       datetime@perl.org mailing list

       http://datetime.perl.org/

perl v5.24.1			  2017-07-02	  DateTime::TimeZone::Alias(3)

NAME | SYNOPSIS | DESCRIPTION | IMPORT PARAMETERS | METHODS | GOTCHAS | DEVELOPER NOTES | CREDITS | SUPPORT | AUTHOR | COPYRIGHT | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=DateTime::TimeZone::Alias&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help