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
If wrapped
time
is a DateTime, use DateTime#since instead of+
. -
#-(other) ⇒ Object
If a time-like object is passed in, compare it with
utc
. -
#<=>(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
Neuter freeze because freezing can cause problems with lazy loading of attributes.
- #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
.
260 261 262 263 |
# File 'lib/active_support/time_with_zone.rb', line 260 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
If wrapped time
is a DateTime, use DateTime#since instead of +
. Otherwise, just pass on to method_missing
.
164 165 166 167 |
# File 'lib/active_support/time_with_zone.rb', line 164 def +(other) result = utc.acts_like?(:date) ? utc.since(other) : utc + other rescue utc.since(other) result.in_time_zone(time_zone) end |
#-(other) ⇒ Object
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
.
172 173 174 175 176 177 178 179 |
# File 'lib/active_support/time_with_zone.rb', line 172 def -(other) if other.acts_like?(:time) utc - 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)
.
229 230 231 |
# File 'lib/active_support/time_with_zone.rb', line 229 def acts_like_time? true end |
#advance(options) ⇒ Object
189 190 191 |
# File 'lib/active_support/time_with_zone.rb', line 189 def advance() utc.advance().in_time_zone(time_zone) end |
#ago(other) ⇒ Object
185 186 187 |
# File 'lib/active_support/time_with_zone.rb', line 185 def ago(other) utc.ago(other).in_time_zone(time_zone) 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
Neuter freeze because freezing can cause problems with lazy loading of attributes.
240 241 242 |
# File 'lib/active_support/time_with_zone.rb', line 240 def freeze self 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.
234 235 236 |
# File 'lib/active_support/time_with_zone.rb', line 234 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
244 245 246 |
# File 'lib/active_support/time_with_zone.rb', line 244 def marshal_dump [utc, time_zone.name, time] end |
#marshal_load(variables) ⇒ Object
248 249 250 |
# File 'lib/active_support/time_with_zone.rb', line 248 def marshal_load(variables) initialize(variables[0], ::Time.send!(:get_zone, variables[1]), variables[2]) 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.
253 254 255 256 257 |
# File 'lib/active_support/time_with_zone.rb', line 253 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
181 182 183 |
# File 'lib/active_support/time_with_zone.rb', line 181 def since(other) utc.since(other).in_time_zone(time_zone) 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
205 206 207 |
# File 'lib/active_support/time_with_zone.rb', line 205 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
224 225 226 |
# File 'lib/active_support/time_with_zone.rb', line 224 def to_datetime utc.to_datetime.new_offset(Rational(utc_offset, 86_400)) end |
#to_f ⇒ Object
209 210 211 |
# File 'lib/active_support/time_with_zone.rb', line 209 def to_f utc.to_f end |
#to_i ⇒ Object Also known as: hash, tv_sec
213 214 215 |
# File 'lib/active_support/time_with_zone.rb', line 213 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
.
220 221 222 |
# File 'lib/active_support/time_with_zone.rb', line 220 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
201 202 203 |
# File 'lib/active_support/time_with_zone.rb', line 201 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 |