tzinfo 0.2.2 → 0.3.0

data/CHANGES

@@ -1,172 +1,222 @@
-== Version 0.2.2 (tzdata v2006g) - 17-May-2006
-
-* Use class-scoped instance variables to store the Timezone identifier and 
-  singleton instance. Loading a linked zone no longer causes the parent
-  zone's identifier to be changed. The instance method of a linked zone class
-  also now returns an instance of the linked zone class rather than the parent
-  class. Closes #4502.
-* The zdumptest utility now compares the TZInfo zone identifier with the zdump
-  zone identifier.
-* The zdumptestall utility now exits if not supplied with enough parameters.
-* Updated to tzdata version 2006g
-  (http://article.gmane.org/gmane.comp.time.tz/1008).
-
-
-== Version 0.2.1 (tzdata v2006d) - 17-Apr-2006
-
-* Fix a performance issue caused in 0.2.0 with Timezone.local_to_utc. 
-  Conversions performed on TimeOrDateTime instances passed to <=> are now
-  cached as originally intended. Thanks to Michael Smedberg for spotting this.
-* Fix a performance issue with the local_to_utc period search algorithm 
-  originally implemented in 0.1.0. The condition that was supposed to cause
-  the search to terminate when enough periods had been found was only being
-  evaluated in a small subset of cases. Thanks to Michael Smedberg and 
-  Jamis Buck for reporting this.
-* Added abbreviation as an alias for TimezonePeriod.zone_identifier.
-* Updated to tzdata version 2006d
-  (http://article.gmane.org/gmane.comp.time.tz/936).
-* Ignore any offset in DateTimes passed in (as is already done for Times).
-  All of the following now refer to the same UTC time (15:40 on 17 April 2006). 
-  Previously, the DateTime in the second line would have been interpreted 
-  as 20:40.
-  
-    tz.utc_to_local(DateTime.new(2006, 4, 17, 15, 40, 0))
-    tz.utc_to_local(DateTime.new(2006, 4, 17, 15, 40, 0).new_offset(Rational(5, 24)))
-    tz.utc_to_local(Time.utc(2006, 4, 17, 15, 40, 0))
-    tz.utc_to_local(Time.local(2006, 4, 17, 15, 40, 0))
-
-
-== Version 0.2.0 (tzdata v2006c) - 3-Apr-2006
-
-* Use timestamps rather than DateTime objects in zone files for times between
-  1970 and 2037 (the range of Time).
-* Don't convert passed in Time objects to DateTime in most cases (provides 
-  a substantial performance improvement).
-* Allow integer timestamps (time in seconds since 1970-1-1) to be used as well 
-  as Time and DateTime objects in all public methods that take times as 
-  parameters.
-* Tool to compare TZInfo conversions with output from zdump.
-* TZDataParser zone generation algorithm rewritten. Now based on the zic code.
-  TZInfo is now 100% compatible with zic/zdump output.
-* Riyadh Solar Time zones now included again (generation time has been reduced
-  with TZDataParser changes).
-* Use binary mode when writing zone and country files to get Unix (\n) new
-  lines.
-* Omit unnecessary quotes in zone identifier symbols.
-* Omit the final transition to DST if there is a prior transition in the last
-  year processed to standard time.
-* Updated to tzdata version 2006c
-  (http://article.gmane.org/gmane.comp.time.tz/920).
-
-
-== Version 0.1.2 (tzdata v2006a) - 5-Feb-2006
-
-* Add lib directory to the load path when tzinfo is required. Makes it easier
-  to use tzinfo gem when unpacked to vendor directory in rails. 
-* Updated to tzdata version 2006a 
-  (http://article.gmane.org/gmane.comp.time.tz/738).
-* build_tz_classes rake task now handles running svn add and svn delete as new 
-  timezones and countries are added and old ones are removed.
-* Return a better error when attempting to use a Timezone instance that was
-  constructed with Timezone.new(nil). This will occur when using Rails'
-  composed_of. When the timezone identifier in the database is null, attempting
-  to use the Timezone will now result in an UnknownTimezone exception rather 
-  than a NameError.
-
-
-== Version 0.1.1 (tzdata v2005q) - 18-Dec-2005
-
-* Timezones that are defined by a single unbounded period (e.g. UTC) now 
-  work again.
-* Updated to tzdata version 2005q.
-
-
-== Version 0.1.0 (tzdata v2005n) - 27-Nov-2005
-
-* period_for_local and local_to_utc now allow resolution of ambiguous
-  times (e.g. when switching from daylight savings to standard time). 
-  The behaviour of these methods when faced with an ambiguous local time
-  has now changed. If you are using these methods you should check
-  the documentation. Thanks to Cliff Matthews for suggesting this change.
-* Added require 'date' to timezone.rb (date isn't loaded by default in all
-  environments).
-* Use rake to build packages and documentation.
-* License file is now included in gem distribution.
-* Dates in definitions stored as Astronomical Julian Day numbers rather than
-  as civil dates (improves performance creating DateTime instances).
-* Added options to TZDataParser to allow generation of specific zones and
-  countries.
-* Moved TimezonePeriod class to timezone_period.rb.
-* New TimezonePeriodList class to store TimezonePeriods for a timezone and
-  perform searches for periods.
-* Timezones now defined using blocks. TimezonePeriods are only instantiated
-  when they are needed. Thanks to Jamis Buck for the suggestion.
-* Add options to TZDataParser to allow exclusion of specific zones and 
-  countries.
-* Exclude the Riyadh Solar Time zones. The rules are only for 1987 to 1989 and
-  take a long time to generate and process. Riyadh Solar Time is no longer
-  observed.
-* The last TimezonePeriod for each Timezone is now written out with an
-  unbounded rather than arbitrary end time.
-* Construct the Rational offset in TimezonePeriod once when the TimezonePeriod
-  is constructed rather than each time it is needed.
-* Timezone and Country now keep a cache of loaded instances to avoid running
-  require which can be slow on some platforms.
-* Updated to tzdata version 2005n.
-
-
-== Version 0.0.4 (tzdata v2005m) - 18-Sep-2005
-
-* Removed debug output accidentally included in the previous release.
-* Fixed a bug in the generation of friendly zone identifiers (was inserting
-  apostrophes into UTC, GMT, etc).
-* Fixed Country <=> operator (was comparing non-existent attribute)
-* Fixed Timezone.period_for_local error when period not found.
-* Added testcases for Timezone, TimezoneProxy, TimezonePeriod, Country and
-  some selected timezones.
-
-  
-== Version 0.0.3 (tzdata v2005m) - 17-Sep-2005
-
-* Reduced visibility of some methods added in Timezone#setup and Country#setup.
-* Added name method to Timezone (returns the identifier).
-* Added friendly_identifier method to Timezone. Returns a more friendly version
-  of the identifier.
-* Added to_s method to Timezone. Returns the friendly identifier.
-* Added == and <=> operators to Timezone (compares identifiers).
-* Timezone now includes Comparable.
-* Added to_s method to Country.
-* Added == and <=> operators to Country (compares ISO 3166 country codes).
-* Country now includes Comparable.
-* New TimezoneProxy class that behaves the same as a Timezone but doesn't
-  actually load in its definition until it is actually required.
-* Modified Timezone and Country methods that return Timezones to return
-  TimezoneProxy instances instead. This makes these methods much quicker.
-  
-  In Ruby on Rails, you can now show a drop-down list of all timezones using the
-  Rails time_zone_select helper method:
-  
-  <%= time_zone_select 'user', 'time_zone', TZInfo::Timezone.all.sort, :model => TZInfo::Timezone %>
-
-
-== Version 0.0.2 (tzdata v2005m) - 13-Sep-2005 
-
-* Country and Timezone data is now loaded into class rather than instance 
-  variables. This makes Timezone links more efficient and saves memory if
-  creating specific Timezone and Country classes directly.
-* TimezonePeriod zone_identifier is now defined as a symbol to save memory
-  (was previously a string).
-* TimezonePeriod zone_identifiers that were previously '' are now :Unknown.
-* Timezones and Countries can now be returned using Timezone.new(identifier)
-  and Country.new(identifier). When passed an identifier, the new method
-  calls get to return an instance of the specified timezone or country.
-* Added new class methods to Timezone to return sets of zones and identifiers.
-
-Thanks to Scott Barron of Lunchbox Software for the suggestions in his
-article about using TZInfo with Rails 
-(http://lunchroom.lunchboxsoftware.com/pages/tzinfo_rails)
-
-
-== Version 0.0.1 (tzdata v2005m) - 29-Aug-2005 
-
-* First release.
+== Version 0.3.0 (tzdata v2006g) - 17-Jul-2006
+
+* New timezone data format. Timezone data now occupies less space on disk and
+  takes less memory once loaded. #4142, #4144.
+* Timezone data is defined in modules rather than classes. Timezone instances 
+  returned by Timezone.get are no longer instances of data classes, but are
+  instead instances of new DataTimezone and LinkedTimezone classes.
+* Timezone instances can now be used with Marshal.dump and Marshal.load. #4240.
+* Added a Timezone.get_proxy method that returns a TimezoneProxy object for a 
+  given identifier.
+* Country index data is now defined in a single module that is independent
+  of the Country class implementation.
+* Country instances can now be used with Marshal.dump and Marshal.load. #4240.
+* Country has a new zone_info method that returns CountryTimezone objects
+  containing additional information (latitude, longitude and a description) 
+  relating to each Timezone. #4140.
+* Timezones within a Country are now returned in an order that makes 
+  geographic sense.
+* The zdumptest utility now checks local to utc conversions in addition to
+  utc to local conversions.
+* eql? method defined on Country and Timezone that is equivalent to ==.
+* == method of Timezone no longer raises an exception when passed an object
+  with no identifier method.
+* == method of Country no longer raises an exception when passed an object
+  with no code method.
+* hash method defined on Country that returns the hash of the code.
+* hash method defined on Timezone that returns the hash of the identifier.
+* Miscellaneous API documentation corrections and improvements.
+* Timezone definition and indexes are now excluded from rdoc (the contents were
+  previously ignored with #:nodoc: anyway).
+* Removed no longer needed #:nodoc: directives from timezone data files (which
+  are now excluded from the rdoc build).
+* Installation of the gem now causes rdoc API documentation to be generated. 
+  #4905.
+* When optimizing transitions to generate zone definitions, check the
+  UTC and standard offsets separately rather than just the total offset to UTC.
+  Fixes an incorrect abbreviation issue with Europe/London, Europe/Dublin and 
+  Pacific/Auckland.
+* Eliminated unnecessary .nil? calls to give a minor performance gain.
+* Timezone.all and Timezone.all_identifiers now return all the 
+  Timezones/identifiers rather than just those associated with countries. #4146.
+* Added all_data_zones, all_data_zone_identifiers, all_linked_zones and
+  all_linked_zone_identifiers class methods to Timezone.
+* Added a strftime method to Timezone that converts a time in UTC to local
+  time and then returns it formatted. %Z is replaced with the Timezone 
+  abbreviation for the given time (for example, EST or EDT). #4143.
+* Fix escaping of quotes in TZDataParser. This affected country names and
+  descriptions of timezones within countries.
+
+
+== Version 0.2.2 (tzdata v2006g) - 17-May-2006
+
+* Use class-scoped instance variables to store the Timezone identifier and 
+  singleton instance. Loading a linked zone no longer causes the parent
+  zone's identifier to be changed. The instance method of a linked zone class
+  also now returns an instance of the linked zone class rather than the parent
+  class. #4502.
+* The zdumptest utility now compares the TZInfo zone identifier with the zdump
+  zone identifier.
+* The zdumptestall utility now exits if not supplied with enough parameters.
+* Updated to tzdata version 2006g
+  (http://article.gmane.org/gmane.comp.time.tz/1008).
+
+
+== Version 0.2.1 (tzdata v2006d) - 17-Apr-2006
+
+* Fix a performance issue caused in 0.2.0 with Timezone.local_to_utc. 
+  Conversions performed on TimeOrDateTime instances passed to <=> are now
+  cached as originally intended. Thanks to Michael Smedberg for spotting this.
+* Fix a performance issue with the local_to_utc period search algorithm 
+  originally implemented in 0.1.0. The condition that was supposed to cause
+  the search to terminate when enough periods had been found was only being
+  evaluated in a small subset of cases. Thanks to Michael Smedberg and 
+  Jamis Buck for reporting this.
+* Added abbreviation as an alias for TimezonePeriod.zone_identifier.
+* Updated to tzdata version 2006d
+  (http://article.gmane.org/gmane.comp.time.tz/936).
+* Ignore any offset in DateTimes passed in (as is already done for Times).
+  All of the following now refer to the same UTC time (15:40 on 17 April 2006). 
+  Previously, the DateTime in the second line would have been interpreted 
+  as 20:40.
+  
+    tz.utc_to_local(DateTime.new(2006, 4, 17, 15, 40, 0))
+    tz.utc_to_local(DateTime.new(2006, 4, 17, 15, 40, 0).new_offset(Rational(5, 24)))
+    tz.utc_to_local(Time.utc(2006, 4, 17, 15, 40, 0))
+    tz.utc_to_local(Time.local(2006, 4, 17, 15, 40, 0))
+
+
+== Version 0.2.0 (tzdata v2006c) - 3-Apr-2006
+
+* Use timestamps rather than DateTime objects in zone files for times between
+  1970 and 2037 (the range of Time).
+* Don't convert passed in Time objects to DateTime in most cases (provides 
+  a substantial performance improvement).
+* Allow integer timestamps (time in seconds since 1970-1-1) to be used as well 
+  as Time and DateTime objects in all public methods that take times as 
+  parameters.
+* Tool to compare TZInfo conversions with output from zdump.
+* TZDataParser zone generation algorithm rewritten. Now based on the zic code.
+  TZInfo is now 100% compatible with zic/zdump output.
+* Riyadh Solar Time zones now included again (generation time has been reduced
+  with TZDataParser changes).
+* Use binary mode when writing zone and country files to get Unix (\n) new
+  lines.
+* Omit unnecessary quotes in zone identifier symbols.
+* Omit the final transition to DST if there is a prior transition in the last
+  year processed to standard time.
+* Updated to tzdata version 2006c
+  (http://article.gmane.org/gmane.comp.time.tz/920).
+
+
+== Version 0.1.2 (tzdata v2006a) - 5-Feb-2006
+
+* Add lib directory to the load path when tzinfo is required. Makes it easier
+  to use tzinfo gem when unpacked to vendor directory in rails. 
+* Updated to tzdata version 2006a 
+  (http://article.gmane.org/gmane.comp.time.tz/738).
+* build_tz_classes rake task now handles running svn add and svn delete as new 
+  timezones and countries are added and old ones are removed.
+* Return a better error when attempting to use a Timezone instance that was
+  constructed with Timezone.new(nil). This will occur when using Rails'
+  composed_of. When the timezone identifier in the database is null, attempting
+  to use the Timezone will now result in an UnknownTimezone exception rather 
+  than a NameError.
+
+
+== Version 0.1.1 (tzdata v2005q) - 18-Dec-2005
+
+* Timezones that are defined by a single unbounded period (e.g. UTC) now 
+  work again.
+* Updated to tzdata version 2005q.
+
+
+== Version 0.1.0 (tzdata v2005n) - 27-Nov-2005
+
+* period_for_local and local_to_utc now allow resolution of ambiguous
+  times (e.g. when switching from daylight savings to standard time). 
+  The behaviour of these methods when faced with an ambiguous local time
+  has now changed. If you are using these methods you should check
+  the documentation. Thanks to Cliff Matthews for suggesting this change.
+* Added require 'date' to timezone.rb (date isn't loaded by default in all
+  environments).
+* Use rake to build packages and documentation.
+* License file is now included in gem distribution.
+* Dates in definitions stored as Astronomical Julian Day numbers rather than
+  as civil dates (improves performance creating DateTime instances).
+* Added options to TZDataParser to allow generation of specific zones and
+  countries.
+* Moved TimezonePeriod class to timezone_period.rb.
+* New TimezonePeriodList class to store TimezonePeriods for a timezone and
+  perform searches for periods.
+* Timezones now defined using blocks. TimezonePeriods are only instantiated
+  when they are needed. Thanks to Jamis Buck for the suggestion.
+* Add options to TZDataParser to allow exclusion of specific zones and 
+  countries.
+* Exclude the Riyadh Solar Time zones. The rules are only for 1987 to 1989 and
+  take a long time to generate and process. Riyadh Solar Time is no longer
+  observed.
+* The last TimezonePeriod for each Timezone is now written out with an
+  unbounded rather than arbitrary end time.
+* Construct the Rational offset in TimezonePeriod once when the TimezonePeriod
+  is constructed rather than each time it is needed.
+* Timezone and Country now keep a cache of loaded instances to avoid running
+  require which can be slow on some platforms.
+* Updated to tzdata version 2005n.
+
+
+== Version 0.0.4 (tzdata v2005m) - 18-Sep-2005
+
+* Removed debug output accidentally included in the previous release.
+* Fixed a bug in the generation of friendly zone identifiers (was inserting
+  apostrophes into UTC, GMT, etc).
+* Fixed Country <=> operator (was comparing non-existent attribute)
+* Fixed Timezone.period_for_local error when period not found.
+* Added testcases for Timezone, TimezoneProxy, TimezonePeriod, Country and
+  some selected timezones.
+
+  
+== Version 0.0.3 (tzdata v2005m) - 17-Sep-2005
+
+* Reduced visibility of some methods added in Timezone#setup and Country#setup.
+* Added name method to Timezone (returns the identifier).
+* Added friendly_identifier method to Timezone. Returns a more friendly version
+  of the identifier.
+* Added to_s method to Timezone. Returns the friendly identifier.
+* Added == and <=> operators to Timezone (compares identifiers).
+* Timezone now includes Comparable.
+* Added to_s method to Country.
+* Added == and <=> operators to Country (compares ISO 3166 country codes).
+* Country now includes Comparable.
+* New TimezoneProxy class that behaves the same as a Timezone but doesn't
+  actually load in its definition until it is actually required.
+* Modified Timezone and Country methods that return Timezones to return
+  TimezoneProxy instances instead. This makes these methods much quicker.
+  
+  In Ruby on Rails, you can now show a drop-down list of all timezones using the
+  Rails time_zone_select helper method:
+  
+  <%= time_zone_select 'user', 'time_zone', TZInfo::Timezone.all.sort, :model => TZInfo::Timezone %>
+
+
+== Version 0.0.2 (tzdata v2005m) - 13-Sep-2005 
+
+* Country and Timezone data is now loaded into class rather than instance 
+  variables. This makes Timezone links more efficient and saves memory if
+  creating specific Timezone and Country classes directly.
+* TimezonePeriod zone_identifier is now defined as a symbol to save memory
+  (was previously a string).
+* TimezonePeriod zone_identifiers that were previously '' are now :Unknown.
+* Timezones and Countries can now be returned using Timezone.new(identifier)
+  and Country.new(identifier). When passed an identifier, the new method
+  calls get to return an instance of the specified timezone or country.
+* Added new class methods to Timezone to return sets of zones and identifiers.
+
+Thanks to Scott Barron of Lunchbox Software for the suggestions in his
+article about using TZInfo with Rails 
+(http://lunchroom.lunchboxsoftware.com/pages/tzinfo_rails)
+
+
+== Version 0.0.1 (tzdata v2005m) - 29-Aug-2005 
+
+* First release.

data/README

@@ -6,23 +6,34 @@ daylight-savings aware transformations between times in different timezones.
 This is the same database as used for zoneinfo on Unix machines.
 
 The tz database has been imported (using TZDataParser) and turned into a set of
-Ruby classes (which are packaged with this release).
+Ruby modules (which are packaged with this release).
 
 
 == Example usage
 
-To convert a time in UTC, to a local time in the America/New_York timezone, you
+To convert a time in UTC to a local time in the America/New_York timezone, you
 can do the following:
 
   require_gem 'tzinfo'
   include TZInfo
   
   tz = Timezone.get('America/New_York')
-  local = tz.utc_to_local(DateTime.new(2005,8,29,15,35,0))
+  local = tz.utc_to_local(Time.utc(2005,8,29,15,35,0))
+
+Note that the Time returned will look like it is UTC (Time.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:
+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.
@@ -39,6 +50,9 @@ passed.
 You can get the current local time in a Timezone 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.
   
 You can also access Timezones by Country (ISO 3166 country code). The following 
 gets all the Timezone identifiers for the US:
@@ -46,6 +60,9 @@ gets all the Timezone identifiers for the US:
   us = Country.get('US')
   timezones = us.zone_identifiers
   
+The zone_info method of Country provides an additional description and
+location for each Timezone in the Country.
+  
 The above covers the most common uses of Timezone and Country. For more detail,
 see the API documentation for the individual classes.