class TZInfo::Timezone

Compares this {Timezone} with another based on the {identifier}.

@param tz [Object] an ‘Object` to compare this {Timezone} with. @return [Integer] -1 if `tz` is less than `self`, 0 if `tz` is equal to

`self` and +1 if `tz` is greater than `self`, or `nil` if `tz` is not an
instance of {Timezone}.

# File lib/tzinfo/timezone.rb, line 1105
def <=>(tz)
  return nil unless tz.is_a?(Timezone)
  identifier <=> tz.identifier
end

=~ (regexp)

Matches ‘regexp` against the {identifier} of this {Timezone}.

@param regexp [Regexp] a ‘Regexp` to match against the {identifier} of

this {Timezone}.

@return [Integer] the position the match starts, or ‘nil` if there is no

match.

# File lib/tzinfo/timezone.rb, line 1128
def =~(regexp)
  regexp =~ identifier
end

_dump (limit)

Returns a serialized representation of this {Timezone}. This method is called when using ‘Marshal.dump` with an instance of {Timezone}.

@param limit [Integer] the maximum depth to dump - ignored. @return [String] a serialized representation of this {Timezone}.

# File lib/tzinfo/timezone.rb, line 1137
def _dump(limit)
  identifier
end

abbr (time = Time.now)

Alias for: abbreviation

abbreviation (time = Time.now)

@param time [Object] a ‘Time`, `DateTime` or `Timestamp`. @return [String] the abbreviation of this {Timezone} at the given time. @raise [ArgumentError] if `time` is `nil`. @raise [ArgumentError] if `time` is a {Timestamp} with an unspecified UTC

offset.

# File lib/tzinfo/timezone.rb, line 1048
def abbreviation(time = Time.now)
  period_for(time).abbreviation
end

Also aliased as: abbr

base_utc_offset (time = Time.now)

Returns the base offset from UTC in seconds at the given time. This does not include any adjustment made for daylight savings time and will typically remain constant throughout the year.

To obtain the observed offset from UTC, including the effect of daylight savings time, use {observed_utc_offset} instead.

If you require accurate {base_utc_offset} values, you should install the tzinfo-data gem and set {DataSources::RubyDataSource} as the {DataSource}. When using {DataSources::ZoneinfoDataSource}, the value of {base_utc_offset} has to be derived from changes to the observed UTC offset and DST status since it is not included in zoneinfo files.

@param time [Object] a ‘Time`, `DateTime` or `Timestamp`. @return [Integer] the base offset from UTC in seconds at the given time. @raise [ArgumentError] if `time` is `nil`. @raise [ArgumentError] if `time` is a {Timestamp} with an unspecified UTC

offset.

# File lib/tzinfo/timezone.rb, line 1081
def base_utc_offset(time = Time.now)
  period_for(time).base_utc_offset
end

canonical_identifier ()

Returns the canonical identifier of this time zone.

This is a shortcut for calling ‘canonical_zone.identifier`. Please refer to the {canonical_zone} documentation for further information.

@return [String] the canonical identifier of this time zone.

# File lib/tzinfo/timezone.rb, line 987
def canonical_identifier
  canonical_zone.identifier
end

canonical_zone ()

Returns the canonical {Timezone} instance for this {Timezone}.

The IANA Time Zone database contains two types of definition: Zones and Links. Zones are defined by rules that set out when transitions occur. Links are just references to fully defined Zone, creating an alias for that Zone.

Links are commonly used where a time zone has been renamed in a release of the Time Zone database. For example, the US/Eastern Zone was renamed as America/New_York. A US/Eastern Link was added in its place, linking to (and creating an alias for) America/New_York.

Links are also used for time zones that are currently identical to a full Zone, but that are administered separately. For example, Europe/Vatican is a Link to (and alias for) Europe/Rome.

For a full Zone (implemented by {DataTimezone}), {canonical_zone} returns self.

For a Link (implemented by {LinkedTimezone}), {canonical_zone} returns a {Timezone} instance representing the full Zone that the link targets.

TZInfo can be used with different data sources (see the documentation for {TZInfo::DataSource}). Some DataSource implementations may not support distinguishing between full Zones and Links and will treat all time zones as full Zones. In this case, {canonical_zone} will always return ‘self`.

There are two built-in DataSource implementations. {DataSources::RubyDataSource} (which will be used if the tzinfo-data gem is available) supports Link zones. {DataSources::ZoneinfoDataSource} returns Link zones as if they were full Zones. If the {canonical_zone} or {canonical_identifier} methods are needed, the tzinfo-data gem should be installed.

The {TZInfo::DataSource.get} method can be used to check which DataSource implementation is being used.

@return [Timezone] the canonical {Timezone} instance for this {Timezone}.

# File lib/tzinfo/timezone.rb, line 412
def canonical_zone
  raise_unknown_timezone
end

current_period ()

@return [TimezonePeriod] the current {TimezonePeriod} for the time zone.

# File lib/tzinfo/timezone.rb, line 997
def current_period
  period_for(Time.now)
end

current_period_and_time ()

Alias for: current_time_and_period

current_time_and_period ()

Returns the current local time and {TimezonePeriod} for the time zone as an ‘Array`. The first element is the time as a {TimeWithOffset}. The second element is the period.

@return [Array] an ‘Array` containing the current {TimeWithOffset} for the

time zone as the first element and the current {TimezonePeriod} for the
time zone as the second element.

# File lib/tzinfo/timezone.rb, line 1008
def current_time_and_period
  period = nil

  local_time = Timestamp.for(Time.now) do |ts|
    period = period_for(ts)
    TimestampWithOffset.set_timezone_offset(ts, period.offset)
  end

  [local_time, period]
end

Also aliased as: current_period_and_time

dst? (time = Time.now)

@param time [Object] a ‘Time`, `DateTime` or `Timestamp`. @return [Boolean] whether daylight savings time is in effect at the given

time.

@raise [ArgumentError] if ‘time` is `nil`. @raise [ArgumentError] if `time` is a {Timestamp} with an unspecified UTC

offset.

# File lib/tzinfo/timezone.rb, line 1059
def dst?(time = Time.now)
  period_for(time).dst?
end

eql? (tz)

@param tz [Object] an ‘Object` to compare this {Timezone} with. @return [Boolean] `true` if `tz` is an instance of {Timezone} and has the

same {identifier} as `self`, otherwise `false`.

# File lib/tzinfo/timezone.rb, line 1113
def eql?(tz)
  self == tz
end

friendly_identifier (skip_first_part = false)

Returns {identifier}, modified to make it more readable. Set ‘skip_first_part` to omit the first part of the identifier (typically a region name) where there is more than one part.

For example:

TZInfo::Timezone.get('Europe/Paris').friendly_identifier(false)         #=> "Europe - Paris"
TZInfo::Timezone.get('Europe/Paris').friendly_identifier(true)          #=> "Paris"
TZInfo::Timezone.get('America/Indiana/Knox').friendly_identifier(false) #=> "America - Knox, Indiana"
TZInfo::Timezone.get('America/Indiana/Knox').friendly_identifier(true)  #=> "Knox, Indiana"

@param skip_first_part [Boolean] whether the first part of the identifier

(typically a region name) should be omitted.

@return [String] the modified identifier.

# File lib/tzinfo/timezone.rb, line 277
def friendly_identifier(skip_first_part = false)
  id = identifier
  id = id.encode(Encoding::UTF_8) unless id.encoding.ascii_compatible?
  parts = id.split('/')
  if parts.empty?
    # shouldn't happen
    identifier
  elsif parts.length == 1
    parts[0]
  else
    prefix = skip_first_part ? nil : "#{parts[0]} - "

    parts = parts.drop(1).map do |part|
      part.gsub!(/_/, ' ')

      if part.index(/[a-z]/)
        # Missing a space if a lower case followed by an upper case and the
        # name isn't McXxxx.
        part.gsub!(/([^M][a-z])([A-Z])/, '\1 \2')
        part.gsub!(/([M][a-bd-z])([A-Z])/, '\1 \2')

        # Missing an apostrophe if two consecutive upper case characters.
        part.gsub!(/([A-Z])([A-Z])/, '\1\'\2')
      end

      part
    end

    "#{prefix}#{parts.reverse.join(', ')}"
  end
end

hash ()

@return [Integer] a hash based on the {identifier}.

# File lib/tzinfo/timezone.rb, line 1118
def hash
  identifier.hash
end

identifier ()

@return [String] the identifier of the time zone, for example,

`"Europe/Paris"`.

# File lib/tzinfo/timezone.rb, line 241
def identifier
  raise_unknown_timezone
end

inspect ()

@return [String] the internal object state as a programmer-readable

`String`.

# File lib/tzinfo/timezone.rb, line 259
def inspect
  "#<#{self.class}: #{identifier}>"
end

local_datetime (year, month = 1, day = 1, hour = 0, minute = 0, second = 0, sub_second = 0, dst = Timezone.default_dst, &block)

Creates a ‘DateTime` object based on the given (Gregorian calendar) date and time parameters. The parameters are interpreted as a local time in the time zone. The result has the appropriate `offset` and {DateTimeWithOffset#timezone_offset timezone_offset}.

Warning: There are time values that are not valid as local times in a time zone (for example, during the transition from standard time to daylight savings time). There are also time values that are ambiguous, occurring more than once with different offsets to UTC (for example, during the transition from daylight savings time to standard time).

In the first case (an invalid local time), a {PeriodNotFound} exception will be raised.

In the second case (more than one occurrence), an {AmbiguousTime} exception will be raised unless the optional ‘dst` parameter or block handles the ambiguity.

If the ambiguity is due to a transition from daylight savings time to standard time, the ‘dst` parameter can be used to select whether the daylight savings time or local time is used. For example, the following code would raise an {AmbiguousTime} exception:

tz = TZInfo::Timezone.get('America/New_York')
tz.local_datetime(2004,10,31,1,30,0,0)

Specifying ‘dst = true` would return a `Time` with a UTC offset of -4 hours and abbreviation EDT (Eastern Daylight Time). Specifying `dst = false` would return a `Time` with a UTC offset of -5 hours and abbreviation EST (Eastern Standard Time).

The ‘dst` parameter will not be able to resolve an ambiguity resulting from the clocks being set back without changing from daylight savings time to standard time. In this case, if a block is specified, it will be called to resolve the ambiguity. The block must take a single parameter - an `Array` of {TimezonePeriod}s that need to be resolved. The block can select and return a single {TimezonePeriod} or return `nil` or an empty `Array` to cause an {AmbiguousTime} exception to be raised.

The default value of the ‘dst` parameter can be specified using {Timezone.default_dst=}.

@param year [Integer] the year. @param month [Integer] the month (1-12). @param day [Integer] the day of the month (1-31). @param hour [Integer] the hour (0-23). @param minute [Integer] the minute (0-59). @param second [Integer] the second (0-59). @param sub_second [Numeric] the fractional part of the second as either

a `Rational` that is greater than or equal to 0 and less than 1, or
the `Integer` 0.

@param dst [Boolean] whether to resolve ambiguous local times by always

selecting the period observing daylight savings time (`true`), always
selecting the period observing standard time (`false`), or leaving the
ambiguity unresolved (`nil`).

@yield [periods] if the ‘dst` parameter did not resolve an ambiguity, an

optional block is yielded to.

@yieldparam periods [Array<TimezonePeriod>] an ‘Array` containing all

the {TimezonePeriod}s that still match `local_time` after applying the
`dst` parameter.

@yieldreturn [Object] to resolve the ambiguity: a chosen {TimezonePeriod}

or an `Array` containing a chosen {TimezonePeriod}; to leave the
ambiguity unresolved: an empty `Array`, an `Array` containing more than
one {TimezonePeriod}, or `nil`.

@return [DateTimeWithOffset] a new ‘DateTime` object based on the given values, interpreted as a local time in the time zone. @raise [ArgumentError] if either of `year`, `month`, `day`, `hour`,

`minute`, or `second` is not an `Integer`.

@raise [ArgumentError] if ‘sub_second` is not a `Rational`, or the

`Integer` 0.

@raise [ArgumentError] if ‘utc_offset` is not `nil`, not an `Integer`

and not the `Symbol` `:utc`.

@raise [RangeError] if ‘month` is not between 1 and 12. @raise [RangeError] if `day` is not between 1 and 31. @raise [RangeError] if `hour` is not between 0 and 23. @raise [RangeError] if `minute` is not between 0 and 59. @raise [RangeError] if `second` is not between 0 and 59. @raise [RangeError] if `sub_second` is a `Rational` but that is less

than 0 or greater than or equal to 1.

@raise [PeriodNotFound] if the date and time parameters do not specify a

valid local time in the time zone.

@raise [AmbiguousTime] if the date and time parameters are ambiguous for

the time zone and the `dst` parameter or block did not resolve the
ambiguity.

# File lib/tzinfo/timezone.rb, line 831
def local_datetime(year, month = 1, day = 1, hour = 0, minute = 0, second = 0, sub_second = 0, dst = Timezone.default_dst, &block)
  local_timestamp(year, month, day, hour, minute, second, sub_second, dst, &block).to_datetime
end

local_time (year, month = 1, day = 1, hour = 0, minute = 0, second = 0, sub_second = 0, dst = Timezone.default_dst, &block)

Creates a ‘Time` object based on the given (Gregorian calendar) date and time parameters. The parameters are interpreted as a local time in the time zone. The result has the appropriate `utc_offset`, `zone` and {TimeWithOffset#timezone_offset timezone_offset}.

Warning: There are time values that are not valid as local times in a time zone (for example, during the transition from standard time to daylight savings time). There are also time values that are ambiguous, occurring more than once with different offsets to UTC (for example, during the transition from daylight savings time to standard time).

In the first case (an invalid local time), a {PeriodNotFound} exception will be raised.

In the second case (more than one occurrence), an {AmbiguousTime} exception will be raised unless the optional ‘dst` parameter or block handles the ambiguity.

If the ambiguity is due to a transition from daylight savings time to standard time, the ‘dst` parameter can be used to select whether the daylight savings time or local time is used. For example, the following code would raise an {AmbiguousTime} exception:

tz = TZInfo::Timezone.get('America/New_York')
tz.local_time(2004,10,31,1,30,0,0)

Specifying ‘dst = true` would return a `Time` with a UTC offset of -4 hours and abbreviation EDT (Eastern Daylight Time). Specifying `dst = false` would return a `Time` with a UTC offset of -5 hours and abbreviation EST (Eastern Standard Time).

The ‘dst` parameter will not be able to resolve an ambiguity resulting from the clocks being set back without changing from daylight savings time to standard time. In this case, if a block is specified, it will be called to resolve the ambiguity. The block must take a single parameter - an `Array` of {TimezonePeriod}s that need to be resolved. The block can select and return a single {TimezonePeriod} or return `nil` or an empty `Array` to cause an {AmbiguousTime} exception to be raised.

The default value of the ‘dst` parameter can be specified using {Timezone.default_dst=}.

@param year [Integer] the year. @param month [Integer] the month (1-12). @param day [Integer] the day of the month (1-31). @param hour [Integer] the hour (0-23). @param minute [Integer] the minute (0-59). @param second [Integer] the second (0-59). @param sub_second [Numeric] the fractional part of the second as either

a `Rational` that is greater than or equal to 0 and less than 1, or
the `Integer` 0.

@param dst [Boolean] whether to resolve ambiguous local times by always

selecting the period observing daylight savings time (`true`), always
selecting the period observing standard time (`false`), or leaving the
ambiguity unresolved (`nil`).

@yield [periods] if the ‘dst` parameter did not resolve an ambiguity, an

optional block is yielded to.

@yieldparam periods [Array<TimezonePeriod>] an ‘Array` containing all

the {TimezonePeriod}s that still match `local_time` after applying the
`dst` parameter.

@yieldreturn [Object] to resolve the ambiguity: a chosen {TimezonePeriod}

or an `Array` containing a chosen {TimezonePeriod}; to leave the
ambiguity unresolved: an empty `Array`, an `Array` containing more than
one {TimezonePeriod}, or `nil`.

@return [TimeWithOffset] a new ‘Time` object based on the given values,

interpreted as a local time in the time zone.

@raise [ArgumentError] if either of ‘year`, `month`, `day`, `hour`,

`minute`, or `second` is not an `Integer`.

@raise [ArgumentError] if ‘sub_second` is not a `Rational`, or the

`Integer` 0.

@raise [ArgumentError] if ‘utc_offset` is not `nil`, not an `Integer`

and not the `Symbol` `:utc`.

@raise [RangeError] if ‘month` is not between 1 and 12. @raise [RangeError] if `day` is not between 1 and 31. @raise [RangeError] if `hour` is not between 0 and 23. @raise [RangeError] if `minute` is not between 0 and 59. @raise [RangeError] if `second` is not between 0 and 59. @raise [RangeError] if `sub_second` is a `Rational` but that is less

than 0 or greater than or equal to 1.

@raise [PeriodNotFound] if the date and time parameters do not specify a

valid local time in the time zone.

@raise [AmbiguousTime] if the date and time parameters are ambiguous for

the time zone and the `dst` parameter or block did not resolve the
ambiguity.

# File lib/tzinfo/timezone.rb, line 743
def local_time(year, month = 1, day = 1, hour = 0, minute = 0, second = 0, sub_second = 0, dst = Timezone.default_dst, &block)
  local_timestamp(year, month, day, hour, minute, second, sub_second, dst, &block).to_time
end

local_timestamp (year, month = 1, day = 1, hour = 0, minute = 0, second = 0, sub_second = 0, dst = Timezone.default_dst, &block)

Creates a {Timestamp} object based on the given (Gregorian calendar) date and time parameters. The parameters are interpreted as a local time in the time zone. The result has the appropriate {Timestamp#utc_offset utc_offset} and {TimestampWithOffset#timezone_offset timezone_offset}.

Warning: There are time values that are not valid as local times in a time zone (for example, during the transition from standard time to daylight savings time). There are also time values that are ambiguous, occurring more than once with different offsets to UTC (for example, during the transition from daylight savings time to standard time).

In the first case (an invalid local time), a {PeriodNotFound} exception will be raised.

In the second case (more than one occurrence), an {AmbiguousTime} exception will be raised unless the optional ‘dst` parameter or block handles the ambiguity.

If the ambiguity is due to a transition from daylight savings time to standard time, the ‘dst` parameter can be used to select whether the daylight savings time or local time is used. For example, the following code would raise an {AmbiguousTime} exception:

tz = TZInfo::Timezone.get('America/New_York')
tz.local_timestamp(2004,10,31,1,30,0,0)

Specifying ‘dst = true` would return a `Time` with a UTC offset of -4 hours and abbreviation EDT (Eastern Daylight Time). Specifying `dst = false` would return a `Time` with a UTC offset of -5 hours and abbreviation EST (Eastern Standard Time).

The ‘dst` parameter will not be able to resolve an ambiguity resulting from the clocks being set back without changing from daylight savings time to standard time. In this case, if a block is specified, it will be called to resolve the ambiguity. The block must take a single parameter - an `Array` of {TimezonePeriod}s that need to be resolved. The block can select and return a single {TimezonePeriod} or return `nil` or an empty `Array` to cause an {AmbiguousTime} exception to be raised.

The default value of the ‘dst` parameter can be specified using {Timezone.default_dst=}.

@param year [Integer] the year. @param month [Integer] the month (1-12). @param day [Integer] the day of the month (1-31). @param hour [Integer] the hour (0-23). @param minute [Integer] the minute (0-59). @param second [Integer] the second (0-59). @param sub_second [Numeric] the fractional part of the second as either

a `Rational` that is greater than or equal to 0 and less than 1, or
the `Integer` 0.

@param dst [Boolean] whether to resolve ambiguous local times by always

selecting the period observing daylight savings time (`true`), always
selecting the period observing standard time (`false`), or leaving the
ambiguity unresolved (`nil`).

@yield [periods] if the ‘dst` parameter did not resolve an ambiguity, an

optional block is yielded to.

@yieldparam periods [Array<TimezonePeriod>] an ‘Array` containing all

the {TimezonePeriod}s that still match `local_time` after applying the
`dst` parameter.

@yieldreturn [Object] to resolve the ambiguity: a chosen {TimezonePeriod}

or an `Array` containing a chosen {TimezonePeriod}; to leave the
ambiguity unresolved: an empty `Array`, an `Array` containing more than
one {TimezonePeriod}, or `nil`.

@return [TimestampWithOffset] a new {Timestamp} object based on the given

values, interpreted as a local time in the time zone.

@raise [ArgumentError] if either of ‘year`, `month`, `day`, `hour`,

`minute`, or `second` is not an `Integer`.

@raise [ArgumentError] if ‘sub_second` is not a `Rational`, or the

`Integer` 0.

@raise [ArgumentError] if ‘utc_offset` is not `nil`, not an `Integer`

and not the `Symbol` `:utc`.

@raise [RangeError] if ‘month` is not between 1 and 12. @raise [RangeError] if `day` is not between 1 and 31. @raise [RangeError] if `hour` is not between 0 and 23. @raise [RangeError] if `minute` is not between 0 and 59. @raise [RangeError] if `second` is not between 0 and 59. @raise [RangeError] if `sub_second` is a `Rational` but that is less

than 0 or greater than or equal to 1.

@raise [PeriodNotFound] if the date and time parameters do not specify a

valid local time in the time zone.

@raise [AmbiguousTime] if the date and time parameters are ambiguous for

the time zone and the `dst` parameter or block did not resolve the
ambiguity.

# File lib/tzinfo/timezone.rb, line 919
def local_timestamp(year, month = 1, day = 1, hour = 0, minute = 0, second = 0, sub_second = 0, dst = Timezone.default_dst, &block)
  ts = Timestamp.create(year, month, day, hour, minute, second, sub_second)
  timezone_offset = period_for_local(ts, dst, &block).offset
  utc_offset = timezone_offset.observed_utc_offset
  TimestampWithOffset.new(ts.value - utc_offset, sub_second, utc_offset).set_timezone_offset(timezone_offset)
end

local_to_utc (local_time, dst = Timezone.default_dst) { |periods| ... }

Converts a local time for the time zone to UTC.

The result will either be a ‘Time`, `DateTime` or {Timestamp} according to the type of the `local_time` parameter.

The UTC offset of the ‘local_time` parameter is ignored (it is treated as a time in the time zone represented by `self`).

Warning: There are local times that have no equivalent UTC times (for example, during the transition from standard time to daylight savings time). There are also local times that have more than one UTC equivalent (for example, during the transition from daylight savings time to standard time).

In the first case (no equivalent UTC time), a {PeriodNotFound} exception will be raised.

In the second case (more than one equivalent UTC time), an {AmbiguousTime} exception will be raised unless the optional ‘dst` parameter or block handles the ambiguity.

If the ambiguity is due to a transition from daylight savings time to standard time, the ‘dst` parameter can be used to select whether the daylight savings time or local time is used. For example, the following code would raise an {AmbiguousTime} exception:

tz = TZInfo::Timezone.get('America/New_York')
tz.period_for_local(Time.new(2004,10,31,1,30,0))

Specifying ‘dst = true` would select the daylight savings period from April to October 2004. Specifying `dst = false` would return the standard time period from October 2004 to April 2005.

The ‘dst` parameter will not be able to resolve an ambiguity resulting from the clocks being set back without changing from daylight savings time to standard time. In this case, if a block is specified, it will be called to resolve the ambiguity. The block must take a single parameter - an `Array` of {TimezonePeriod}s that need to be resolved. The block can select and return a single {TimezonePeriod} or return `nil` or an empty `Array` to cause an {AmbiguousTime} exception to be raised.

The default value of the ‘dst` parameter can be specified using {Timezone.default_dst=}.

@param local_time [Object] a ‘Time`, `DateTime` or {Timestamp}. @param dst [Boolean] whether to resolve ambiguous local times by always

selecting the period observing daylight savings time (`true`), always
selecting the period observing standard time (`false`), or leaving the
ambiguity unresolved (`nil`).

@yield [periods] if the ‘dst` parameter did not resolve an ambiguity, an

optional block is yielded to.

@yieldparam periods [Array<TimezonePeriod>] an ‘Array` containing all

the {TimezonePeriod}s that still match `local_time` after applying the
`dst` parameter.

@yieldreturn [Object] to resolve the ambiguity: a chosen {TimezonePeriod}

or an `Array` containing a chosen {TimezonePeriod}; to leave the
ambiguity unresolved: an empty `Array`, an `Array` containing more than
one {TimezonePeriod}, or `nil`.

@return [Object] the UTC equivalent of ‘local_time` as a `Time`,

`DateTime` or {Timestamp}.

@raise [ArgumentError] if ‘local_time` is `nil`. @raise [PeriodNotFound] if `local_time` is not valid for the time zone

(there is no equivalent UTC time).

@raise [AmbiguousTime] if ‘local_time` was ambiguous for the time zone and

the `dst` parameter or block did not resolve the ambiguity.

# File lib/tzinfo/timezone.rb, line 645
def local_to_utc(local_time, dst = Timezone.default_dst)
  raise ArgumentError, 'local_time must be specified' unless local_time

  Timestamp.for(local_time, :ignore) do |ts|
    period = if block_given?
      period_for_local(ts, dst) {|periods| yield periods }
    else
      period_for_local(ts, dst)
    end

    ts.add_and_set_utc_offset(-period.observed_utc_offset, :utc)
  end
end

name ()

@return [String] the identifier of the time zone, for example,

`"Europe/Paris"`.

# File lib/tzinfo/timezone.rb, line 247
def name
  # Don't use alias, as identifier gets overridden.
  identifier
end

now ()

@return [TimeWithOffset] the current local time in the time zone.

# File lib/tzinfo/timezone.rb, line 992
def now
  to_local(Time.now)
end

observed_utc_offset (time = Time.now)

Returns the observed offset from UTC in seconds at the given time. This includes adjustments made for daylight savings time.

@param time [Object] a ‘Time`, `DateTime` or `Timestamp`. @return [Integer] the observed offset from UTC in seconds at the given

time.

@raise [ArgumentError] if ‘time` is `nil`. @raise [ArgumentError] if `time` is a {Timestamp} with an unspecified UTC

offset.

# File lib/tzinfo/timezone.rb, line 1094
def observed_utc_offset(time = Time.now)
  period_for(time).observed_utc_offset
end

Also aliased as: utc_offset

offsets_up_to (to, from = nil)

Returns the unique offsets used by the time zone up to a given time (‘to`) as an `Array` of {TimezoneOffset} instances.

A from time may also be supplied using the ‘from` parameter. If from is not `nil`, only offsets used from that time onwards will be returned.

Comparisons with ‘to` are exclusive. Comparisons with `from` are inclusive.

@param to [Object] a ‘Time`, `DateTime` or {Timestamp} specifying the

latest (exclusive) offset to return.

@param from [Object] an optional ‘Time`, `DateTime` or {Timestamp}

specifying the earliest (inclusive) offset to return.

@return [Array<TimezoneOffsets>] the offsets that are used earlier than

`to` and, if specified, at or later than `from`. Offsets may be returned
in any order.

@raise [ArgumentError] if ‘from` is specified and `to` is not greater than

`from`.

@raise [ArgumentError] is raised if ‘to` is `nil`. @raise [ArgumentError] if either `to` or `from` is a {Timestamp} with an

unspecified offset.

# File lib/tzinfo/timezone.rb, line 947
def offsets_up_to(to, from = nil)
  raise ArgumentError, 'to must be specified' unless to

  to_timestamp = Timestamp.for(to)
  from_timestamp = from && Timestamp.for(from)
  transitions = transitions_up_to(to_timestamp, from_timestamp)

  if transitions.empty?
    # No transitions in the range, find the period that covers it.

    if from_timestamp
      # Use the from date as it is inclusive.
      period = period_for(from_timestamp)
    else
      # to is exclusive, so this can't be used with period_for. However, any
      # time earlier than to can be used. Subtract 1 hour.
      period = period_for(to_timestamp.add_and_set_utc_offset(-3600, :utc))
    end

    [period.offset]
  else
    result = Set.new

    first = transitions.first
    result << first.previous_offset unless from_timestamp && first.at == from_timestamp

    transitions.each do |t|
      result << t.offset
    end

    result.to_a
  end
end

period_for (time)

Returns the {TimezonePeriod} that is valid at a given time.

Unlike {period_for_local} and {period_for_utc}, the UTC offset of the ‘time` parameter is taken into consideration.

@param time [Object] a ‘Time`, `DateTime` or {Timestamp}. @return [TimezonePeriod] the {TimezonePeriod} that is valid at `time`. @raise [ArgumentError] if `time` is `nil`. @raise [ArgumentError] if `time` is a {Timestamp} with an unspecified

offset.

# File lib/tzinfo/timezone.rb, line 319
def period_for(time)
  raise_unknown_timezone
end

period_for_local (local_time, dst = Timezone.default_dst) { |results| ... }

Returns the {TimezonePeriod} that is valid at the given local time.

The UTC offset of the ‘local_time` parameter is ignored (it is treated as a time in the time zone represented by `self`). Use the {period_for} method instead if the the UTC offset of the time needs to be taken into consideration.

Warning: There are local times that have no equivalent UTC times (for example, during the transition from standard time to daylight savings time). There are also local times that have more than one UTC equivalent (for example, during the transition from daylight savings time to standard time).

In the first case (no equivalent UTC time), a {PeriodNotFound} exception will be raised.

In the second case (more than one equivalent UTC time), an {AmbiguousTime} exception will be raised unless the optional ‘dst` parameter or block handles the ambiguity.

If the ambiguity is due to a transition from daylight savings time to standard time, the ‘dst` parameter can be used to select whether the daylight savings time or local time is used. For example, the following code would raise an {AmbiguousTime} exception:

tz = TZInfo::Timezone.get('America/New_York')
tz.period_for_local(Time.new(2004,10,31,1,30,0))

Specifying ‘dst = true` would select the daylight savings period from April to October 2004. Specifying `dst = false` would return the standard time period from October 2004 to April 2005.

The ‘dst` parameter will not be able to resolve an ambiguity resulting from the clocks being set back without changing from daylight savings time to standard time. In this case, if a block is specified, it will be called to resolve the ambiguity. The block must take a single parameter - an `Array` of {TimezonePeriod}s that need to be resolved. The block can select and return a single {TimezonePeriod} or return `nil` or an empty `Array` to cause an {AmbiguousTime} exception to be raised.

The default value of the ‘dst` parameter can be specified using {Timezone.default_dst=}.

@param local_time [Object] a ‘Time`, `DateTime` or {Timestamp}. @param dst [Boolean] whether to resolve ambiguous local times by always

selecting the period observing daylight savings time (`true`), always
selecting the period observing standard time (`false`), or leaving the
ambiguity unresolved (`nil`).

@yield [periods] if the ‘dst` parameter did not resolve an ambiguity, an

optional block is yielded to.

@yieldparam periods [Array<TimezonePeriod>] an ‘Array` containing all

the {TimezonePeriod}s that still match `local_time` after applying the
`dst` parameter.

@yieldreturn [Object] to resolve the ambiguity: a chosen {TimezonePeriod}

or an `Array` containing a chosen {TimezonePeriod}; to leave the
ambiguity unresolved: an empty `Array`, an `Array` containing more than
one {TimezonePeriod}, or `nil`.

@return [TimezonePeriod] the {TimezonePeriod} that is valid at

`local_time`.

@raise [ArgumentError] if ‘local_time` is `nil`. @raise [PeriodNotFound] if `local_time` is not valid for the time zone

(there is no equivalent UTC time).

@raise [AmbiguousTime] if ‘local_time` was ambiguous for the time zone and

the `dst` parameter or block did not resolve the ambiguity.

# File lib/tzinfo/timezone.rb, line 494
def period_for_local(local_time, dst = Timezone.default_dst)
  raise ArgumentError, 'local_time must be specified' unless local_time
  local_time = Timestamp.for(local_time, :ignore)
  results = periods_for_local(local_time)

  if results.empty?
    raise PeriodNotFound, "#{local_time.strftime('%Y-%m-%d %H:%M:%S')} is an invalid local time."
  elsif results.size < 2
    results.first
  else
    # ambiguous result try to resolve

    if !dst.nil?
      matches = results.find_all {|period| period.dst? == dst}
      results = matches if !matches.empty?
    end

    if results.size < 2
      results.first
    else
      # still ambiguous, try the block

      if block_given?
        results = yield results
      end

      if results.is_a?(TimezonePeriod)
        results
      elsif results && results.size == 1
        results.first
      else
        raise AmbiguousTime, "#{local_time.strftime('%Y-%m-%d %H:%M:%S')} is an ambiguous local time."
      end
    end
  end
end

period_for_utc (utc_time)

Returns the {TimezonePeriod} that is valid at a given time.

The UTC offset of the ‘utc_time` parameter is ignored (it is treated as a UTC time). Use the {period_for} method instead if the UTC offset of the time needs to be taken into consideration.

@param utc_time [Object] a ‘Time`, `DateTime` or {Timestamp}. @return [TimezonePeriod] the {TimezonePeriod} that is valid at `utc_time`. @raise [ArgumentError] if `utc_time` is `nil`.

# File lib/tzinfo/timezone.rb, line 425
def period_for_utc(utc_time)
  raise ArgumentError, 'utc_time must be specified' unless utc_time
  period_for(Timestamp.for(utc_time, :treat_as_utc))
end

periods_for_local (local_time)

Returns the set of {TimezonePeriod}s that are valid for the given local time as an ‘Array`.

The UTC offset of the ‘local_time` parameter is ignored (it is treated as a time in the time zone represented by `self`).

This will typically return an ‘Array` containing a single {TimezonePeriod}. More than one {TimezonePeriod} will be returned when the local time is ambiguous (for example, when daylight savings time ends). An empty `Array` will be returned when the local time is not valid (for example, when daylight savings time begins).

To obtain just a single {TimezonePeriod} in all cases, use {period_for_local} instead and specify how ambiguities should be resolved.

@param local_time [Object] a ‘Time`, `DateTime` or {Timestamp}. @return [Array<TimezonePeriod>] the set of {TimezonePeriod}s that are

valid at `local_time`.

@raise [ArgumentError] if ‘local_time` is `nil`.

# File lib/tzinfo/timezone.rb, line 342
def periods_for_local(local_time)
  raise_unknown_timezone
end

strftime (format, time = Time.now)

Converts a time to local time for the time zone and returns a ‘String` representation of the local time according to the given format.

‘Timezone#strftime` first expands any occurrences of `%Z` in the format string to the time zone abbreviation for the local time (for example, EST or EDT). Depending on the type of `time` parameter, the result of the expansion is then passed to either `Time#strftime`, `DateTime#strftime` or `Timestamp#strftime` to handle any other format directives.

This method is equivalent to the following:

time_zone.to_local(time).strftime(format)

@param format [String] the format string. @param time [Object] a ‘Time`, `DateTime` or `Timestamp`. @return [String] the formatted local time. @raise [ArgumentError] if `format` or `time` is `nil`. @raise [ArgumentError] if `time` is a {Timestamp} with an unspecified UTC

offset.

# File lib/tzinfo/timezone.rb, line 1039
def strftime(format, time = Time.now)
  to_local(time).strftime(format)
end

to_local (time)

Converts a time to the local time for the time zone.

The result will be of type {TimeWithOffset} (if passed a ‘Time`), {DateTimeWithOffset} (if passed a `DateTime`) or {TimestampWithOffset} (if passed a {Timestamp}). {TimeWithOffset}, {DateTimeWithOffset} and {TimestampWithOffset} are subclasses of `Time`, `DateTime` and {Timestamp} that provide additional information about the local result.

Unlike {utc_to_local}, {to_local} takes the UTC offset of the given time into consideration.

@param time [Object] a ‘Time`, `DateTime` or {Timestamp}. @return [Object] the local equivalent of `time` as a {TimeWithOffset},

{DateTimeWithOffset} or {TimestampWithOffset}.

@raise [ArgumentError] if ‘time` is `nil`. @raise [ArgumentError] if `time` is a {Timestamp} that does not have a

specified UTC offset.

# File lib/tzinfo/timezone.rb, line 548
def to_local(time)
  raise ArgumentError, 'time must be specified' unless time

  Timestamp.for(time) do |ts|
    TimestampWithOffset.set_timezone_offset(ts, period_for(ts).offset)
  end
end

to_s ()

@return [String] {identifier}, modified to make it more readable.

# File lib/tzinfo/timezone.rb, line 253
def to_s
  friendly_identifier
end

transitions_up_to (to, from = nil)

Returns an ‘Array` of {TimezoneTransition} instances representing the times where the UTC offset of the timezone changes.

Transitions are returned up to a given time (‘to`).

A from time may also be supplied using the ‘from` parameter. If from is not `nil`, only transitions from that time onwards will be returned.

Comparisons with ‘to` are exclusive. Comparisons with `from` are inclusive. If a transition falls precisely on `to`, it will be excluded. If a transition falls on `from`, it will be included.

@param to [Object] a ‘Time`, `DateTime` or {Timestamp} specifying the

latest (exclusive) transition to return.

@param from [Object] an optional ‘Time`, `DateTime` or {Timestamp}

specifying the earliest (inclusive) transition to return.

@return [Array<TimezoneTransition>] the transitions that are earlier than

`to` and, if specified, at or later than `from`. Transitions are ordered
by when they occur, from earliest to latest.

@raise [ArgumentError] if ‘from` is specified and `to` is not greater than

`from`.

@raise [ArgumentError] is raised if ‘to` is `nil`. @raise [ArgumentError] if either `to` or `from` is a {Timestamp} with an

unspecified offset.

# File lib/tzinfo/timezone.rb, line 370
def transitions_up_to(to, from = nil)
  raise_unknown_timezone
end

utc_offset (time = Time.now)

Alias for: observed_utc_offset

utc_to_local (utc_time)

Converts a time in UTC to the local time for the time zone.

The result will be of type {TimeWithOffset} (if passed a ‘Time`), {DateTimeWithOffset} (if passed a `DateTime`) or {TimestampWithOffset} (if passed a {Timestamp}). {TimeWithOffset}, {DateTimeWithOffset} and {TimestampWithOffset} are subclasses of `Time`, `DateTime` and {Timestamp} that provide additional information about the local result.

The UTC offset of the ‘utc_time` parameter is ignored (it is treated as a UTC time). Use the {to_local} method instead if the the UTC offset of the time needs to be taken into consideration.

@param utc_time [Object] a ‘Time`, `DateTime` or {Timestamp}. @return [Object] the local equivalent of `utc_time` as a {TimeWithOffset},

{DateTimeWithOffset} or {TimestampWithOffset}.

@raise [ArgumentError] if ‘utc_time` is `nil`.

# File lib/tzinfo/timezone.rb, line 572
def utc_to_local(utc_time)
  raise ArgumentError, 'utc_time must be specified' unless utc_time

  Timestamp.for(utc_time, :treat_as_utc) do |ts|
    to_local(ts)
  end
end

Public Class Methods

Public Instance Methods