| 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 190
190: def +(other)
191: # If we're adding a Duration of variable length (i.e., years, months, days), move forward from #time,
192: # otherwise move forward from #utc, for accuracy when moving across DST boundaries
193: if duration_of_variable_length?(other)
194: method_missing(:+, other)
195: else
196: result = utc.acts_like?(:date) ? utc.since(other) : utc + other rescue utc.since(other)
197: result.in_time_zone(time_zone)
198: end
199: end
# File vendor/rails/activesupport/lib/active_support/time_with_zone.rb, line 201
201: def -(other)
202: # If we're subtracting a Duration of variable length (i.e., years, months, days), move backwards from #time,
203: # otherwise move backwards #utc, for accuracy when moving across DST boundaries
204: if other.acts_like?(:time)
205: utc.to_f - other.to_f
206: elsif duration_of_variable_length?(other)
207: method_missing(:-, other)
208: else
209: result = utc.acts_like?(:date) ? utc.ago(other) : utc - other rescue utc.ago(other)
210: result.in_time_zone(time_zone)
211: end
212: end
# File vendor/rails/activesupport/lib/active_support/time_with_zone.rb, line 228
228: def advance(options)
229: # If we're advancing a value of variable length (i.e., years, weeks, months, days), advance from #time,
230: # otherwise advance from #utc, for accuracy when moving across DST boundaries
231: if options.detect {|k,v| [:years, :weeks, :months, :days].include? k}
232: method_missing(:advance, options)
233: else
234: utc.advance(options).in_time_zone(time_zone)
235: end
236: end
# File vendor/rails/activesupport/lib/active_support/time_with_zone.rb, line 224
224: def ago(other)
225: since(-other)
226: end
# File vendor/rails/activesupport/lib/active_support/time_with_zone.rb, line 170
170: def between?(min, max)
171: utc.between?(min, max)
172: 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 186
186: def eql?(other)
187: utc == other
188: 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 285
285: def freeze
286: period; utc; time # preload instance variables before freezing
287: super
288: end
# File vendor/rails/activesupport/lib/active_support/time_with_zone.rb, line 182
182: def future?
183: utc.future?
184: end
# File vendor/rails/activesupport/lib/active_support/time_with_zone.rb, line 138
138: def httpdate
139: utc.httpdate
140: 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 280
280: def is_a?(klass)
281: klass == ::Time || super
282: end
# File vendor/rails/activesupport/lib/active_support/time_with_zone.rb, line 290
290: def marshal_dump
291: [utc, time_zone.name, time]
292: end
# File vendor/rails/activesupport/lib/active_support/time_with_zone.rb, line 294
294: def marshal_load(variables)
295: initialize(variables[0].utc, ::Time.__send__(:get_zone, variables[1]), variables[2].utc)
296: 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 306
306: def method_missing(sym, *args, &block)
307: result = time.__send__(sym, *args, &block)
308: result.acts_like?(:time) ? self.class.new(nil, time_zone, result) : result
309: end
# File vendor/rails/activesupport/lib/active_support/time_with_zone.rb, line 174
174: def past?
175: utc.past?
176: 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 299
299: def respond_to?(sym, include_priv = false)
300: # consistently respond false to acts_like?(:date), regardless of whether #time is a Time or DateTime
301: return false if sym.to_s == 'acts_like_date?'
302: super || time.respond_to?(sym, include_priv)
303: end
# File vendor/rails/activesupport/lib/active_support/time_with_zone.rb, line 142
142: def rfc2822
143: to_s(:rfc822)
144: end
# File vendor/rails/activesupport/lib/active_support/time_with_zone.rb, line 214
214: def since(other)
215: # If we're adding a Duration of variable length (i.e., years, months, days), move forward from #time,
216: # otherwise move forward from #utc, for accuracy when moving across DST boundaries
217: if duration_of_variable_length?(other)
218: method_missing(:since, other)
219: else
220: utc.since(other).in_time_zone(time_zone)
221: end
222: 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 160
160: def strftime(format)
161: format = format.gsub('%Z', zone).gsub('%z', formatted_offset(false))
162: time.strftime(format)
163: end
# File vendor/rails/activesupport/lib/active_support/time_with_zone.rb, line 251
251: def to_a
252: [time.sec, time.min, time.hour, time.day, time.mon, time.year, time.wday, time.yday, dst?, zone]
253: end
# File vendor/rails/activesupport/lib/active_support/time_with_zone.rb, line 270
270: def to_datetime
271: utc.to_datetime.new_offset(Rational(utc_offset, 86_400))
272: end
# File vendor/rails/activesupport/lib/active_support/time_with_zone.rb, line 255
255: def to_f
256: utc.to_f
257: end
# File vendor/rails/activesupport/lib/active_support/time_with_zone.rb, line 259
259: def to_i
260: utc.to_i
261: 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 122
122: def to_json(options = nil)
123: if ActiveSupport.use_standard_json_time_format
124: xmlschema.inspect
125: else
126: %("#{time.strftime("%Y/%m/%d %H:%M:%S")} #{formatted_offset(false)}")
127: end
128: 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 149
149: def to_s(format = :default)
150: return utc.to_s(format) if format == :db
151: if formatter = ::Time::DATE_FORMATS[format]
152: formatter.respond_to?(:call) ? formatter.call(self).to_s : strftime(formatter)
153: else
154: "#{time.strftime("%Y-%m-%d %H:%M:%S")} #{formatted_offset(false, 'UTC')}" # mimicking Ruby 1.9 Time#to_s format
155: end
156: end
A TimeWithZone acts like a Time, so just return self.
# File vendor/rails/activesupport/lib/active_support/time_with_zone.rb, line 266
266: def to_time
267: self
268: end
# File vendor/rails/activesupport/lib/active_support/time_with_zone.rb, line 130
130: def to_yaml(options = {})
131: if options.kind_of?(YAML::Emitter)
132: utc.to_yaml(options)
133: else
134: time.to_yaml(options).gsub('Z', formatted_offset(true, 'Z'))
135: end
136: end
# File vendor/rails/activesupport/lib/active_support/time_with_zone.rb, line 178
178: def today?
179: time.today?
180: end
# File vendor/rails/activesupport/lib/active_support/time_with_zone.rb, line 247
247: def usec
248: time.respond_to?(:usec) ? time.usec : 0
249: 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
# File vendor/rails/activesupport/lib/active_support/time_with_zone.rb, line 101
101: def xmlschema(fraction_digits = 0)
102: fraction = if fraction_digits > 0
103: ".%i" % time.usec.to_s[0, fraction_digits]
104: end
105:
106: "#{time.strftime("%Y-%m-%dT%H:%M:%S")}#{fraction}#{formatted_offset(true, 'Z')}"
107: end