Class: TZInfo::TimezonePeriod

Inherits:
Object
  • Object
show all
Defined in:
lib/tzinfo/timezone_period.rb

Overview

A period of time in a timezone where the same offset from UTC applies.

All the methods that take times accept instances of Time or DateTime as well as Integer timestamps.

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(start_transition, end_transition, offset = nil) ⇒ TimezonePeriod

Initializes a new TimezonePeriod.

TimezonePeriod instances should not normally be constructed manually.



21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
 
# File 'lib/tzinfo/timezone_period.rb', line 21

def initialize(start_transition, end_transition, offset = nil)
  @start_transition = start_transition
  @end_transition = end_transition
  
  if offset
    raise ArgumentError, 'Offset specified with transitions' if @start_transition || @end_transition
    @offset = offset
  else
    if @start_transition 
      @offset = @start_transition.offset
    elsif @end_transition
      @offset = @end_transition.previous_offset
    else
      raise ArgumentError, 'No offset specified and no transitions to determine it from'
    end
  end
  
  @utc_total_offset_rational = nil      
end

Instance Attribute Details

#end_transition ⇒ Object (readonly)

The TimezoneTransition that defines the end of this TimezonePeriod (may be nil if unbounded).



13
14
15
 
# File 'lib/tzinfo/timezone_period.rb', line 13

def end_transition
  @end_transition
end

#offset ⇒ Object (readonly)

The TimezoneOffset for this period.



16
17
18
 
# File 'lib/tzinfo/timezone_period.rb', line 16

def offset
  @offset
end

#start_transition ⇒ Object (readonly)

The TimezoneTransition that defines the start of this TimezonePeriod (may be nil if unbounded).



9
10
11
 
# File 'lib/tzinfo/timezone_period.rb', line 9

def start_transition
  @start_transition
end

Instance Method Details

#==(p) ⇒ Object

Returns true if this TimezonePeriod is equal to p. This compares the start_transition, end_transition and offset using ==.



215
216
217
218
219
220
 
# File 'lib/tzinfo/timezone_period.rb', line 215

def ==(p)
  p.kind_of?(TimezonePeriod) &&
    start_transition == p.start_transition &&
    end_transition == p.end_transition &&
    offset == p.offset
end

#abbreviation ⇒ Object Also known as: zone_identifier

The identifier of this period, e.g. “GMT” (Greenwich Mean Time) or “BST” (British Summer Time) for “Europe/London”. The returned identifier is a symbol.



78
79
80
 
# File 'lib/tzinfo/timezone_period.rb', line 78

def abbreviation
  @offset.abbreviation
end

#dst? ⇒ Boolean

true if daylight savings is in effect for this period; otherwise false.

Returns:

  • (Boolean) 


148
149
150
 
# File 'lib/tzinfo/timezone_period.rb', line 148

def dst?
  @offset.dst?
end

#eql?(p) ⇒ Boolean

Returns true if this TimezonePeriods is equal to p. This compares the start_transition, end_transition and offset using eql?

Returns:

  • (Boolean) 


224
225
226
227
228
229
 
# File 'lib/tzinfo/timezone_period.rb', line 224

def eql?(p)
  p.kind_of?(TimezonePeriod) &&
    start_transition.eql?(p.start_transition) &&
    end_transition.eql?(p.end_transition) &&
    offset.eql?(p.offset)
end

#hash ⇒ Object

Returns a hash of this TimezonePeriod.



232
233
234
235
236
 
# File 'lib/tzinfo/timezone_period.rb', line 232

def hash
  result = @start_transition.hash ^ @end_transition.hash
  result ^= @offset.hash unless @start_transition || @end_transition
  result       
end

#inspect ⇒ Object

Returns internal object state as a programmer-readable string.



239
240
241
242
243
 
# File 'lib/tzinfo/timezone_period.rb', line 239

def inspect
  result = "#<#{self.class}: #{@start_transition.inspect},#{@end_transition.inspect}"
  result << ",#{@offset.inspect}>" unless @start_transition || @end_transition
  result + '>'
end

#local_after_start?(local) ⇒ Boolean

true if the given local DateTime is after the start of the period (inclusive); otherwise false.

Deprecation warning: this method will be removed in TZInfo version 2.0.0.

Returns:

  • (Boolean) 


187
188
189
 
# File 'lib/tzinfo/timezone_period.rb', line 187

def local_after_start?(local)
  !@start_transition || @start_transition.local_start_at <= local
end

#local_before_end?(local) ⇒ Boolean

true if the given local DateTime is before the end of the period (exclusive); otherwise false.

Deprecation warning: this method will be removed in TZInfo version 2.0.0.

Returns:

  • (Boolean) 


195
196
197
 
# File 'lib/tzinfo/timezone_period.rb', line 195

def local_before_end?(local)
  !@end_transition || @end_transition.local_end_at > local
end

#local_end ⇒ Object

The end time of the period in local time as a DateTime. May be nil if unbounded.



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

def local_end
  @end_transition ? @end_transition.local_end_at.to_datetime : nil
end

#local_end_time ⇒ Object

The end time of the period in local time as a Time. May be nil if unbounded.



143
144
145
 
# File 'lib/tzinfo/timezone_period.rb', line 143

def local_end_time
  @end_transition ? @end_transition.local_end_at.to_time : nil
end

#local_start ⇒ Object

The start time of the period in local time as a DateTime. May be nil if unbounded.



125
126
127
 
# File 'lib/tzinfo/timezone_period.rb', line 125

def local_start
  @start_transition ? @start_transition.local_start_at.to_datetime : nil
end

#local_start_time ⇒ Object

The start time of the period in local time as a Time. May be nil if unbounded.



131
132
133
 
# File 'lib/tzinfo/timezone_period.rb', line 131

def local_start_time
  @start_transition ? @start_transition.local_start_at.to_time : nil
end

#std_offset ⇒ Object

The offset from the time zone’s standard time in seconds. Zero when daylight savings time is not in effect. Non-zero (usually 3600 = 1 hour) if daylight savings is being observed.

Note that zoneinfo files only include the value of utc_total_offset and a DST flag. When using DataSources::ZoneinfoDataSource, the std_offset will be derived from changes to the UTC total offset and the DST flag. As a consequence, utc_total_offset will always be correct, but std_offset may be inaccurate.

If you require std_offset to be accurate, install the tzinfo-data gem and set RubyDataSource as the DataSource.



71
72
73
 
# File 'lib/tzinfo/timezone_period.rb', line 71

def std_offset
  @offset.std_offset
end

#to_local(utc) ⇒ Object

Converts a UTC DateTime to local time based on the offset of this period.

Deprecation warning: this method will be removed in TZInfo version 2.0.0.



202
203
204
 
# File 'lib/tzinfo/timezone_period.rb', line 202

def to_local(utc)
  @offset.to_local(utc)
end

#to_utc(local) ⇒ Object

Converts a local DateTime to UTC based on the offset of this period.

Deprecation warning: this method will be removed in TZInfo version 2.0.0.



209
210
211
 
# File 'lib/tzinfo/timezone_period.rb', line 209

def to_utc(local)
  @offset.to_utc(local)
end

#utc_after_start?(utc) ⇒ Boolean

true if the given UTC DateTime is after the start of the period (inclusive); otherwise false.

Deprecation warning: this method will be removed in TZInfo version 2.0.0.

Returns:

  • (Boolean) 


163
164
165
 
# File 'lib/tzinfo/timezone_period.rb', line 163

def utc_after_start?(utc)
  !@start_transition || @start_transition.at <= utc
end

#utc_before_end?(utc) ⇒ Boolean

true if the given UTC DateTime is before the end of the period (exclusive); otherwise false.

Deprecation warning: this method will be removed in TZInfo version 2.0.0.

Returns:

  • (Boolean) 


171
172
173
 
# File 'lib/tzinfo/timezone_period.rb', line 171

def utc_before_end?(utc)
  !@end_transition || @end_transition.at > utc
end

#utc_end ⇒ Object

The end time of the period in UTC as a DateTime. May be nil if unbounded.



114
115
116
 
# File 'lib/tzinfo/timezone_period.rb', line 114

def utc_end
  @end_transition ? @end_transition.at.to_datetime : nil
end

#utc_end_time ⇒ Object

The end time of the period in UTC as a Time. May be nil if unbounded.



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

def utc_end_time
  @end_transition ? @end_transition.at.to_time : nil
end

#utc_offset ⇒ Object

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

To obtain the currently observed offset from UTC, including the effect of daylight savings time, use utc_total_offset instead.

Note that zoneinfo files only include the value of utc_total_offset and a DST flag. When using ZoneinfoDataSource, the utc_offset will be derived from changes to the UTC total offset and the DST flag. As a consequence, utc_total_offset will always be correct, but utc_offset may be inaccurate.

If you require utc_offset to be accurate, install the tzinfo-data gem and set RubyDataSource as the DataSource.



55
56
57
 
# File 'lib/tzinfo/timezone_period.rb', line 55

def utc_offset
  @offset.utc_offset
end

#utc_start ⇒ Object

The start time of the period in UTC as a DateTime. May be nil if unbounded.



104
105
106
 
# File 'lib/tzinfo/timezone_period.rb', line 104

def utc_start
  @start_transition ? @start_transition.at.to_datetime : nil
end

#utc_start_time ⇒ Object

The start time of the period in UTC as a Time. May be nil if unbounded.



109
110
111
 
# File 'lib/tzinfo/timezone_period.rb', line 109

def utc_start_time
  @start_transition ? @start_transition.at.to_time : nil
end

#utc_total_offset ⇒ Object

Total offset from UTC (seconds). Equal to utc_offset + std_offset.



84
85
86
 
# File 'lib/tzinfo/timezone_period.rb', line 84

def utc_total_offset
  @offset.utc_total_offset
end

#utc_total_offset_rational ⇒ Object

Total offset from UTC (days). Result is a Rational.



89
90
91
92
93
94
95
96
97
98
99
100
101
 
# File 'lib/tzinfo/timezone_period.rb', line 89

def utc_total_offset_rational
  # Thread-safety: It is possible that the value of 
  # @utc_total_offset_rational may be calculated multiple times in 
  # concurrently executing threads. It is not worth the overhead of locking
  # to ensure that @zone_identifiers is only calculated once.

  unless @utc_total_offset_rational
    result = OffsetRationals.rational_for_offset(utc_total_offset)
    return result if frozen?
    @utc_total_offset_rational = result
  end
  @utc_total_offset_rational
end

#valid_for_local?(local) ⇒ Boolean

true if this period is valid for the given local DateTime; otherwise false.

Deprecation warning: this method will be removed in TZInfo version 2.0.0.

Returns:

  • (Boolean) 


179
180
181
 
# File 'lib/tzinfo/timezone_period.rb', line 179

def valid_for_local?(local)      
  local_after_start?(local) && local_before_end?(local) 
end

#valid_for_utc?(utc) ⇒ Boolean

true if this period is valid for the given UTC DateTime; otherwise false.

Deprecation warning: this method will be removed in TZInfo version 2.0.0.

Returns:

  • (Boolean) 


155
156
157
 
# File 'lib/tzinfo/timezone_period.rb', line 155

def valid_for_utc?(utc)
  utc_after_start?(utc) && utc_before_end?(utc) 
end