| Class | ActiveSupport::TimeWithZone |
| In: |
vendor/rails/activesupport/lib/active_support/time_with_zone.rb
|
| Parent: | Object |
A Time-like class that can represent a time in any time zone. Necessary because standard Ruby Time instances are limited to UTC and the system‘s ENV[‘TZ’] zone.
You shouldn‘t ever need to create a TimeWithZone instance directly via new — instead, Rails provides the methods local, parse, at and now on TimeZone instances, and in_time_zone on Time and DateTime instances, for a more user-friendly syntax. Examples:
Time.zone = 'Eastern Time (US & Canada)' # => 'Eastern Time (US & Canada)'
Time.zone.local(2007, 2, 10, 15, 30, 45) # => Sat, 10 Feb 2007 15:30:45 EST -05:00
Time.zone.parse('2007-02-01 15:30:45') # => Sat, 10 Feb 2007 15:30:45 EST -05:00
Time.zone.at(1170361845) # => Sat, 10 Feb 2007 15:30:45 EST -05:00
Time.zone.now # => Sun, 18 May 2008 13:07:55 EDT -04:00
Time.utc(2007, 2, 10, 20, 30, 45).in_time_zone # => Sat, 10 Feb 2007 15:30:45 EST -05:00
See TimeZone and ActiveSupport::CoreExtensions::Time::Zones for further documentation for these methods.
TimeWithZone instances implement the same API as Ruby Time instances, so that Time and TimeWithZone instances are interchangable. Examples:
t = Time.zone.now # => Sun, 18 May 2008 13:27:25 EDT -04:00 t.hour # => 13 t.dst? # => true t.utc_offset # => -14400 t.zone # => "EDT" t.to_s(:rfc822) # => "Sun, 18 May 2008 13:27:25 -0400" t + 1.day # => Mon, 19 May 2008 13:27:25 EDT -04:00 t.beginning_of_year # => Tue, 01 Jan 2008 00:00:00 EST -05:00 t > Time.utc(1999) # => true t.is_a?(Time) # => true t.is_a?(ActiveSupport::TimeWithZone) # => true
| time_zone | [R] |
# File vendor/rails/activesupport/lib/active_support/time_with_zone.rb, line 36
36: def initialize(utc_time, time_zone, local_time = nil, period = nil)
37: @utc, @time_zone, @time = utc_time, time_zone, local_time
38: @period = @utc ? period : get_period_and_ensure_valid_local_time
39: end
# File vendor/rails/activesupport/lib/active_support/time_with_zone.rb, line 174
174: def +(other)
175: # If we're adding a Duration of variable length (i.e., years, months, days), move forward from #time,
176: # otherwise move forward from #utc, for accuracy when moving across DST boundaries
177: if duration_of_variable_length?(other)
178: method_missing(:+, other)
179: else
180: result = utc.acts_like?(:date) ? utc.since(other) : utc + other rescue utc.since(other)
181: result.in_time_zone(time_zone)
182: end
183: end
# File vendor/rails/activesupport/lib/active_support/time_with_zone.rb, line 185
185: def -(other)
186: # If we're subtracting a Duration of variable length (i.e., years, months, days), move backwards from #time,
187: # otherwise move backwards #utc, for accuracy when moving across DST boundaries
188: if other.acts_like?(:time)
189: utc - other
190: elsif duration_of_variable_length?(other)
191: method_missing(:-, other)
192: else
193: result = utc.acts_like?(:date) ? utc.ago(other) : utc - other rescue utc.ago(other)
194: result.in_time_zone(time_zone)
195: end
196: end
# File vendor/rails/activesupport/lib/active_support/time_with_zone.rb, line 212
212: def advance(options)
213: # If we're advancing a value of variable length (i.e., years, weeks, months, days), advance from #time,
214: # otherwise advance from #utc, for accuracy when moving across DST boundaries
215: if options.detect {|k,v| [:years, :weeks, :months, :days].include? k}
216: method_missing(:advance, options)
217: else
218: utc.advance(options).in_time_zone(time_zone)
219: end
220: end
# File vendor/rails/activesupport/lib/active_support/time_with_zone.rb, line 208
208: def ago(other)
209: since(-other)
210: end
# File vendor/rails/activesupport/lib/active_support/time_with_zone.rb, line 166
166: def between?(min, max)
167: utc.between?(min, max)
168: end
# File vendor/rails/activesupport/lib/active_support/time_with_zone.rb, line 72
72: def dst?
73: period.dst?
74: end
# File vendor/rails/activesupport/lib/active_support/time_with_zone.rb, line 170
170: def eql?(other)
171: utc == other
172: end
# File vendor/rails/activesupport/lib/active_support/time_with_zone.rb, line 88
88: def formatted_offset(colon = true, alternate_utc_string = nil)
89: utc? && alternate_utc_string || utc_offset.to_utc_offset_s(colon)
90: end
# File vendor/rails/activesupport/lib/active_support/time_with_zone.rb, line 134
134: def httpdate
135: utc.httpdate
136: end
# File vendor/rails/activesupport/lib/active_support/time_with_zone.rb, line 97
97: def inspect
98: "#{time.strftime('%a, %d %b %Y %H:%M:%S')} #{zone} #{formatted_offset}"
99: end
Say we‘re a Time to thwart type checking.
# File vendor/rails/activesupport/lib/active_support/time_with_zone.rb, line 264
264: def is_a?(klass)
265: klass == ::Time || super
266: end
# File vendor/rails/activesupport/lib/active_support/time_with_zone.rb, line 274
274: def marshal_dump
275: [utc, time_zone.name, time]
276: end
# File vendor/rails/activesupport/lib/active_support/time_with_zone.rb, line 278
278: def marshal_load(variables)
279: initialize(variables[0].utc, ::Time.__send__(:get_zone, variables[1]), variables[2].utc)
280: end
Send the missing method to time instance, and wrap result in a new TimeWithZone with the existing time_zone.
# File vendor/rails/activesupport/lib/active_support/time_with_zone.rb, line 290
290: def method_missing(sym, *args, &block)
291: result = time.__send__(sym, *args, &block)
292: result.acts_like?(:time) ? self.class.new(nil, time_zone, result) : result
293: end
Returns the underlying TZInfo::TimezonePeriod.
# File vendor/rails/activesupport/lib/active_support/time_with_zone.rb, line 56
56: def period
57: @period ||= time_zone.period_for_utc(@utc)
58: end
Ensure proxy class responds to all methods that underlying time instance responds to.
# File vendor/rails/activesupport/lib/active_support/time_with_zone.rb, line 283
283: def respond_to?(sym, include_priv = false)
284: # consistently respond false to acts_like?(:date), regardless of whether #time is a Time or DateTime
285: return false if sym.to_s == 'acts_like_date?'
286: super || time.respond_to?(sym, include_priv)
287: end
# File vendor/rails/activesupport/lib/active_support/time_with_zone.rb, line 138
138: def rfc2822
139: to_s(:rfc822)
140: end
# File vendor/rails/activesupport/lib/active_support/time_with_zone.rb, line 198
198: def since(other)
199: # If we're adding a Duration of variable length (i.e., years, months, days), move forward from #time,
200: # otherwise move forward from #utc, for accuracy when moving across DST boundaries
201: if duration_of_variable_length?(other)
202: method_missing(:since, other)
203: else
204: utc.since(other).in_time_zone(time_zone)
205: end
206: end
Replaces %Z and %z directives with zone and formatted_offset, respectively, before passing to Time#strftime, so that zone information is correct
# File vendor/rails/activesupport/lib/active_support/time_with_zone.rb, line 156
156: def strftime(format)
157: format = format.gsub('%Z', zone).gsub('%z', formatted_offset(false))
158: time.strftime(format)
159: end
# File vendor/rails/activesupport/lib/active_support/time_with_zone.rb, line 235
235: def to_a
236: [time.sec, time.min, time.hour, time.day, time.mon, time.year, time.wday, time.yday, dst?, zone]
237: end
# File vendor/rails/activesupport/lib/active_support/time_with_zone.rb, line 254
254: def to_datetime
255: utc.to_datetime.new_offset(Rational(utc_offset, 86_400))
256: end
# File vendor/rails/activesupport/lib/active_support/time_with_zone.rb, line 239
239: def to_f
240: utc.to_f
241: end
# File vendor/rails/activesupport/lib/active_support/time_with_zone.rb, line 243
243: def to_i
244: utc.to_i
245: end
Returns a JSON string representing the TimeWithZone. If ActiveSupport.use_standard_json_time_format is set to true, the ISO 8601 format is used.
# With ActiveSupport.use_standard_json_time_format = true Time.utc(2005,2,1,15,15,10).in_time_zone.to_json # => "2005-02-01T15:15:10Z" # With ActiveSupport.use_standard_json_time_format = false Time.utc(2005,2,1,15,15,10).in_time_zone.to_json # => "2005/02/01 15:15:10 +0000"
# File vendor/rails/activesupport/lib/active_support/time_with_zone.rb, line 118
118: def to_json(options = nil)
119: if ActiveSupport.use_standard_json_time_format
120: xmlschema.inspect
121: else
122: %("#{time.strftime("%Y/%m/%d %H:%M:%S")} #{formatted_offset(false)}")
123: end
124: end
:db format outputs time in UTC; all others output time in local. Uses TimeWithZone‘s strftime, so %Z and %z work correctly.
# File vendor/rails/activesupport/lib/active_support/time_with_zone.rb, line 145
145: def to_s(format = :default)
146: return utc.to_s(format) if format == :db
147: if formatter = ::Time::DATE_FORMATS[format]
148: formatter.respond_to?(:call) ? formatter.call(self).to_s : strftime(formatter)
149: else
150: "#{time.strftime("%Y-%m-%d %H:%M:%S")} #{formatted_offset(false, 'UTC')}" # mimicking Ruby 1.9 Time#to_s format
151: end
152: end
A TimeWithZone acts like a Time, so just return self.
# File vendor/rails/activesupport/lib/active_support/time_with_zone.rb, line 250
250: def to_time
251: self
252: end
# File vendor/rails/activesupport/lib/active_support/time_with_zone.rb, line 126
126: def to_yaml(options = {})
127: if options.kind_of?(YAML::Emitter)
128: utc.to_yaml(options)
129: else
130: time.to_yaml(options).gsub('Z', formatted_offset(true, 'Z'))
131: end
132: end
# File vendor/rails/activesupport/lib/active_support/time_with_zone.rb, line 231
231: def usec
232: time.respond_to?(:usec) ? time.usec : 0
233: end
# File vendor/rails/activesupport/lib/active_support/time_with_zone.rb, line 77
77: def utc?
78: time_zone.name == 'UTC'
79: end
# File vendor/rails/activesupport/lib/active_support/time_with_zone.rb, line 82
82: def utc_offset
83: period.utc_total_offset
84: end