Class: ActiveSupport::TimeWithZone
- Includes:
- Comparable
- Defined in:
- lib/active_support/time_with_zone.rb
Overview
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
Instance Attribute Summary collapse
-
#time_zone ⇒ Object
readonly
Returns the value of attribute time_zone.
Instance Method Summary collapse
- #+(other) ⇒ Object
- #-(other) ⇒ Object
-
#<=>(other) ⇒ Object
Use the time in UTC for comparisons.
-
#acts_like_time? ⇒ Boolean
So that
self
acts_like?(:time)
. - #advance(options) ⇒ Object
- #ago(other) ⇒ Object
- #between?(min, max) ⇒ Boolean
- #dst? ⇒ Boolean (also: #isdst)
- #eql?(other) ⇒ Boolean
- #formatted_offset(colon = true, alternate_utc_string = nil) ⇒ Object
- #freeze ⇒ Object
- #httpdate ⇒ Object
-
#in_time_zone(new_zone = ::Time.zone) ⇒ Object
Returns the simultaneous time in
Time.zone
, or the specified zone. -
#initialize(utc_time, time_zone, local_time = nil, period = nil) ⇒ TimeWithZone
constructor
A new instance of TimeWithZone.
- #inspect ⇒ Object
-
#is_a?(klass) ⇒ Boolean
(also: #kind_of?)
Say we’re a Time to thwart type checking.
-
#localtime ⇒ Object
(also: #getlocal)
Returns a
Time.local()
instance of the simultaneous time in your system’sENV['TZ']
zone. - #marshal_dump ⇒ Object
- #marshal_load(variables) ⇒ Object
-
#method_missing(sym, *args, &block) ⇒ Object
Send the missing method to
time
instance, and wrap result in a new TimeWithZone with the existingtime_zone
. -
#period ⇒ Object
Returns the underlying TZInfo::TimezonePeriod.
-
#respond_to?(sym, include_priv = false) ⇒ Boolean
Ensure proxy class responds to all methods that underlying time instance responds to.
- #rfc2822 ⇒ Object (also: #rfc822)
- #since(other) ⇒ Object
-
#strftime(format) ⇒ Object
Replaces
%Z
and%z
directives withzone
andformatted_offset
, respectively, before passing to Time#strftime, so that zone information is correct. -
#time ⇒ Object
Returns a Time or DateTime instance that represents the time in
time_zone
. - #to_a ⇒ Object
- #to_datetime ⇒ Object
- #to_f ⇒ Object
- #to_i ⇒ Object (also: #hash, #tv_sec)
- #to_json(options = nil) ⇒ Object
-
#to_s(format = :default) ⇒ Object
:db
format outputs time in UTC; all others output time in local. -
#to_time ⇒ Object
A TimeWithZone acts like a Time, so just return
self
. - #to_yaml(options = {}) ⇒ Object
- #usec ⇒ Object
-
#utc ⇒ Object
(also: #comparable_time, #getgm, #getutc, #gmtime)
Returns a Time or DateTime instance that represents the time in UTC.
- #utc? ⇒ Boolean (also: #gmt?)
- #utc_offset ⇒ Object (also: #gmt_offset, #gmtoff)
- #xmlschema ⇒ Object (also: #iso8601)
-
#zone ⇒ Object
Time uses
zone
to display the time zone abbreviation, so we’re duck-typing it.
Constructor Details
#initialize(utc_time, time_zone, local_time = nil, period = nil) ⇒ TimeWithZone
Returns a new instance of TimeWithZone.
36 37 38 39 |
# File 'lib/active_support/time_with_zone.rb', line 36 def initialize(utc_time, time_zone, local_time = nil, period = nil) @utc, @time_zone, @time = utc_time, time_zone, local_time @period = @utc ? period : get_period_and_ensure_valid_local_time end |
Dynamic Method Handling
This class handles dynamic methods through the method_missing method
#method_missing(sym, *args, &block) ⇒ Object
Send the missing method to time
instance, and wrap result in a new TimeWithZone with the existing time_zone
.
277 278 279 280 |
# File 'lib/active_support/time_with_zone.rb', line 277 def method_missing(sym, *args, &block) result = time.__send__(sym, *args, &block) result.acts_like?(:time) ? self.class.new(nil, time_zone, result) : result end |
Instance Attribute Details
#time_zone ⇒ Object (readonly)
Returns the value of attribute time_zone.
34 35 36 |
# File 'lib/active_support/time_with_zone.rb', line 34 def time_zone @time_zone end |
Instance Method Details
#+(other) ⇒ Object
162 163 164 165 166 167 168 169 170 171 |
# File 'lib/active_support/time_with_zone.rb', line 162 def +(other) # If we're adding a Duration of variable length (i.e., years, months, days), move forward from #time, # otherwise move forward from #utc, for accuracy when moving across DST boundaries if duration_of_variable_length?(other) method_missing(:+, other) else result = utc.acts_like?(:date) ? utc.since(other) : utc + other rescue utc.since(other) result.in_time_zone(time_zone) end end |
#-(other) ⇒ Object
173 174 175 176 177 178 179 180 181 182 183 184 |
# File 'lib/active_support/time_with_zone.rb', line 173 def -(other) # If we're subtracting a Duration of variable length (i.e., years, months, days), move backwards from #time, # otherwise move backwards #utc, for accuracy when moving across DST boundaries if other.acts_like?(:time) utc - other elsif duration_of_variable_length?(other) method_missing(:-, other) else result = utc.acts_like?(:date) ? utc.ago(other) : utc - other rescue utc.ago(other) result.in_time_zone(time_zone) end end |
#<=>(other) ⇒ Object
Use the time in UTC for comparisons.
150 151 152 |
# File 'lib/active_support/time_with_zone.rb', line 150 def <=>(other) utc <=> other end |
#acts_like_time? ⇒ Boolean
So that self
acts_like?(:time)
.
246 247 248 |
# File 'lib/active_support/time_with_zone.rb', line 246 def acts_like_time? true end |
#advance(options) ⇒ Object
200 201 202 203 204 205 206 207 208 |
# File 'lib/active_support/time_with_zone.rb', line 200 def advance() # If we're advancing a value of variable length (i.e., years, weeks, months, days), advance from #time, # otherwise advance from #utc, for accuracy when moving across DST boundaries if .detect {|k,v| [:years, :weeks, :months, :days].include? k} method_missing(:advance, ) else utc.advance().in_time_zone(time_zone) end end |
#ago(other) ⇒ Object
196 197 198 |
# File 'lib/active_support/time_with_zone.rb', line 196 def ago(other) since(-other) end |
#between?(min, max) ⇒ Boolean
154 155 156 |
# File 'lib/active_support/time_with_zone.rb', line 154 def between?(min, max) utc.between?(min, max) end |
#dst? ⇒ Boolean Also known as: isdst
72 73 74 |
# File 'lib/active_support/time_with_zone.rb', line 72 def dst? period.dst? end |
#eql?(other) ⇒ Boolean
158 159 160 |
# File 'lib/active_support/time_with_zone.rb', line 158 def eql?(other) utc == other end |
#formatted_offset(colon = true, alternate_utc_string = nil) ⇒ Object
88 89 90 |
# File 'lib/active_support/time_with_zone.rb', line 88 def formatted_offset(colon = true, alternate_utc_string = nil) utc? && alternate_utc_string || utc_offset.to_utc_offset_s(colon) end |
#freeze ⇒ Object
256 257 258 259 |
# File 'lib/active_support/time_with_zone.rb', line 256 def freeze period; utc; time # preload instance variables before freezing super end |
#httpdate ⇒ Object
122 123 124 |
# File 'lib/active_support/time_with_zone.rb', line 122 def httpdate utc.httpdate end |
#in_time_zone(new_zone = ::Time.zone) ⇒ Object
Returns the simultaneous time in Time.zone
, or the specified zone.
61 62 63 64 |
# File 'lib/active_support/time_with_zone.rb', line 61 def in_time_zone(new_zone = ::Time.zone) return self if time_zone == new_zone utc.in_time_zone(new_zone) end |
#inspect ⇒ Object
97 98 99 |
# File 'lib/active_support/time_with_zone.rb', line 97 def inspect "#{time.strftime('%a, %d %b %Y %H:%M:%S')} #{zone} #{formatted_offset}" end |
#is_a?(klass) ⇒ Boolean Also known as: kind_of?
Say we’re a Time to thwart type checking.
251 252 253 |
# File 'lib/active_support/time_with_zone.rb', line 251 def is_a?(klass) klass == ::Time || super end |
#localtime ⇒ Object Also known as: getlocal
Returns a Time.local()
instance of the simultaneous time in your system’s ENV['TZ']
zone
67 68 69 |
# File 'lib/active_support/time_with_zone.rb', line 67 def localtime utc.getlocal end |
#marshal_dump ⇒ Object
261 262 263 |
# File 'lib/active_support/time_with_zone.rb', line 261 def marshal_dump [utc, time_zone.name, time] end |
#marshal_load(variables) ⇒ Object
265 266 267 |
# File 'lib/active_support/time_with_zone.rb', line 265 def marshal_load(variables) initialize(variables[0].utc, ::Time.send!(:get_zone, variables[1]), variables[2].utc) end |
#period ⇒ Object
Returns the underlying TZInfo::TimezonePeriod.
56 57 58 |
# File 'lib/active_support/time_with_zone.rb', line 56 def period @period ||= time_zone.period_for_utc(@utc) end |
#respond_to?(sym, include_priv = false) ⇒ Boolean
Ensure proxy class responds to all methods that underlying time instance responds to.
270 271 272 273 274 |
# File 'lib/active_support/time_with_zone.rb', line 270 def respond_to?(sym, include_priv = false) # consistently respond false to acts_like?(:date), regardless of whether #time is a Time or DateTime return false if sym.to_s == 'acts_like_date?' super || time.respond_to?(sym, include_priv) end |
#rfc2822 ⇒ Object Also known as: rfc822
126 127 128 |
# File 'lib/active_support/time_with_zone.rb', line 126 def rfc2822 to_s(:rfc822) end |
#since(other) ⇒ Object
186 187 188 189 190 191 192 193 194 |
# File 'lib/active_support/time_with_zone.rb', line 186 def since(other) # If we're adding a Duration of variable length (i.e., years, months, days), move forward from #time, # otherwise move forward from #utc, for accuracy when moving across DST boundaries if duration_of_variable_length?(other) method_missing(:since, other) else utc.since(other).in_time_zone(time_zone) end end |
#strftime(format) ⇒ Object
Replaces %Z
and %z
directives with zone
and formatted_offset
, respectively, before passing to Time#strftime, so that zone information is correct
144 145 146 147 |
# File 'lib/active_support/time_with_zone.rb', line 144 def strftime(format) format = format.gsub('%Z', zone).gsub('%z', formatted_offset(false)) time.strftime(format) end |
#time ⇒ Object
Returns a Time or DateTime instance that represents the time in time_zone
.
42 43 44 |
# File 'lib/active_support/time_with_zone.rb', line 42 def time @time ||= period.to_local(@utc) end |
#to_a ⇒ Object
222 223 224 |
# File 'lib/active_support/time_with_zone.rb', line 222 def to_a [time.sec, time.min, time.hour, time.day, time.mon, time.year, time.wday, time.yday, dst?, zone] end |
#to_datetime ⇒ Object
241 242 243 |
# File 'lib/active_support/time_with_zone.rb', line 241 def to_datetime utc.to_datetime.new_offset(Rational(utc_offset, 86_400)) end |
#to_f ⇒ Object
226 227 228 |
# File 'lib/active_support/time_with_zone.rb', line 226 def to_f utc.to_f end |
#to_i ⇒ Object Also known as: hash, tv_sec
230 231 232 |
# File 'lib/active_support/time_with_zone.rb', line 230 def to_i utc.to_i end |
#to_json(options = nil) ⇒ Object
106 107 108 109 110 111 112 |
# File 'lib/active_support/time_with_zone.rb', line 106 def to_json( = nil) if ActiveSupport.use_standard_json_time_format xmlschema.inspect else %("#{time.strftime("%Y/%m/%d %H:%M:%S")} #{formatted_offset(false)}") end end |
#to_s(format = :default) ⇒ Object
:db
format outputs time in UTC; all others output time in local. Uses TimeWithZone’s strftime
, so %Z
and %z
work correctly.
133 134 135 136 137 138 139 140 |
# File 'lib/active_support/time_with_zone.rb', line 133 def to_s(format = :default) return utc.to_s(format) if format == :db if formatter = ::Time::DATE_FORMATS[format] formatter.respond_to?(:call) ? formatter.call(self).to_s : strftime(formatter) else "#{time.strftime("%Y-%m-%d %H:%M:%S")} #{formatted_offset(false, 'UTC')}" # mimicking Ruby 1.9 Time#to_s format end end |
#to_time ⇒ Object
A TimeWithZone acts like a Time, so just return self
.
237 238 239 |
# File 'lib/active_support/time_with_zone.rb', line 237 def to_time self end |
#to_yaml(options = {}) ⇒ Object
114 115 116 117 118 119 120 |
# File 'lib/active_support/time_with_zone.rb', line 114 def to_yaml( = {}) if .kind_of?(YAML::Emitter) utc.to_yaml() else time.to_yaml().gsub('Z', formatted_offset(true, 'Z')) end end |
#usec ⇒ Object
218 219 220 |
# File 'lib/active_support/time_with_zone.rb', line 218 def usec time.respond_to?(:usec) ? time.usec : 0 end |
#utc ⇒ Object Also known as: comparable_time, getgm, getutc, gmtime
Returns a Time or DateTime instance that represents the time in UTC.
47 48 49 |
# File 'lib/active_support/time_with_zone.rb', line 47 def utc @utc ||= period.to_utc(@time) end |
#utc? ⇒ Boolean Also known as: gmt?
77 78 79 |
# File 'lib/active_support/time_with_zone.rb', line 77 def utc? time_zone.name == 'UTC' end |
#utc_offset ⇒ Object Also known as: gmt_offset, gmtoff
82 83 84 |
# File 'lib/active_support/time_with_zone.rb', line 82 def utc_offset period.utc_total_offset end |
#xmlschema ⇒ Object Also known as: iso8601
101 102 103 |
# File 'lib/active_support/time_with_zone.rb', line 101 def xmlschema "#{time.strftime("%Y-%m-%dT%H:%M:%S")}#{formatted_offset(true, 'Z')}" end |
#zone ⇒ Object
Time uses zone
to display the time zone abbreviation, so we’re duck-typing it.
93 94 95 |
# File 'lib/active_support/time_with_zone.rb', line 93 def zone period.zone_identifier.to_s end |