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
If wrapped time is a DateTime, use DateTime#since instead of +. Otherwise, just pass on to method_missing.
# File vendor/rails/activesupport/lib/active_support/time_with_zone.rb, line 164 164: def +(other) 165: result = utc.acts_like?(:date) ? utc.since(other) : utc + other rescue utc.since(other) 166: result.in_time_zone(time_zone) 167: end
If a time-like object is passed in, compare it with utc. Else if wrapped time is a DateTime, use DateTime#ago instead of DateTime#-. Otherwise, just pass on to method_missing.
# File vendor/rails/activesupport/lib/active_support/time_with_zone.rb, line 172 172: def -(other) 173: if other.acts_like?(:time) 174: utc - other 175: else 176: result = utc.acts_like?(:date) ? utc.ago(other) : utc - other rescue utc.ago(other) 177: result.in_time_zone(time_zone) 178: end 179: end
# File vendor/rails/activesupport/lib/active_support/time_with_zone.rb, line 189 189: def advance(options) 190: utc.advance(options).in_time_zone(time_zone) 191: end
# File vendor/rails/activesupport/lib/active_support/time_with_zone.rb, line 185 185: def ago(other) 186: utc.ago(other).in_time_zone(time_zone) 187: end
# File vendor/rails/activesupport/lib/active_support/time_with_zone.rb, line 154 154: def between?(min, max) 155: utc.between?(min, max) 156: 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 158 158: def eql?(other) 159: utc == other 160: 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 122 122: def httpdate 123: utc.httpdate 124: 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 235 235: def is_a?(klass) 236: klass == ::Time || super 237: end
# File vendor/rails/activesupport/lib/active_support/time_with_zone.rb, line 245 245: def marshal_dump 246: [utc, time_zone.name, time] 247: end
# File vendor/rails/activesupport/lib/active_support/time_with_zone.rb, line 249 249: def marshal_load(variables) 250: initialize(variables[0], ::Time.send!(:get_zone, variables[1]), variables[2]) 251: 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 261 261: def method_missing(sym, *args, &block) 262: result = time.__send__(sym, *args, &block) 263: result.acts_like?(:time) ? self.class.new(nil, time_zone, result) : result 264: 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 254 254: def respond_to?(sym, include_priv = false) 255: # consistently respond false to acts_like?(:date), regardless of whether #time is a Time or DateTime 256: return false if sym.to_s == 'acts_like_date?' 257: super || time.respond_to?(sym, include_priv) 258: end
# File vendor/rails/activesupport/lib/active_support/time_with_zone.rb, line 126 126: def rfc2822 127: to_s(:rfc822) 128: end
# File vendor/rails/activesupport/lib/active_support/time_with_zone.rb, line 181 181: def since(other) 182: utc.since(other).in_time_zone(time_zone) 183: 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 144 144: def strftime(format) 145: format = format.gsub('%Z', zone).gsub('%z', formatted_offset(false)) 146: time.strftime(format) 147: end
# File vendor/rails/activesupport/lib/active_support/time_with_zone.rb, line 206 206: def to_a 207: [time.sec, time.min, time.hour, time.day, time.mon, time.year, time.wday, time.yday, dst?, zone] 208: end
# File vendor/rails/activesupport/lib/active_support/time_with_zone.rb, line 225 225: def to_datetime 226: utc.to_datetime.new_offset(Rational(utc_offset, 86_400)) 227: end
# File vendor/rails/activesupport/lib/active_support/time_with_zone.rb, line 210 210: def to_f 211: utc.to_f 212: end
# File vendor/rails/activesupport/lib/active_support/time_with_zone.rb, line 214 214: def to_i 215: utc.to_i 216: end
# File vendor/rails/activesupport/lib/active_support/time_with_zone.rb, line 106 106: def to_json(options = nil) 107: if ActiveSupport.use_standard_json_time_format 108: xmlschema.inspect 109: else 110: %("#{time.strftime("%Y/%m/%d %H:%M:%S")} #{formatted_offset(false)}") 111: end 112: 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 133 133: def to_s(format = :default) 134: return utc.to_s(format) if format == :db 135: if formatter = ::Time::DATE_FORMATS[format] 136: formatter.respond_to?(:call) ? formatter.call(self).to_s : strftime(formatter) 137: else 138: "#{time.strftime("%Y-%m-%d %H:%M:%S")} #{formatted_offset(false, 'UTC')}" # mimicking Ruby 1.9 Time#to_s format 139: end 140: end
A TimeWithZone acts like a Time, so just return self.
# File vendor/rails/activesupport/lib/active_support/time_with_zone.rb, line 221 221: def to_time 222: self 223: end
# File vendor/rails/activesupport/lib/active_support/time_with_zone.rb, line 114 114: def to_yaml(options = {}) 115: if options.kind_of?(YAML::Emitter) 116: utc.to_yaml(options) 117: else 118: time.to_yaml(options).gsub('Z', formatted_offset(true, 'Z')) 119: end 120: end
# File vendor/rails/activesupport/lib/active_support/time_with_zone.rb, line 202 202: def usec 203: time.respond_to?(:usec) ? time.usec : 0 204: 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