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

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
Also aliased as: since, in
📝 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

comparable_time()

Alias for: utc

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
Also aliased as: isdst
📝 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

getgm()

Alias for: utc

getlocal(utc_offset = nil)

Alias for: localtime

getutc()

Alias for: utc

gmt?()

Alias for: utc?

gmt_offset()

Alias for: utc_offset

gmtime()

Alias for: utc

gmtoff()

Alias for: utc_offset

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(other)

Alias for: +

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.

Also aliased as: kind_of?
📝 Source code
# File activesupport/lib/active_support/time_with_zone.rb, line 469
    def is_a?(klass)
      klass == ::Time || super
    end
🔎 See on GitHub

isdst()

Alias for: dst?

iso8601(fraction_digits = 0)

Alias for: xmlschema

kind_of?(klass)

Alias for: is_a?

localtime(utc_offset = nil)

Returns a Time instance of the simultaneous time in the system timezone.

Also aliased as: getlocal
📝 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"
Also aliased as: rfc822
📝 Source code
# File activesupport/lib/active_support/time_with_zone.rb, line 196
    def rfc2822
      to_s(:rfc822)
    end
🔎 See on GitHub

rfc3339(fraction_digits = 0)

Alias for: xmlschema

rfc822()

Alias for: rfc2822

since(other)

Alias for: +

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_formatted_s(format = :default)

Alias for: to_s

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
Also aliased as: tv_sec
📝 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 Ruby Time#to_s format.

  • :db - format outputs time in UTC :db time. See Time#to_formatted_s(:db).

  • Any key in Time::DATE_FORMATS can be used. See active_support/core_ext/time/conversions.rb.

Also aliased as: to_formatted_s
📝 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

tv_sec()

Alias for: to_i

utc()

Returns a Time instance of the simultaneous time in the UTC timezone.

Also aliased as: comparable_time, getgm, getutc, gmtime
📝 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
Also aliased as: gmt?
📝 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.

Also aliased as: gmt_offset, gmtoff
📝 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"
Also aliased as: iso8601, rfc3339
📝 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