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
- #
- A
- B
- C
- D
- E
- F
- G
- H
- I
- K
- L
- M
- N
- P
- R
- S
- T
- U
- X
- Y
- Z
Constants
PRECISIONS | = | Hash.new { |h, n| h[n] = "%FT%T.%#{n}N" } |
SECONDS_PER_DAY | = | 86400 |
Attributes
[R] | time_zone |
Class Public methods
name() Link
Report class name as 'Time' to thwart type checking.
# File activesupport/lib/active_support/time_with_zone.rb, line 44 def self.name ActiveSupport::Deprecation.warn(<<~EOM) ActiveSupport::TimeWithZone.name has been deprecated and from Rails 7.1 will use the default Ruby implementation. You can set `config.active_support.remove_deprecated_time_with_zone_name = true` to enable the new behavior now. EOM "Time" end
new(utc_time, time_zone, local_time = nil, period = nil) Link
# File activesupport/lib/active_support/time_with_zone.rb, line 61 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
Instance Public methods
+(other) Link
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
# File activesupport/lib/active_support/time_with_zone.rb, line 328 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
-(other) Link
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
# File activesupport/lib/active_support/time_with_zone.rb, line 362 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
<=>(other) Link
Use the time in UTC for comparisons.
acts_like_time?() Link
So that self
acts_like?(:time)
.
advance(options) Link
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
# File activesupport/lib/active_support/time_with_zone.rb, line 451 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
ago(other) Link
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
as_json(options = nil) Link
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"
# File activesupport/lib/active_support/time_with_zone.rb, line 176 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
between?(min, max) Link
Returns true if the current object's time is within the specified min
and max
time.
blank?() Link
An instance of ActiveSupport::TimeWithZone
is never blank
change(options) Link
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.116992711 EST -05:00
t.change(min: 30) # => Fri, 14 Apr 2017 11:30:00.116992711 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
# File activesupport/lib/active_support/time_with_zone.rb, line 411 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
dst?() Link
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
eql?(other) Link
Returns true
if other
is equal to current object.
formatted_offset(colon = true, alternate_utc_string = nil) Link
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"
freeze() Link
future?() Link
Returns true if the current object's time is in the future.
hash() Link
httpdate() Link
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"
in_time_zone(new_zone = ::Time.zone) Link
Returns the simultaneous time in Time.zone
, or the specified zone.
inspect() Link
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.624541392 EST -05:00"
localtime(utc_offset = nil) Link
Returns a Time
instance of the simultaneous time in the system timezone.
marshal_dump() Link
marshal_load(variables) Link
method_missing(sym, *args, &block) Link
Send the missing method to time
instance, and wrap result in a new TimeWithZone
with the existing time_zone
.
# File activesupport/lib/active_support/time_with_zone.rb, line 569 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).sub("Time", "ActiveSupport::TimeWithZone"), e.backtrace end
past?() Link
Returns true if the current object's time is in the past.
period() Link
Returns the underlying TZInfo::TimezonePeriod
.
respond_to?(sym, include_priv = false) Link
respond_to_missing? is not called in some cases, such as when type conversion is performed with Kernel#String
respond_to_missing?(sym, include_priv) Link
Ensure proxy class responds to all methods that underlying time instance responds to.
rfc2822() Link
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"
strftime(format) Link
Replaces %Z
directive with +zone before passing to Time#strftime, so that zone information is correct.
time() Link
Returns a Time
instance that represents the time in time_zone
.
to_a() Link
to_datetime() Link
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
to_f() Link
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
to_fs(format = :default) Link
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.
# File activesupport/lib/active_support/time_with_zone.rb, line 241 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 # Change to to_s when deprecation is gone. "#{time.strftime("%Y-%m-%d %H:%M:%S")} #{formatted_offset(false, 'UTC')}" end end
to_i() Link
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
to_r() Link
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)
to_s(format = NOT_SET) Link
Returns a string of the object's date and time.
# File activesupport/lib/active_support/time_with_zone.rb, line 212 def to_s(format = NOT_SET) if format == :db ActiveSupport::Deprecation.warn( "TimeWithZone#to_s(:db) is deprecated. Please use TimeWithZone#to_fs(:db) instead." ) utc.to_fs(format) elsif formatter = ::Time::DATE_FORMATS[format] ActiveSupport::Deprecation.warn( "TimeWithZone#to_s(#{format.inspect}) is deprecated. Please use TimeWithZone#to_fs(#{format.inspect}) instead." ) formatter.respond_to?(:call) ? formatter.call(self).to_s : strftime(formatter) elsif format == NOT_SET "#{time.strftime("%Y-%m-%d %H:%M:%S")} #{formatted_offset(false, 'UTC')}" # mimicking Ruby Time#to_s format else ActiveSupport::Deprecation.warn( "TimeWithZone#to_s(#{format.inspect}) is deprecated. Please use TimeWithZone#to_fs(#{format.inspect}) instead." ) "#{time.strftime("%Y-%m-%d %H:%M:%S")} #{formatted_offset(false, 'UTC')}" # mimicking Ruby Time#to_s format end end
to_time() Link
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
.
today?() Link
Returns true if the current object's time falls within the current day.
tomorrow?() Link
Returns true if the current object's time falls within the next day (tomorrow).
utc() Link
Returns a Time
instance of the simultaneous time in the UTC timezone.
utc?() Link
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
utc_offset() Link
Returns the offset from current time to UTC time in seconds.
xmlschema(fraction_digits = 0) Link
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"