Class: TZInfo::ZoneinfoDataSource

Inherits:
DataSource show all
Defined in:
lib/tzinfo/zoneinfo_data_source.rb

Overview

A DataSource that loads data from a ‘zoneinfo’ directory containing compiled “TZif” version 3 (or earlier) files in addition to iso3166.tab and zone1970.tab or zone.tab index files.

To have TZInfo load the system zoneinfo files, call TZInfo::DataSource.set as follows:

TZInfo::DataSource.set(:zoneinfo)

To load zoneinfo files from a particular directory, pass the directory to TZInfo::DataSource.set:

TZInfo::DataSource.set(:zoneinfo, directory)

Note that the platform used at runtime may limit the range of available transition data that can be loaded from zoneinfo files. There are two factors to consider:

First of all, the zoneinfo support in TZInfo makes use of Ruby’s Time class. On 32-bit builds of Ruby 1.8, the Time class only supports 32-bit timestamps. This means that only Times between 1901-12-13 20:45:52 and 2038-01-19 03:14:07 can be represented. Furthermore, certain platforms only allow for positive 32-bit timestamps (notably Windows), making the earliest representable time 1970-01-01 00:00:00.

64-bit builds of Ruby 1.8 and all builds of Ruby 1.9 support 64-bit timestamps. This means that there is no practical restriction on the range of the Time class on these platforms.

TZInfo will only load transitions that fall within the supported range of the Time class. Any queries performed on times outside of this range may give inaccurate results.

The second factor concerns the zoneinfo files. Versions of the ‘zic’ tool (used to build zoneinfo files) that were released prior to February 2006 created zoneinfo files that used 32-bit integers for transition timestamps. Later versions of zic produce zoneinfo files that use 64-bit integers. If you have 32-bit zoneinfo files on your system, then any queries falling outside of the range 1901-12-13 20:45:52 to 2038-01-19 03:14:07 may be inaccurate.

Most modern platforms include 64-bit zoneinfo files. However, Mac OS X (up to at least 10.8.4) still uses 32-bit zoneinfo files.

To check whether your zoneinfo files contain 32-bit or 64-bit transition data, you can run the following code (substituting the identifier of the zone you want to test for zone_identifier):

TZInfo::DataSource.set(:zoneinfo)
dir = TZInfo::DataSource.get.zoneinfo_dir
File.open(File.join(dir, zone_identifier), 'r') {|f| f.read(5) }

If the last line returns “TZif\x00”, then you have a 32-bit zoneinfo file. If it returns “TZif2” or “TZif3” then you have a 64-bit zoneinfo file.

If you require support for 64-bit transitions, but are restricted to 32-bit zoneinfo support, then you may want to consider using TZInfo::RubyDataSource instead.

Constant Summary collapse

DEFAULT_SEARCH_PATH =

The default value of ZoneinfoDataSource.search_path.

['/usr/share/zoneinfo', '/usr/share/lib/zoneinfo', '/etc/zoneinfo'].freeze
DEFAULT_ALTERNATE_ISO3166_TAB_SEARCH_PATH =

The default value of ZoneinfoDataSource.alternate_iso3166_tab_search_path.

['/usr/share/misc/iso3166.tab', '/usr/share/misc/iso3166'].freeze
@@search_path =

Paths to be checked to find the system zoneinfo directory.

DEFAULT_SEARCH_PATH.dup
@@alternate_iso3166_tab_search_path =

Paths to possible alternate iso3166.tab files (used to locate the system-wide iso3166.tab files on FreeBSD and OpenBSD).

DEFAULT_ALTERNATE_ISO3166_TAB_SEARCH_PATH.dup

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods inherited from DataSource

get, set

Constructor Details

#initialize(zoneinfo_dir = nil, alternate_iso3166_tab_path = nil) ⇒ ZoneinfoDataSource

Creates a new ZoneinfoDataSource.

If zoneinfo_dir is specified, it will be checked and used as the source of zoneinfo files.

The directory must contain a file named iso3166.tab and a file named either zone1970.tab or zone.tab. These may either be included in the root of the directory or in a ‘tab’ sub-directory and named ‘country.tab’ and ‘zone_sun.tab’ respectively (as is the case on Solaris.

Additionally, the path to iso3166.tab can be overridden using the alternate_iso3166_tab_path parameter.

InvalidZoneinfoDirectory will be raised if the iso3166.tab and zone1970.tab or zone.tab files cannot be found using the zoneinfo_dir and alternate_iso3166_tab_path parameters.

If zoneinfo_dir is not specified or nil, the paths referenced in search_path are searched in order to find a valid zoneinfo directory (one that contains zone1970.tab or zone.tab and iso3166.tab files as above).

The paths referenced in alternate_iso3166_tab_search_path are also searched to find an iso3166.tab file if one of the searched zoneinfo directories doesn’t contain an iso3166.tab file.

If no valid directory can be found by searching, ZoneinfoDirectoryNotFound will be raised.



167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
 
# File 'lib/tzinfo/zoneinfo_data_source.rb', line 167

def initialize(zoneinfo_dir = nil, alternate_iso3166_tab_path = nil)
  if zoneinfo_dir
    iso3166_tab_path, zone_tab_path = validate_zoneinfo_dir(zoneinfo_dir, alternate_iso3166_tab_path)
  
    unless iso3166_tab_path && zone_tab_path
      raise InvalidZoneinfoDirectory, "#{zoneinfo_dir} is not a directory or doesn't contain a iso3166.tab file and a zone1970.tab or zone.tab file." 
    end
    
    @zoneinfo_dir = zoneinfo_dir
  else
    @zoneinfo_dir, iso3166_tab_path, zone_tab_path = find_zoneinfo_dir
    
    unless @zoneinfo_dir && iso3166_tab_path && zone_tab_path
      raise ZoneinfoDirectoryNotFound, "None of the paths included in TZInfo::ZoneinfoDataSource.search_path are valid zoneinfo directories."
    end
  end
  
  @zoneinfo_dir = File.expand_path(@zoneinfo_dir).freeze
  @timezone_index = load_timezone_index.freeze
  @country_index = load_country_index(iso3166_tab_path, zone_tab_path).freeze
end

Instance Attribute Details

#zoneinfo_dir ⇒ Object (readonly)

The zoneinfo directory being used.



137
138
139
 
# File 'lib/tzinfo/zoneinfo_data_source.rb', line 137

def zoneinfo_dir
  @zoneinfo_dir
end

Class Method Details

.alternate_iso3166_tab_search_path ⇒ Object

An Array of paths that will be checked to find an alternate iso3166.tab file if one was not included in the zoneinfo directory (for example, on FreeBSD and OpenBSD systems).

Paths are checked in the order they appear in the array.

The default value is [‘/usr/share/misc/iso3166.tab’, ‘/usr/share/misc/iso3166’].



119
120
121
 
# File 'lib/tzinfo/zoneinfo_data_source.rb', line 119

def self.alternate_iso3166_tab_search_path
  @@alternate_iso3166_tab_search_path
end

.alternate_iso3166_tab_search_path=(alternate_iso3166_tab_search_path) ⇒ Object

Sets the paths to check to locate an alternate iso3166.tab file if one was not included in the zoneinfo directory.

Can be set to an Array of directories or a String containing directories separated with File::PATH_SEPARATOR.

Paths are checked in the order they appear in the array.

Set to nil to revert to the default paths.



132
133
134
 
# File 'lib/tzinfo/zoneinfo_data_source.rb', line 132

def self.alternate_iso3166_tab_search_path=(alternate_iso3166_tab_search_path)
  @@alternate_iso3166_tab_search_path = process_search_path(alternate_iso3166_tab_search_path, DEFAULT_ALTERNATE_ISO3166_TAB_SEARCH_PATH)
end

.search_path ⇒ Object

An Array of directories that will be checked to find the system zoneinfo directory.

Directories are checked in the order they appear in the Array.

The default value is [‘/usr/share/zoneinfo’, ‘/usr/share/lib/zoneinfo’, ‘/etc/zoneinfo’].



95
96
97
 
# File 'lib/tzinfo/zoneinfo_data_source.rb', line 95

def self.search_path
  @@search_path
end

.search_path=(search_path) ⇒ Object

Sets the directories to be checked when locating the system zoneinfo directory.

Can be set to an Array of directories or a String containing directories separated with File::PATH_SEPARATOR.

Directories are checked in the order they appear in the Array or String.

Set to nil to revert to the default paths.



108
109
110
 
# File 'lib/tzinfo/zoneinfo_data_source.rb', line 108

def self.search_path=(search_path)
  @@search_path = process_search_path(search_path, DEFAULT_SEARCH_PATH)      
end

Instance Method Details

#country_codes ⇒ Object

Returns an array of all the available ISO 3166-1 alpha-2 country codes.



250
251
252
 
# File 'lib/tzinfo/zoneinfo_data_source.rb', line 250

def country_codes
  @country_index.keys.freeze
end

#data_timezone_identifiers ⇒ Object

Returns an array of all the available timezone identifiers for data timezones (i.e. those that actually contain definitions).

For ZoneinfoDataSource, this will always be identical to timezone_identifers.



227
228
229
 
# File 'lib/tzinfo/zoneinfo_data_source.rb', line 227

def data_timezone_identifiers
  @timezone_index
end

#inspect ⇒ Object

Returns internal object state as a programmer-readable string.



260
261
262
 
# File 'lib/tzinfo/zoneinfo_data_source.rb', line 260

def inspect
  "#<#{self.class}: #{@zoneinfo_dir}>"
end

#linked_timezone_identifiers ⇒ Object

Returns an array of all the available timezone identifiers that are links to other timezones.

For ZoneinfoDataSource, this will always be an empty array.



235
236
237
 
# File 'lib/tzinfo/zoneinfo_data_source.rb', line 235

def linked_timezone_identifiers
  [].freeze
end

#load_country_info(code) ⇒ Object

Returns a CountryInfo instance for the given ISO 3166-1 alpha-2 country code. Raises InvalidCountryCode if the country could not be found or the code is invalid.

Raises:



242
243
244
245
246
 
# File 'lib/tzinfo/zoneinfo_data_source.rb', line 242

def load_country_info(code)
  info = @country_index[code]
  raise InvalidCountryCode, 'Invalid country code' unless info
  info
end

#load_timezone_info(identifier) ⇒ Object

Returns a TimezoneInfo instance for a given identifier. Raises InvalidTimezoneIdentifier if the timezone is not found or the identifier is invalid.



192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
 
# File 'lib/tzinfo/zoneinfo_data_source.rb', line 192

def load_timezone_info(identifier)
  begin
    if @timezone_index.include?(identifier)
      path = File.join(@zoneinfo_dir, identifier)
      
      # Untaint path rather than identifier. We don't want to modify 
      # identifier. identifier may also be frozen and therefore cannot be
      # untainted.
      path.untaint
      
      begin
        ZoneinfoTimezoneInfo.new(identifier, path)
      rescue InvalidZoneinfoFile => e
        raise InvalidTimezoneIdentifier, e.message
      end
    else
      raise InvalidTimezoneIdentifier, 'Invalid identifier'
    end
  rescue Errno::ENOENT, Errno::ENAMETOOLONG, Errno::ENOTDIR
    raise InvalidTimezoneIdentifier, 'Invalid identifier'
  rescue Errno::EACCES => e
    raise InvalidTimezoneIdentifier, e.message
  end
end

#timezone_identifiers ⇒ Object

Returns an array of all the available timezone identifiers.



218
219
220
 
# File 'lib/tzinfo/zoneinfo_data_source.rb', line 218

def timezone_identifiers
  @timezone_index
end

#to_s ⇒ Object

Returns the name and information about this DataSource.



255
256
257
 
# File 'lib/tzinfo/zoneinfo_data_source.rb', line 255

def to_s
  "Zoneinfo DataSource: #{@zoneinfo_dir}"
end