Class: ActiveSupport::TimeWithZone

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

Attributes

Name Read/write?

time_zone R

Public Class Methods

new (utc_time, time_zone, local_time = nil, period = nil)

    # File vendor/rails/activesupport/lib/active_support/time_with_zone.rb, line 9
 9:     def initialize(utc_time, time_zone, local_time = nil, period = nil)
10:       @utc, @time_zone, @time = utc_time, time_zone, local_time
11:       @period = @utc ? period : get_period_and_ensure_valid_local_time
12:     end

Public Instance Methods

+ (other)

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 132
132:     def +(other)
133:       time.acts_like?(:date) ? method_missing(:since, other) : method_missing(:+, other)
134:     end

- (other)

If a time-like object is passed in, compare it with utc Else if wrapped time is a DateTime, use DateTime#ago instead of #- Otherwise, just pass on to method missing

     # File vendor/rails/activesupport/lib/active_support/time_with_zone.rb, line 139
139:     def -(other)
140:       if other.acts_like?(:time)
141:         utc - other
142:       else
143:         time.acts_like?(:date) ? method_missing(:ago, other) : method_missing(:-, other)
144:       end
145:     end

<=> (other)

Use the time in UTC for comparisons

     # File vendor/rails/activesupport/lib/active_support/time_with_zone.rb, line 118
118:     def <=>(other)
119:       utc <=> other
120:     end

acts_like_time? ()

so that self acts_like?(:time)

     # File vendor/rails/activesupport/lib/active_support/time_with_zone.rb, line 175
175:     def acts_like_time?
176:       true
177:     end

between? (min, max)

     # File vendor/rails/activesupport/lib/active_support/time_with_zone.rb, line 122
122:     def between?(min, max)
123:       utc.between?(min, max)
124:     end

comparable_time ()

Alias for utc

dst? ()

    # File vendor/rails/activesupport/lib/active_support/time_with_zone.rb, line 45
45:     def dst?
46:       period.dst?
47:     end

eql? (other)

     # File vendor/rails/activesupport/lib/active_support/time_with_zone.rb, line 126
126:     def eql?(other)
127:       utc == other
128:     end

formatted_offset (colon = true, alternate_utc_string = nil)

    # File vendor/rails/activesupport/lib/active_support/time_with_zone.rb, line 61
61:     def formatted_offset(colon = true, alternate_utc_string = nil)
62:       utc? && alternate_utc_string || utc_offset.to_utc_offset_s(colon)
63:     end

freeze ()

Neuter freeze because freezing can cause problems with lazy loading of attributes

     # File vendor/rails/activesupport/lib/active_support/time_with_zone.rb, line 186
186:     def freeze
187:       self
188:     end

getgm ()

Alias for utc

getlocal ()

Alias for localtime

getutc ()

Alias for utc

gmt? ()

Alias for utc?

gmt_offset ()

Alias for utc_offset

gmtime ()

Alias for utc

gmtoff ()

Alias for utc_offset

hash ()

Alias for to_i

httpdate ()

    # File vendor/rails/activesupport/lib/active_support/time_with_zone.rb, line 91
91:     def httpdate
92:       utc.httpdate
93:     end

in_time_zone (new_zone = ::Time.zone)

Returns the simultaneous time in Time.zone, or the specified zone

    # File vendor/rails/activesupport/lib/active_support/time_with_zone.rb, line 34
34:     def in_time_zone(new_zone = ::Time.zone)
35:       return self if time_zone == new_zone
36:       utc.in_time_zone(new_zone)
37:     end

inspect ()

    # File vendor/rails/activesupport/lib/active_support/time_with_zone.rb, line 70
70:     def inspect
71:       "#{time.strftime('%a, %d %b %Y %H:%M:%S')} #{zone} #{formatted_offset}"
72:     end

is_a? (klass)

Say we‘re a Time to thwart type checking

     # File vendor/rails/activesupport/lib/active_support/time_with_zone.rb, line 180
180:     def is_a?(klass)
181:       klass == ::Time || super
182:     end

isdst ()

Alias for dst?

iso8601 ()

Alias for xmlschema

kind_of? (klass)

Alias for is_a?

localtime ()

Returns a Time.local() instance of the simultaneous time in your system‘s ENV[‘TZ’] zone

    # File vendor/rails/activesupport/lib/active_support/time_with_zone.rb, line 40
40:     def localtime
41:       utc.getlocal
42:     end

marshal_dump ()

     # File vendor/rails/activesupport/lib/active_support/time_with_zone.rb, line 190
190:     def marshal_dump
191:       [utc, time_zone.name, time]
192:     end

marshal_load (variables)

     # File vendor/rails/activesupport/lib/active_support/time_with_zone.rb, line 194
194:     def marshal_load(variables)
195:       initialize(variables[0], ::Time.send!(:get_zone, variables[1]), variables[2])
196:     end

method_missing (sym, *args, &block)

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 206
206:     def method_missing(sym, *args, &block)
207:       if %w(+ - since ago advance).include?(sym.to_s)
208:         result = utc.__send__(sym, *args, &block)
209:         result.acts_like?(:time) ? result.in_time_zone(time_zone) : result
210:       else
211:         result = time.__send__(sym, *args, &block)
212:         result.acts_like?(:time) ? self.class.new(nil, time_zone, result) : result
213:       end
214:     end

period ()

Returns the underlying TZInfo::TimezonePeriod

    # File vendor/rails/activesupport/lib/active_support/time_with_zone.rb, line 29
29:     def period
30:       @period ||= time_zone.period_for_utc(@utc)
31:     end

respond_to? (sym)

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 199
199:     def respond_to?(sym)
200:       # consistently respond false to acts_like?(:date), regardless of whether #time is a Time or DateTime
201:       return false if sym.to_s == 'acts_like_date?'
202:       super || time.respond_to?(sym)
203:     end

rfc2822 ()

    # File vendor/rails/activesupport/lib/active_support/time_with_zone.rb, line 95
95:     def rfc2822
96:       to_s(:rfc822)
97:     end

rfc822 ()

Alias for rfc2822

strftime (format)

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 112
112:     def strftime(format)
113:       format = format.gsub('%Z', zone).gsub('%z', formatted_offset(false))
114:       time.strftime(format)
115:     end

time ()

Returns a Time or DateTime instance that represents the time in time_zone

    # File vendor/rails/activesupport/lib/active_support/time_with_zone.rb, line 15
15:     def time
16:       @time ||= period.to_local(@utc)
17:     end

to_a ()

     # File vendor/rails/activesupport/lib/active_support/time_with_zone.rb, line 151
151:     def to_a
152:       [time.sec, time.min, time.hour, time.day, time.mon, time.year, time.wday, time.yday, dst?, zone]
153:     end

to_datetime ()

     # File vendor/rails/activesupport/lib/active_support/time_with_zone.rb, line 170
170:     def to_datetime
171:       utc.to_datetime.new_offset(Rational(utc_offset, 86_400))
172:     end

to_f ()

     # File vendor/rails/activesupport/lib/active_support/time_with_zone.rb, line 155
155:     def to_f
156:       utc.to_f
157:     end

to_i ()

     # File vendor/rails/activesupport/lib/active_support/time_with_zone.rb, line 159
159:     def to_i
160:       utc.to_i
161:     end

to_json (options = nil)

    # File vendor/rails/activesupport/lib/active_support/time_with_zone.rb, line 79
79:     def to_json(options = nil)
80:       %("#{time.strftime("%Y/%m/%d %H:%M:%S")} #{formatted_offset(false)}")
81:     end

to_s (format = :default)

: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 101
101:     def to_s(format = :default) 
102:       return utc.to_s(format) if format == :db
103:       if formatter = ::Time::DATE_FORMATS[format]
104:         formatter.respond_to?(:call) ? formatter.call(self).to_s : strftime(formatter)
105:       else
106:         "#{time.strftime("%Y-%m-%d %H:%M:%S")} #{formatted_offset(false, 'UTC')}" # mimicking Ruby 1.9 Time#to_s format
107:       end
108:     end

to_time ()

A TimeWithZone acts like a Time, so just return self

     # File vendor/rails/activesupport/lib/active_support/time_with_zone.rb, line 166
166:     def to_time
167:       self
168:     end

to_yaml (options = {})

    # File vendor/rails/activesupport/lib/active_support/time_with_zone.rb, line 83
83:     def to_yaml(options = {})
84:       if options.kind_of?(YAML::Emitter)
85:         utc.to_yaml(options)
86:       else
87:         time.to_yaml(options).gsub('Z', formatted_offset(true, 'Z'))
88:       end
89:     end

tv_sec ()

Alias for to_i

usec ()

     # File vendor/rails/activesupport/lib/active_support/time_with_zone.rb, line 147
147:     def usec
148:       time.respond_to?(:usec) ? time.usec : 0
149:     end

utc ()

Returns a Time or DateTime instance that represents the time in UTC

    # File vendor/rails/activesupport/lib/active_support/time_with_zone.rb, line 20
20:     def utc
21:       @utc ||= period.to_utc(@time)
22:     end

utc? ()

    # File vendor/rails/activesupport/lib/active_support/time_with_zone.rb, line 50
50:     def utc?
51:       time_zone.name == 'UTC'
52:     end

utc_offset ()

    # File vendor/rails/activesupport/lib/active_support/time_with_zone.rb, line 55
55:     def utc_offset
56:       period.utc_total_offset
57:     end

xmlschema ()

    # File vendor/rails/activesupport/lib/active_support/time_with_zone.rb, line 74
74:     def xmlschema
75:       "#{time.strftime("%Y-%m-%dT%H:%M:%S")}#{formatted_offset(true, 'Z')}"
76:     end

zone ()

Time uses zone to display the time zone abbreviation, so we‘re duck-typing it

    # File vendor/rails/activesupport/lib/active_support/time_with_zone.rb, line 66
66:     def zone
67:       period.zone_identifier.to_s
68:     end

Private Instance Methods

get_period_and_ensure_valid_local_time ()

     # File vendor/rails/activesupport/lib/active_support/time_with_zone.rb, line 217
217:       def get_period_and_ensure_valid_local_time
218:         # we don't want a Time.local instance enforcing its own DST rules as well, 
219:         # so transfer time values to a utc constructor if necessary
220:         @time = transfer_time_values_to_utc_constructor(@time) unless @time.utc?
221:         begin
222:           @time_zone.period_for_local(@time)
223:         rescue ::TZInfo::PeriodNotFound
224:           # time is in the "spring forward" hour gap, so we're moving the time forward one hour and trying again
225:           @time += 1.hour
226:           retry
227:         end
228:       end

transfer_time_values_to_utc_constructor (time)

     # File vendor/rails/activesupport/lib/active_support/time_with_zone.rb, line 230
230:       def transfer_time_values_to_utc_constructor(time)
231:         ::Time.utc_time(time.year, time.month, time.day, time.hour, time.min, time.sec, time.respond_to?(:usec) ? time.usec : 0)
232:       end