class ActiveSupport::TimeWithZone
Active Support Time With Zone
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.000000000 EST -05:00
Time.zone.parse('2007-02-10 15:30:45') # => Sat, 10 Feb 2007 15:30:45.000000000 EST -05:00
Time.zone.at(1171139445) # => Sat, 10 Feb 2007 15:30:45.000000000 EST -05:00
Time.zone.now # => Sun, 18 May 2008 13:07:55.754107581 EDT -04:00
Time.utc(2007, 2, 10, 20, 30, 45).in_time_zone # => Sat, 10 Feb 2007 15:30:45.000000000 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.031505668 EDT -04:00
t.hour # => 13
t.dst? # => true
t.utc_offset # => -14400
t.zone # => "EDT"
t.to_fs(:rfc822) # => "Sun, 18 May 2008 13:27:25 -0400"
t + 1.day # => Mon, 19 May 2008 13:27:25.031505668 EDT -04:00
t.beginning_of_year # => Tue, 01 Jan 2008 00:00:00.000000000 EST -05:00
t > Time.utc(1999) # => true
t.is_a?(Time) # => true
t.is_a?(ActiveSupport::TimeWithZone) # => true
Constants
Attributes
[R] | time_zone |
Public class methods
Source code GitHub
# File activesupport/lib/active_support/time_with_zone.rb, line 51
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
Public instance methods
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.725182881 EDT -04:00
now + 1000 # => Sun, 02 Nov 2014 01:43:08.725182881 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.725182881 EST -05:00
now + 1.day # => Mon, 03 Nov 2014 01:26:28.725182881 EST -05:00
Source code GitHub
# File activesupport/lib/active_support/time_with_zone.rb, line 298
def +(other)
if duration_of_variable_length?(other)
method_missing(:+, other)
else
begin
result = utc + other
rescue TypeError
result = utc.to_datetime.since(other)
ActiveSupport.deprecator.warn(
"Adding an instance of #{other.class} to an instance of #{self.class} is deprecated. This behavior will raise " \
"a `TypeError` in Rails 8.1."
)
result.in_time_zone(time_zone)
end
result.in_time_zone(time_zone)
end
end
Subtracts an interval of time and returns a new TimeWithZone
object unless the other value acts_like?
time. In which case, it will subtract the other time and return the difference in seconds as a Float.
Time.zone = 'Eastern Time (US & Canada)' # => 'Eastern Time (US & Canada)'
now = Time.zone.now # => Mon, 03 Nov 2014 00:26:28.725182881 EST -05:00
now - 1000 # => Mon, 03 Nov 2014 00:09:48.725182881 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.725182881 EDT -04:00
now - 1.day # => Sun, 02 Nov 2014 00:26:28.725182881 EDT -04:00
If both the TimeWithZone
object and the other value act like Time, a Float will be returned.
Time.zone.now - 1.day.ago # => 86399.999967
Source code GitHub
# File activesupport/lib/active_support/time_with_zone.rb, line 341
def -(other)
if other.acts_like?(:time)
getutc - other.getutc
elsif duration_of_variable_length?(other)
method_missing(:-, other)
else
result = utc - other
result.in_time_zone(time_zone)
end
end
Use the time in UTC for comparisons.
Source code GitHub
# File activesupport/lib/active_support/time_with_zone.rb, line 231
def <=>(other)
utc <=> other
end
So that self
acts_like?(:time)
.
Source code GitHub
# File activesupport/lib/active_support/time_with_zone.rb, line 504
def acts_like_time?
true
end
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.558049687 EDT -04:00
now.advance(seconds: 1) # => Sun, 02 Nov 2014 01:26:29.558049687 EDT -04:00
now.advance(minutes: 1) # => Sun, 02 Nov 2014 01:27:28.558049687 EDT -04:00
now.advance(hours: 1) # => Sun, 02 Nov 2014 01:26:28.558049687 EST -05:00
now.advance(days: 1) # => Mon, 03 Nov 2014 01:26:28.558049687 EST -05:00
now.advance(weeks: 1) # => Sun, 09 Nov 2014 01:26:28.558049687 EST -05:00
now.advance(months: 1) # => Tue, 02 Dec 2014 01:26:28.558049687 EST -05:00
now.advance(years: 1) # => Mon, 02 Nov 2015 01:26:28.558049687 EST -05:00
Source code GitHub
# File activesupport/lib/active_support/time_with_zone.rb, line 430
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
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.725182881 EST -05:00
now.ago(1000) # => Mon, 03 Nov 2014 00:09:48.725182881 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.725182881 EDT -04:00
now.ago(1.day) # => Sun, 02 Nov 2014 00:26:28.725182881 EDT -04:00
Source code GitHub
# File activesupport/lib/active_support/time_with_zone.rb, line 369
def ago(other)
since(-other)
end
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").as_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").as_json
# => "2005/02/01 05:15:10 -1000"
Source code GitHub
# File activesupport/lib/active_support/time_with_zone.rb, line 166
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
Returns true if the current object’s time is within the specified min
and max
time.
Source code GitHub
# File activesupport/lib/active_support/time_with_zone.rb, line 239
def between?(min, max)
utc.between?(min, max)
end
An instance of ActiveSupport::TimeWithZone
is never blank
Source code GitHub
# File activesupport/lib/active_support/time_with_zone.rb, line 515
def blank?
false
end
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.116992711 EST -05:00
t.change(year: 2020) # => Tue, 14 Apr 2020 11:45:15.116992711 EST -05:00
t.change(hour: 12) # => Fri, 14 Apr 2017 12:00:00.000000000 EST -05:00
t.change(min: 30) # => Fri, 14 Apr 2017 11:30:00.000000000 EST -05:00
t.change(offset: "-10:00") # => Fri, 14 Apr 2017 11:45:15.116992711 HST -10:00
t.change(zone: "Hawaii") # => Fri, 14 Apr 2017 11:45:15.116992711 HST -10:00
Source code GitHub
# File activesupport/lib/active_support/time_with_zone.rb, line 390
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
Alias for:
utc
.
Also aliased as:
isdst
.
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 GitHub
# File activesupport/lib/active_support/time_with_zone.rb, line 94
def dst?
period.dst?
end
Returns true
if other
is equal to current object.
Source code GitHub
# File activesupport/lib/active_support/time_with_zone.rb, line 274
def eql?(other)
other.eql?(utc)
end
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 GitHub
# File activesupport/lib/active_support/time_with_zone.rb, line 125
def formatted_offset(colon = true, alternate_utc_string = nil)
utc? && alternate_utc_string || TimeZone.seconds_to_utc_offset(utc_offset, colon)
end
Source code GitHub
# File activesupport/lib/active_support/time_with_zone.rb, line 523
def freeze
# preload instance variables before freezing
period; utc; time; to_datetime; to_time
super
end
Returns true if the current object’s time is in the future.
Source code GitHub
# File activesupport/lib/active_support/time_with_zone.rb, line 269
def future?
utc.future?
end
Alias for:
utc
.
Alias for:
localtime
.
Alias for:
utc
.
Alias for:
utc?
.
Alias for:
utc_offset
.
Alias for:
utc
.
Alias for:
utc_offset
.
Source code GitHub
# File activesupport/lib/active_support/time_with_zone.rb, line 278
def hash
utc.hash
end
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 GitHub
# File activesupport/lib/active_support/time_with_zone.rb, line 186
def httpdate
utc.httpdate
end
Alias for:
+
.
Returns the simultaneous time in Time.zone
, or the specified zone.
Source code GitHub
# File activesupport/lib/active_support/time_with_zone.rb, line 77
def in_time_zone(new_zone = ::Time.zone)
return self if time_zone == new_zone
utc.in_time_zone(new_zone)
end
Returns a string of the object’s date, time, zone, and offset from UTC.
Time.zone.now.inspect # => "2024-11-13 07:00:10.528054960 UTC +00:00"
Source code GitHub
# File activesupport/lib/active_support/time_with_zone.rb, line 140
def inspect
"#{time.strftime('%F %H:%M:%S.%9N')} #{zone} #{formatted_offset}"
end
Also aliased as:
kind_of?
.
Say we’re a Time to thwart type checking.
Source code GitHub
# File activesupport/lib/active_support/time_with_zone.rb, line 509
def is_a?(klass)
klass == ::Time || super
end
Alias for:
dst?
.
Alias for:
xmlschema
.
Alias for:
is_a?
.
Also aliased as:
getlocal
.
Returns a Time
instance of the simultaneous time in the system timezone.
Source code GitHub
# File activesupport/lib/active_support/time_with_zone.rb, line 83
def localtime(utc_offset = nil)
utc.getlocal(utc_offset)
end
Source code GitHub
# File activesupport/lib/active_support/time_with_zone.rb, line 529
def marshal_dump
[utc, time_zone.name, time]
end
Source code GitHub
# File activesupport/lib/active_support/time_with_zone.rb, line 533
def marshal_load(variables)
initialize(variables[0].utc, ::Time.find_zone(variables[1]), variables[2].utc)
end
Send the missing method to time
instance, and wrap result in a new TimeWithZone
with the existing time_zone
.
Source code GitHub
# File activesupport/lib/active_support/time_with_zone.rb, line 553
def method_missing(...)
wrap_with_time_zone time.__send__(...)
rescue NoMethodError => e
raise e, e.message.sub(time.inspect, inspect).sub("Time", "ActiveSupport::TimeWithZone"), e.backtrace
end
Alias for:
tomorrow?
.
Returns true if the current object’s time is in the past.
Source code GitHub
# File activesupport/lib/active_support/time_with_zone.rb, line 244
def past?
utc.past?
end
Returns the underlying TZInfo::TimezonePeriod
.
Source code GitHub
# File activesupport/lib/active_support/time_with_zone.rb, line 72
def period
@period ||= time_zone.period_for_utc(@utc)
end
Alias for:
yesterday?
.
respond_to_missing? is not called in some cases, such as when type conversion is performed with Kernel#String
Source code GitHub
# File activesupport/lib/active_support/time_with_zone.rb, line 539
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
Ensure proxy class responds to all methods that underlying time instance responds to.
Source code GitHub
# File activesupport/lib/active_support/time_with_zone.rb, line 547
def respond_to_missing?(sym, include_priv)
time.respond_to?(sym, include_priv)
end
Also aliased as:
rfc822
.
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 GitHub
# File activesupport/lib/active_support/time_with_zone.rb, line 194
def rfc2822
to_fs(:rfc822)
end
Alias for:
xmlschema
.
Alias for:
rfc2822
.
Alias for:
+
.
Replaces %Z
directive with +zone before passing to Time#strftime, so that zone information is correct.
Source code GitHub
# File activesupport/lib/active_support/time_with_zone.rb, line 225
def strftime(format)
format = format.gsub(/((?:\A|[^%])(?:%%)*)%Z/, "\\1#{zone}")
getlocal(utc_offset).strftime(format)
end
Returns a Time
instance that represents the time in time_zone
.
Source code GitHub
# File activesupport/lib/active_support/time_with_zone.rb, line 58
def time
@time ||= incorporate_utc_offset(@utc, utc_offset)
end
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.485278555 UTC +00:00
now.to_a # => [27, 29, 2, 18, 8, 2015, 2, 230, false, "UTC"]
Source code GitHub
# File activesupport/lib/active_support/time_with_zone.rb, line 453
def to_a
[time.sec, time.min, time.hour, time.day, time.mon, time.year, time.wday, time.yday, dst?, zone]
end
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 GitHub
# File activesupport/lib/active_support/time_with_zone.rb, line 486
def to_datetime
@to_datetime ||= utc.to_datetime.new_offset(Rational(utc_offset, 86_400))
end
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 GitHub
# File activesupport/lib/active_support/time_with_zone.rb, line 461
def to_f
utc.to_f
end
Alias for:
to_fs
.
Also aliased as:
to_formatted_s
.
Returns a string of the object’s date and time.
This method is aliased to to_formatted_s
.
Accepts an optional format
:
-
:default
- default value, mimics Ruby Time#to_s format. -
:db
- format outputs time in UTC :db time. SeeTime#to_fs
(:db). -
Any key in
Time::DATE_FORMATS
can be used. See active_support/core_ext/time/conversions.rb.
Source code GitHub
# File activesupport/lib/active_support/time_with_zone.rb, line 212
def to_fs(format = :default)
if format == :db
utc.to_fs(format)
elsif formatter = ::Time::DATE_FORMATS[format]
formatter.respond_to?(:call) ? formatter.call(self).to_s : strftime(formatter)
else
to_s
end
end
Also aliased as:
tv_sec
.
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 GitHub
# File activesupport/lib/active_support/time_with_zone.rb, line 469
def to_i
utc.to_i
end
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 GitHub
# File activesupport/lib/active_support/time_with_zone.rb, line 478
def to_r
utc.to_r
end
Returns a string of the object’s date and time.
Source code GitHub
# File activesupport/lib/active_support/time_with_zone.rb, line 200
def to_s
"#{time.strftime("%Y-%m-%d %H:%M:%S")} #{formatted_offset(false, 'UTC')}" # mimicking Ruby Time#to_s format
end
Returns an instance of Time
, either with the same timezone as self
, 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 GitHub
# File activesupport/lib/active_support/time_with_zone.rb, line 493
def to_time
if preserve_timezone == :zone
@to_time_with_timezone ||= getlocal(time_zone)
elsif preserve_timezone
@to_time_with_instance_offset ||= getlocal(utc_offset)
else
@to_time_with_system_offset ||= getlocal
end
end
Returns true if the current object’s time falls within the current day.
Source code GitHub
# File activesupport/lib/active_support/time_with_zone.rb, line 250
def today?
time.today?
end
Also aliased as:
next_day?
.
Returns true if the current object’s time falls within the next day (tomorrow).
Source code GitHub
# File activesupport/lib/active_support/time_with_zone.rb, line 256
def tomorrow?
time.tomorrow?
end
Alias for:
to_i
.
Also aliased as:
comparable_time
, getgm
, getutc
, gmtime
.
Returns a Time
instance of the simultaneous time in the UTC timezone.
Source code GitHub
# File activesupport/lib/active_support/time_with_zone.rb, line 63
def utc
@utc ||= incorporate_utc_offset(@time, -utc_offset)
end
Also aliased as:
gmt?
.
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 GitHub
# File activesupport/lib/active_support/time_with_zone.rb, line 105
def utc?
zone == "UTC" || zone == "UCT"
end
Also aliased as:
gmt_offset
, gmtoff
.
Returns the offset from current time to UTC time in seconds.
Source code GitHub
# File activesupport/lib/active_support/time_with_zone.rb, line 111
def utc_offset
period.observed_utc_offset
end
Also aliased as:
iso8601
, rfc3339
.
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 GitHub
# File activesupport/lib/active_support/time_with_zone.rb, line 148
def xmlschema(fraction_digits = 0)
"#{time.strftime(PRECISIONS[fraction_digits.to_i])}#{formatted_offset(true, 'Z')}"
end
Also aliased as:
prev_day?
.
Returns true if the current object’s time falls within the previous day (yesterday).
Source code GitHub
# File activesupport/lib/active_support/time_with_zone.rb, line 263
def yesterday?
time.yesterday?
end
Returns the time zone abbreviation.
Time.zone = 'Eastern Time (US & Canada)' # => "Eastern Time (US & Canada)"
Time.zone.now.zone # => "EST"
Source code GitHub
# File activesupport/lib/active_support/time_with_zone.rb, line 133
def zone
period.abbreviation
end