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 use methods local
, parse
, at
and now
on TimeZone
instances, and in_time_zone
on Time
and DateTime
instances.
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-10 15:30:45') # => Sat, 10 Feb 2007 15:30:45 EST -05:00
Time.zone.at(1171139445) # => 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 Time
and TimeZone
for further documentation of these methods.
TimeWithZone
instances implement the same API as Ruby Time
instances, so that Time
and TimeWithZone
instances are interchangeable.
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
Methods
- +
- -
- <=>
- acts_like_time?
- advance
- ago
- as_json
- between?
- blank?
- change
- comparable_time
- dst?
- eql?
- formatted_offset
- freeze
- future?
- getgm
- getlocal
- getutc
- gmt?
- gmt_offset
- gmtime
- gmtoff
- hash
- httpdate
- in
- in_time_zone
- inspect
- is_a?
- isdst
- iso8601
- kind_of?
- localtime
- marshal_dump
- marshal_load
- method_missing
- name
- new
- past?
- period
- respond_to?
- respond_to_missing?
- rfc2822
- rfc3339
- rfc822
- since
- strftime
- time
- to_a
- to_datetime
- to_f
- to_formatted_s
- to_i
- to_r
- to_s
- to_time
- today?
- tv_sec
- utc
- utc?
- utc_offset
- xmlschema
- zone
Constants
PRECISIONS | = | Hash.new { |h, n| h[n] = "%FT%T.%#{n}N".freeze } |
Attributes
[R] | time_zone |
Class Public methods
name()
Report class name as 'Time' to thwart type checking.
📝 Source code
# File activesupport/lib/active_support/time_with_zone.rb, line 42
def self.name
"Time"
end
🔎 See on GitHub
new(utc_time, time_zone, local_time = nil, period = nil)
📝 Source code
# File activesupport/lib/active_support/time_with_zone.rb, line 52
def initialize(utc_time, time_zone, local_time = nil, period = nil)
@utc = utc_time ? transfer_time_values_to_utc_constructor(utc_time) : nil
@time_zone, @time = time_zone, local_time
@period = @utc ? period : get_period_and_ensure_valid_local_time(period)
end
🔎 See on GitHub
Instance Public methods
+(other)
Adds an interval of time to the current object's time and returns that value as a new TimeWithZone
object.
Time.zone = 'Eastern Time (US & Canada)' # => 'Eastern Time (US & Canada)'
now = Time.zone.now # => Sun, 02 Nov 2014 01:26:28 EDT -04:00
now + 1000 # => Sun, 02 Nov 2014 01:43:08 EDT -04:00
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.
For instance, a time + 24.hours will advance exactly 24 hours, while a time + 1.day will advance 23-25 hours, depending on the day.
now + 24.hours # => Mon, 03 Nov 2014 00:26:28 EST -05:00
now + 1.day # => Mon, 03 Nov 2014 01:26:28 EST -05:00
📝 Source code
# File activesupport/lib/active_support/time_with_zone.rb, line 276
def +(other)
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
🔎 See on GitHub
-(other)
Returns a new TimeWithZone
object that represents the difference between the current object's time and the other
time.
Time.zone = 'Eastern Time (US & Canada)' # => 'Eastern Time (US & Canada)'
now = Time.zone.now # => Mon, 03 Nov 2014 00:26:28 EST -05:00
now - 1000 # => Mon, 03 Nov 2014 00:09:48 EST -05:00
If subtracting a Duration
of variable length (i.e., years, months, days), move backward from time
, otherwise move backward from utc
, for accuracy when moving across DST boundaries.
For instance, a time - 24.hours will go subtract exactly 24 hours, while a time - 1.day will subtract 23-25 hours, depending on the day.
now - 24.hours # => Sun, 02 Nov 2014 01:26:28 EDT -04:00
now - 1.day # => Sun, 02 Nov 2014 00:26:28 EDT -04:00
📝 Source code
# File activesupport/lib/active_support/time_with_zone.rb, line 303
def -(other)
if other.acts_like?(:time)
to_time - other.to_time
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
🔎 See on GitHub
<=>(other)
Use the time in UTC for comparisons.
📝 Source code
# File activesupport/lib/active_support/time_with_zone.rb, line 225
def <=>(other)
utc <=> other
end
🔎 See on GitHub
acts_like_time?()
So that self
acts_like?(:time)
.
📝 Source code
# File activesupport/lib/active_support/time_with_zone.rb, line 464
def acts_like_time?
true
end
🔎 See on GitHub
advance(options)
Uses Date
to provide precise Time
calculations for years, months, and days according to the proleptic Gregorian calendar. The result is returned as a new TimeWithZone
object.
The options
parameter takes a hash with any of these keys: :years
, :months
, :weeks
, :days
, :hours
, :minutes
, :seconds
.
If advancing by a value of variable length (i.e., years, weeks, months, days), move forward from time
, otherwise move forward from utc
, for accuracy when moving across DST boundaries.
Time.zone = 'Eastern Time (US & Canada)' # => 'Eastern Time (US & Canada)'
now = Time.zone.now # => Sun, 02 Nov 2014 01:26:28 EDT -04:00
now.advance(seconds: 1) # => Sun, 02 Nov 2014 01:26:29 EDT -04:00
now.advance(minutes: 1) # => Sun, 02 Nov 2014 01:27:28 EDT -04:00
now.advance(hours: 1) # => Sun, 02 Nov 2014 01:26:28 EST -05:00
now.advance(days: 1) # => Mon, 03 Nov 2014 01:26:28 EST -05:00
now.advance(weeks: 1) # => Sun, 09 Nov 2014 01:26:28 EST -05:00
now.advance(months: 1) # => Tue, 02 Dec 2014 01:26:28 EST -05:00
now.advance(years: 1) # => Mon, 02 Nov 2015 01:26:28 EST -05:00
📝 Source code
# File activesupport/lib/active_support/time_with_zone.rb, line 392
def advance(options)
# 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 options.values_at(:years, :weeks, :months, :days).any?
method_missing(:advance, options)
else
utc.advance(options).in_time_zone(time_zone)
end
end
🔎 See on GitHub
ago(other)
Subtracts an interval of time from the current object's time and returns the result as a new TimeWithZone
object.
Time.zone = 'Eastern Time (US & Canada)' # => 'Eastern Time (US & Canada)'
now = Time.zone.now # => Mon, 03 Nov 2014 00:26:28 EST -05:00
now.ago(1000) # => Mon, 03 Nov 2014 00:09:48 EST -05:00
If we're subtracting a Duration
of variable length (i.e., years, months, days), move backward from time
, otherwise move backward from utc
, for accuracy when moving across DST boundaries.
For instance, time.ago(24.hours)
will move back exactly 24 hours, while time.ago(1.day)
will move back 23-25 hours, depending on the day.
now.ago(24.hours) # => Sun, 02 Nov 2014 01:26:28 EDT -04:00
now.ago(1.day) # => Sun, 02 Nov 2014 00:26:28 EDT -04:00
📝 Source code
# File activesupport/lib/active_support/time_with_zone.rb, line 331
def ago(other)
since(-other)
end
🔎 See on GitHub
as_json(options = nil)
Coerces time to a string for JSON
encoding. The default format is ISO 8601. You can get %Y/%m/%d %H:%M:%S +offset style by setting ActiveSupport::JSON::Encoding.use_standard_json_time_format
to false
.
# With ActiveSupport::JSON::Encoding.use_standard_json_time_format = true
Time.utc(2005,2,1,15,15,10).in_time_zone("Hawaii").to_json
# => "2005-02-01T05:15:10.000-10:00"
# With ActiveSupport::JSON::Encoding.use_standard_json_time_format = false
Time.utc(2005,2,1,15,15,10).in_time_zone("Hawaii").to_json
# => "2005/02/01 05:15:10 -1000"
📝 Source code
# File activesupport/lib/active_support/time_with_zone.rb, line 167
def as_json(options = nil)
if ActiveSupport::JSON::Encoding.use_standard_json_time_format
xmlschema(ActiveSupport::JSON::Encoding.time_precision)
else
%(#{time.strftime("%Y/%m/%d %H:%M:%S")} #{formatted_offset(false)})
end
end
🔎 See on GitHub
between?(min, max)
Returns true if the current object's time is within the specified min
and max
time.
📝 Source code
# File activesupport/lib/active_support/time_with_zone.rb, line 231
def between?(min, max)
utc.between?(min, max)
end
🔎 See on GitHub
blank?()
An instance of ActiveSupport::TimeWithZone
is never blank
📝 Source code
# File activesupport/lib/active_support/time_with_zone.rb, line 475
def blank?
false
end
🔎 See on GitHub
change(options)
Returns a new ActiveSupport::TimeWithZone
where one or more of the elements have been changed according to the options
parameter. The time options (:hour
, :min
, :sec
, :usec
, :nsec
) reset cascadingly, so if only the hour is passed, then minute, sec, usec and nsec is set to 0. If the hour and minute is passed, then sec, usec and nsec is set to 0. The options
parameter takes a hash with any of these keys: :year
, :month
, :day
, :hour
, :min
, :sec
, :usec
, :nsec
, :offset
, :zone
. Pass either :usec
or :nsec
, not both. Similarly, pass either :zone
or :offset
, not both.
t = Time.zone.now # => Fri, 14 Apr 2017 11:45:15 EST -05:00
t.change(year: 2020) # => Tue, 14 Apr 2020 11:45:15 EST -05:00
t.change(hour: 12) # => Fri, 14 Apr 2017 12:00:00 EST -05:00
t.change(min: 30) # => Fri, 14 Apr 2017 11:30:00 EST -05:00
t.change(offset: "-10:00") # => Fri, 14 Apr 2017 11:45:15 HST -10:00
t.change(zone: "Hawaii") # => Fri, 14 Apr 2017 11:45:15 HST -10:00
📝 Source code
# File activesupport/lib/active_support/time_with_zone.rb, line 352
def change(options)
if options[:zone] && options[:offset]
raise ArgumentError, "Can't change both :offset and :zone at the same time: #{options.inspect}"
end
new_time = time.change(options)
if options[:zone]
new_zone = ::Time.find_zone(options[:zone])
elsif options[:offset]
new_zone = ::Time.find_zone(new_time.utc_offset)
end
new_zone ||= time_zone
periods = new_zone.periods_for_local(new_time)
self.class.new(nil, new_zone, new_time, periods.include?(period) ? period : nil)
end
🔎 See on GitHub
dst?()
Returns true if the current time is within Daylight Savings Time
for the specified time zone.
Time.zone = 'Eastern Time (US & Canada)' # => 'Eastern Time (US & Canada)'
Time.zone.parse("2012-5-30").dst? # => true
Time.zone.parse("2012-11-30").dst? # => false
📝 Source code
# File activesupport/lib/active_support/time_with_zone.rb, line 95
def dst?
period.dst?
end
🔎 See on GitHub
eql?(other)
Returns true
if other
is equal to current object.
📝 Source code
# File activesupport/lib/active_support/time_with_zone.rb, line 252
def eql?(other)
other.eql?(utc)
end
🔎 See on GitHub
formatted_offset(colon = true, alternate_utc_string = nil)
Returns a formatted string of the offset from UTC, or an alternative string if the time zone is already UTC.
Time.zone = 'Eastern Time (US & Canada)' # => "Eastern Time (US & Canada)"
Time.zone.now.formatted_offset(true) # => "-05:00"
Time.zone.now.formatted_offset(false) # => "-0500"
Time.zone = 'UTC' # => "UTC"
Time.zone.now.formatted_offset(true, "0") # => "0"
📝 Source code
# File activesupport/lib/active_support/time_with_zone.rb, line 126
def formatted_offset(colon = true, alternate_utc_string = nil)
utc? && alternate_utc_string || TimeZone.seconds_to_utc_offset(utc_offset, colon)
end
🔎 See on GitHub
freeze()
📝 Source code
# File activesupport/lib/active_support/time_with_zone.rb, line 479
def freeze
# preload instance variables before freezing
period; utc; time; to_datetime; to_time
super
end
🔎 See on GitHub
future?()
Returns true if the current object's time is in the future.
📝 Source code
# File activesupport/lib/active_support/time_with_zone.rb, line 247
def future?
utc.future?
end
🔎 See on GitHub
hash()
📝 Source code
# File activesupport/lib/active_support/time_with_zone.rb, line 256
def hash
utc.hash
end
🔎 See on GitHub
httpdate()
Returns a string of the object's date and time in the format used by HTTP requests.
Time.zone.now.httpdate # => "Tue, 01 Jan 2013 04:39:43 GMT"
📝 Source code
# File activesupport/lib/active_support/time_with_zone.rb, line 188
def httpdate
utc.httpdate
end
🔎 See on GitHub
in_time_zone(new_zone = ::Time.zone)
Returns the simultaneous time in Time.zone
, or the specified zone.
📝 Source code
# File activesupport/lib/active_support/time_with_zone.rb, line 78
def in_time_zone(new_zone = ::Time.zone)
return self if time_zone == new_zone
utc.in_time_zone(new_zone)
end
🔎 See on GitHub
inspect()
Returns a string of the object's date, time, zone, and offset from UTC.
Time.zone.now.inspect # => "Thu, 04 Dec 2014 11:00:25 EST -05:00"
📝 Source code
# File activesupport/lib/active_support/time_with_zone.rb, line 141
def inspect
"#{time.strftime('%a, %d %b %Y %H:%M:%S')} #{zone} #{formatted_offset}"
end
🔎 See on GitHub
is_a?(klass)
Say we're a Time
to thwart type checking.
📝 Source code
# File activesupport/lib/active_support/time_with_zone.rb, line 469
def is_a?(klass)
klass == ::Time || super
end
🔎 See on GitHub
localtime(utc_offset = nil)
Returns a Time
instance of the simultaneous time in the system timezone.
📝 Source code
# File activesupport/lib/active_support/time_with_zone.rb, line 84
def localtime(utc_offset = nil)
utc.getlocal(utc_offset)
end
🔎 See on GitHub
marshal_dump()
📝 Source code
# File activesupport/lib/active_support/time_with_zone.rb, line 485
def marshal_dump
[utc, time_zone.name, time]
end
🔎 See on GitHub
marshal_load(variables)
📝 Source code
# File activesupport/lib/active_support/time_with_zone.rb, line 489
def marshal_load(variables)
initialize(variables[0].utc, ::Time.find_zone(variables[1]), variables[2].utc)
end
🔎 See on GitHub
method_missing(sym, *args, &block)
Send the missing method to time
instance, and wrap result in a new TimeWithZone
with the existing time_zone
.
📝 Source code
# File activesupport/lib/active_support/time_with_zone.rb, line 510
def method_missing(sym, *args, &block)
wrap_with_time_zone time.__send__(sym, *args, &block)
rescue NoMethodError => e
raise e, e.message.sub(time.inspect, inspect), e.backtrace
end
🔎 See on GitHub
past?()
Returns true if the current object's time is in the past.
📝 Source code
# File activesupport/lib/active_support/time_with_zone.rb, line 236
def past?
utc.past?
end
🔎 See on GitHub
period()
Returns the underlying TZInfo::TimezonePeriod.
📝 Source code
# File activesupport/lib/active_support/time_with_zone.rb, line 73
def period
@period ||= time_zone.period_for_utc(@utc)
end
🔎 See on GitHub
respond_to?(sym, include_priv = false)
respond_to_missing? is not called in some cases, such as when type conversion is performed with Kernel#String
📝 Source code
# File activesupport/lib/active_support/time_with_zone.rb, line 495
def respond_to?(sym, include_priv = false)
# ensure that we're not going to throw and rescue from NoMethodError in method_missing which is slow
return false if sym.to_sym == :to_str
super
end
🔎 See on GitHub
respond_to_missing?(sym, include_priv)
Ensure proxy class responds to all methods that underlying time instance responds to.
📝 Source code
# File activesupport/lib/active_support/time_with_zone.rb, line 503
def respond_to_missing?(sym, include_priv)
return false if sym.to_sym == :acts_like_date?
time.respond_to?(sym, include_priv)
end
🔎 See on GitHub
rfc2822()
Returns a string of the object's date and time in the RFC 2822 standard format.
Time.zone.now.rfc2822 # => "Tue, 01 Jan 2013 04:51:39 +0000"
📝 Source code
# File activesupport/lib/active_support/time_with_zone.rb, line 196
def rfc2822
to_s(:rfc822)
end
🔎 See on GitHub
strftime(format)
Replaces %Z
directive with +zone before passing to Time#strftime, so that zone information is correct.
📝 Source code
# File activesupport/lib/active_support/time_with_zone.rb, line 219
def strftime(format)
format = format.gsub(/((?:\A|[^%])(?:%%)*)%Z/, "\\1#{zone}")
getlocal(utc_offset).strftime(format)
end
🔎 See on GitHub
time()
Returns a Time
instance that represents the time in time_zone
.
📝 Source code
# File activesupport/lib/active_support/time_with_zone.rb, line 59
def time
@time ||= period.to_local(@utc)
end
🔎 See on GitHub
to_a()
Returns Array
of parts of Time
in sequence of [seconds, minutes, hours, day, month, year, weekday, yearday, dst?, zone].
now = Time.zone.now # => Tue, 18 Aug 2015 02:29:27 UTC +00:00
now.to_a # => [27, 29, 2, 18, 8, 2015, 2, 230, false, "UTC"]
📝 Source code
# File activesupport/lib/active_support/time_with_zone.rb, line 415
def to_a
[time.sec, time.min, time.hour, time.day, time.mon, time.year, time.wday, time.yday, dst?, zone]
end
🔎 See on GitHub
to_datetime()
Returns an instance of DateTime
with the timezone's UTC offset
Time.zone.now.to_datetime # => Tue, 18 Aug 2015 02:32:20 +0000
Time.current.in_time_zone('Hawaii').to_datetime # => Mon, 17 Aug 2015 16:32:20 -1000
📝 Source code
# File activesupport/lib/active_support/time_with_zone.rb, line 448
def to_datetime
@to_datetime ||= utc.to_datetime.new_offset(Rational(utc_offset, 86_400))
end
🔎 See on GitHub
to_f()
Returns the object's date and time as a floating point number of seconds since the Epoch (January 1, 1970 00:00 UTC).
Time.zone.now.to_f # => 1417709320.285418
📝 Source code
# File activesupport/lib/active_support/time_with_zone.rb, line 423
def to_f
utc.to_f
end
🔎 See on GitHub
to_i()
Returns the object's date and time as an integer number of seconds since the Epoch (January 1, 1970 00:00 UTC).
Time.zone.now.to_i # => 1417709320
📝 Source code
# File activesupport/lib/active_support/time_with_zone.rb, line 431
def to_i
utc.to_i
end
🔎 See on GitHub
to_r()
Returns the object's date and time as a rational number of seconds since the Epoch (January 1, 1970 00:00 UTC).
Time.zone.now.to_r # => (708854548642709/500000)
📝 Source code
# File activesupport/lib/active_support/time_with_zone.rb, line 440
def to_r
utc.to_r
end
🔎 See on GitHub
to_s(format = :default)
Returns a string of the object's date and time. Accepts an optional format
:
-
:default
- default value, mimics RubyTime#to_s
format. -
:db
- format outputs time in UTC :db time. SeeTime#to_formatted_s
(:db). -
Any key in
Time::DATE_FORMATS
can be used. See active_support/core_ext/time/conversions.rb.
📝 Source code
# File activesupport/lib/active_support/time_with_zone.rb, line 206
def to_s(format = :default)
if format == :db
utc.to_s(format)
elsif 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 Time#to_s format
end
end
🔎 See on GitHub
to_time()
Returns an instance of Time
, either with the same UTC offset as self
or in the local system timezone depending on the setting of ActiveSupport.to_time_preserves_timezone
.
📝 Source code
# File activesupport/lib/active_support/time_with_zone.rb, line 455
def to_time
if preserve_timezone
@to_time_with_instance_offset ||= getlocal(utc_offset)
else
@to_time_with_system_offset ||= getlocal
end
end
🔎 See on GitHub
today?()
Returns true if the current object's time falls within the current day.
📝 Source code
# File activesupport/lib/active_support/time_with_zone.rb, line 242
def today?
time.today?
end
🔎 See on GitHub
utc()
Returns a Time
instance of the simultaneous time in the UTC timezone.
📝 Source code
# File activesupport/lib/active_support/time_with_zone.rb, line 64
def utc
@utc ||= period.to_utc(@time)
end
🔎 See on GitHub
utc?()
Returns true if the current time zone is set to UTC.
Time.zone = 'UTC' # => 'UTC'
Time.zone.now.utc? # => true
Time.zone = 'Eastern Time (US & Canada)' # => 'Eastern Time (US & Canada)'
Time.zone.now.utc? # => false
📝 Source code
# File activesupport/lib/active_support/time_with_zone.rb, line 106
def utc?
period.offset.abbreviation == :UTC || period.offset.abbreviation == :UCT
end
🔎 See on GitHub
utc_offset()
Returns the offset from current time to UTC time in seconds.
📝 Source code
# File activesupport/lib/active_support/time_with_zone.rb, line 112
def utc_offset
period.utc_total_offset
end
🔎 See on GitHub
xmlschema(fraction_digits = 0)
Returns a string of the object's date and time in the ISO 8601 standard format.
Time.zone.now.xmlschema # => "2014-12-04T11:02:37-05:00"
📝 Source code
# File activesupport/lib/active_support/time_with_zone.rb, line 149
def xmlschema(fraction_digits = 0)
"#{time.strftime(PRECISIONS[fraction_digits.to_i])}#{formatted_offset(true, 'Z'.freeze)}"
end
🔎 See on GitHub
zone()
Returns the time zone abbreviation.
Time.zone = 'Eastern Time (US & Canada)' # => "Eastern Time (US & Canada)"
Time.zone.now.zone # => "EST"
📝 Source code
# File activesupport/lib/active_support/time_with_zone.rb, line 134
def zone
period.zone_identifier.to_s
end
🔎 See on GitHub