edge badge

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
#
A
B
C
D
E
F
G
H
I
K
L
M
N
P
R
S
T
U
X
Z
Included Modules
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.

# File activesupport/lib/active_support/time_with_zone.rb, line 40
def self.name
  'Time'
end
new(utc_time, time_zone, local_time = nil, period = nil)
# File activesupport/lib/active_support/time_with_zone.rb, line 50
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(period)
end
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
# File activesupport/lib/active_support/time_with_zone.rb, line 273
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)

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
# File activesupport/lib/active_support/time_with_zone.rb, line 299
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)

Use the time in UTC for comparisons.

# File activesupport/lib/active_support/time_with_zone.rb, line 222
def <=>(other)
  utc <=> other
end
acts_like_time?()

So that self acts_like?(:time).

# File activesupport/lib/active_support/time_with_zone.rb, line 418
def acts_like_time?
  true
end
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
# File activesupport/lib/active_support/time_with_zone.rb, line 352
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)

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
# File activesupport/lib/active_support/time_with_zone.rb, line 327
def ago(other)
  since(-other)
end
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"
# File activesupport/lib/active_support/time_with_zone.rb, line 164
def as_json(options = nil)
  if ActiveSupport::JSON::Encoding.use_standard_json_time_format
    xmlschema(ActiveSupport::JSON::Encoding.time_precision)
  else
    %Q(#{time.strftime("%Y/%m/%d %H:%M:%S")} #{formatted_offset(false)})
  end
end
between?(min, max)

Returns true if the current object's time is within the specified min and max time.

# File activesupport/lib/active_support/time_with_zone.rb, line 228
def between?(min, max)
  utc.between?(min, max)
end
blank?()

An instance of ActiveSupport::TimeWithZone is never blank

# File activesupport/lib/active_support/time_with_zone.rb, line 429
def blank?
  false
end
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
# File activesupport/lib/active_support/time_with_zone.rb, line 93
def dst?
  period.dst?
end
eql?(other)

Returns true if other is equal to current object.

# File activesupport/lib/active_support/time_with_zone.rb, line 249
def eql?(other)
  other.eql?(utc)
end
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"
# File activesupport/lib/active_support/time_with_zone.rb, line 124
def formatted_offset(colon = true, alternate_utc_string = nil)
  utc? && alternate_utc_string || TimeZone.seconds_to_utc_offset(utc_offset, colon)
end
freeze()
# File activesupport/lib/active_support/time_with_zone.rb, line 433
def freeze
  period; utc; time # preload instance variables before freezing
  super
end
future?()

Returns true if the current object's time is in the future.

# File activesupport/lib/active_support/time_with_zone.rb, line 244
def future?
  utc.future?
end
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()
# File activesupport/lib/active_support/time_with_zone.rb, line 253
def hash
  utc.hash
end
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"
# File activesupport/lib/active_support/time_with_zone.rb, line 185
def httpdate
  utc.httpdate
end
in_time_zone(new_zone = ::Time.zone)

Returns the simultaneous time in Time.zone, or the specified zone.

# File activesupport/lib/active_support/time_with_zone.rb, line 75
def in_time_zone(new_zone = ::Time.zone)
  return self if time_zone == new_zone
  utc.in_time_zone(new_zone)
end
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"
# File activesupport/lib/active_support/time_with_zone.rb, line 139
def inspect
  "#{time.strftime('%a, %d %b %Y %H:%M:%S')} #{zone} #{formatted_offset}"
end
is_a?(klass)

Say we're a Time to thwart type checking.

Also aliased as: kind_of?
# File activesupport/lib/active_support/time_with_zone.rb, line 423
def is_a?(klass)
  klass == ::Time || super
end
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.local() instance of the simultaneous time in your system's ENV['TZ'] zone.

Also aliased as: getlocal
# File activesupport/lib/active_support/time_with_zone.rb, line 82
def localtime(utc_offset = nil)
  utc.respond_to?(:getlocal) ? utc.getlocal(utc_offset) : utc.to_time.getlocal(utc_offset)
end
marshal_dump()
# File activesupport/lib/active_support/time_with_zone.rb, line 438
def marshal_dump
  [utc, time_zone.name, time]
end
marshal_load(variables)
# File activesupport/lib/active_support/time_with_zone.rb, line 442
def marshal_load(variables)
  initialize(variables[0].utc, ::Time.find_zone(variables[1]), variables[2].utc)
end
method_missing(sym, *args, &block)

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 464
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, self.inspect), e.backtrace
end
past?()

Returns true if the current object's time is in the past.

# File activesupport/lib/active_support/time_with_zone.rb, line 233
def past?
  utc.past?
end
period()

Returns the underlying TZInfo::TimezonePeriod.

# File activesupport/lib/active_support/time_with_zone.rb, line 70
def period
  @period ||= time_zone.period_for_utc(@utc)
end
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

# File activesupport/lib/active_support/time_with_zone.rb, line 448
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
respond_to_missing?(sym, include_priv)

Ensure proxy class responds to all methods that underlying time instance responds to.

# File activesupport/lib/active_support/time_with_zone.rb, line 456
def respond_to_missing?(sym, include_priv)
  # consistently respond false to acts_like?(:date), regardless of whether #time is a Time or DateTime
  return false if sym.to_sym == :acts_like_date?
  time.respond_to?(sym, include_priv)
end
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
# File activesupport/lib/active_support/time_with_zone.rb, line 193
def rfc2822
  to_s(:rfc822)
end
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.

# File activesupport/lib/active_support/time_with_zone.rb, line 216
def strftime(format)
  format = format.gsub(/((?:\A|[^%])(?:%%)*)%Z/, "\\1#{zone}")
  getlocal(utc_offset).strftime(format)
end
time()

Returns a Time or DateTime instance that represents the time in time_zone.

# File activesupport/lib/active_support/time_with_zone.rb, line 56
def time
  @time ||= period.to_local(@utc)
end
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"]
# File activesupport/lib/active_support/time_with_zone.rb, line 375
def to_a
  [time.sec, time.min, time.hour, time.day, time.mon, time.year, time.wday, time.yday, dst?, zone]
end
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
# File activesupport/lib/active_support/time_with_zone.rb, line 413
def to_datetime
  utc.to_datetime.new_offset(Rational(utc_offset, 86_400))
end
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
# File activesupport/lib/active_support/time_with_zone.rb, line 383
def to_f
  utc.to_f
end
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
# File activesupport/lib/active_support/time_with_zone.rb, line 391
def to_i
  utc.to_i
end
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)
# File activesupport/lib/active_support/time_with_zone.rb, line 400
def to_r
  utc.to_r
end
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
# File activesupport/lib/active_support/time_with_zone.rb, line 203
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
to_time()

Returns an instance of Time in the system timezone.

# File activesupport/lib/active_support/time_with_zone.rb, line 405
def to_time
  utc.to_time
end
today?()

Returns true if the current object's time falls within the current day.

# File activesupport/lib/active_support/time_with_zone.rb, line 239
def today?
  time.today?
end
tv_sec()
Alias for: to_i
utc()

Returns a Time or DateTime instance that represents the time in UTC.

Also aliased as: comparable_time, getgm, getutc, gmtime
# File activesupport/lib/active_support/time_with_zone.rb, line 61
def utc
  @utc ||= period.to_utc(@time)
end
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?
# File activesupport/lib/active_support/time_with_zone.rb, line 104
def utc?
  period.offset.abbreviation == :UTC || period.offset.abbreviation == :UCT
end
utc_offset()

Returns the offset from current time to UTC time in seconds.

Also aliased as: gmt_offset, gmtoff
# File activesupport/lib/active_support/time_with_zone.rb, line 110
def utc_offset
  period.utc_total_offset
end
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
# File activesupport/lib/active_support/time_with_zone.rb, line 147
def xmlschema(fraction_digits = 0)
  "#{time.strftime(PRECISIONS[fraction_digits.to_i])}#{formatted_offset(true, 'Z'.freeze)}"
end
zone()

Returns the time zone abbreviation.

Time.zone = 'Eastern Time (US & Canada)'   # => "Eastern Time (US & Canada)"
Time.zone.now.zone # => "EST"
# File activesupport/lib/active_support/time_with_zone.rb, line 132
def zone
  period.zone_identifier.to_s
end