= TZInfo - Daylight-savings aware timezone support for Ruby

TZInfo[http://tzinfo.rubyforge.org] provides daylight-savings aware 
transformations between times in different timezones.


== Data Sources

TZInfo requires a source of timezone data. There are two built-in options:

1. The TZInfo::Data library (the tzinfo-data gem). TZInfo::Data contains a set 
   of Ruby modules that are generated from the {IANA Time Zone Database}[http://www.iana.org/time-zones].
2. A zoneinfo directory on your system. Most Unix-like systems include a 
   zoneinfo directory containing timezone definitions. These are also generated
   from the {IANA Time Zone Database}[http://www.iana.org/time-zones].

By default the TZInfo::Data source will be used. If TZInfo::Data is not
available (i.e. if require 'tzinfo/data' fails), then TZInfo will search for
a zoneinfo directory instead (using the paths specified in
TZInfo::ZoneinfoDataSource::DEFAULT_SEARCH_PATHS).

If no data source can be found, a TZInfo::DataSourceNotFound exception will be
raised when using TZInfo.

The default data source selection can be overridden using 
TZInfo::DataSource.set.


== Installation

TZInfo can be installed using the gem command:

  $ gem install tzinfo

To use the Ruby modules as the data source, you'll also need to install
TZInfo::Data:

  $ gem install tzinfo-data
  

== Download

Tar, Zip and RubyGem packages of TZInfo can be downloaded from:

* http://rubyforge.org/frs/?group_id=894


== Example usage

The following code will obtain the America/New_York timezone and covert a time
in UTC to local New York time:

  require 'tzinfo'
  
  tz = TZInfo::Timezone.get('America/New_York')
  local = tz.utc_to_local(Time.utc(2005,8,29,15,35,0))

Note that the Time returned will look like it is UTC (local.zone will return 
"UTC"). This is because it is not currently possible to change the offset of 
an individual Time instance.
  
To convert from a local time to UTC, the local_to_utc method can be used. 

  utc = tz.local_to_utc(local)

Note that the timezone information of the time you pass in is ignored. The
following two lines will return the same result regardless of the local 
timezone:

  tz.local_to_utc(Time.local(2006,6,26,1,0,0))
  tz.local_to_utc(Time.utc(2006,6,26,1,0,0))
  
To get information about the rules in force at a particular UTC or local time,
the Timezone.period_for_utc and Timezone.period_for_local methods can be used.
Both of these methods return TimezonePeriod objects. The following gets the 
identifier for the period (in this case EDT).

  period = tz.period_for_utc(Time.utc(2005,8,29,15,35,0))
  id = period.zone_identifier
  
The current local time in a Timezone can be obtained with the Timezone#now
method:

  now = tz.now

All methods in TZInfo that take a time can be used with either Time, DateTime
or Integers (Time#to_i). The return type will be the same as the type passed in.
  
Timezones can also be accessed by Country (using an ISO 3166 country code). The
following gets all the Timezone identifiers for the US:

  us = TZInfo::Country.get('US')
  timezones = us.zone_identifiers
  
The Country#zone_info method provides an additional description and geographic 
location for each Timezone in the Country.
  
The above covers the most common uses TZInfo. For more detail, please refer to
the API documentation for the Timezone and Country classes.


== Documentation

API documentation can be found at 

* http://tzinfo.rubyforge.org/doc/


== License

TZInfo is released under the MIT license, see LICENSE for details.


== Support

Please post to the {TZInfo Users mailing list}[http://rubyforge.org/mailman/listinfo/tzinfo-users]
if you require assistance or have any suggestions.

Alternatively, you can contact the author Philip Ross directly at phil.ross@gmail.com.