Class: ActiveSupport::TimeWithZone

Inherits:
Object
  • Object
show all
Includes:
Comparable, DateAndTime::Compatibility
Defined in:
lib/active_support/time_with_zone.rb

Overview

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

Constant Summary collapse

PRECISIONS =
Hash.new { |h, n| h[n] = "%FT%T.%#{n}N".freeze }

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(utc_time, time_zone, local_time = nil, period = nil) ⇒ TimeWithZone

Returns a new instance of TimeWithZone.



52
53
54
55
56
# File '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

Dynamic Method Handling

This class handles dynamic methods through the method_missing method

#method_missing(sym, *args, &block) ⇒ Object

Send the missing method to time instance, and wrap result in a new TimeWithZone with the existing time_zone.



510
511
512
513
514
# File '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

Instance Attribute Details

#time_zoneObject (readonly)

Returns the value of attribute time_zone.



50
51
52
# File 'lib/active_support/time_with_zone.rb', line 50

def time_zone
  @time_zone
end

Class Method Details

.nameObject

Report class name as ‘Time’ to thwart type checking.



42
43
44
# File 'lib/active_support/time_with_zone.rb', line 42

def self.name
  "Time"
end

Instance Method Details

#+(other) ⇒ Object Also known as: since, in

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


276
277
278
279
280
281
282
283
# File '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

#-(other) ⇒ Object

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


303
304
305
306
307
308
309
310
311
312
# File '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

#<=>(other) ⇒ Object

Use the time in UTC for comparisons.



225
226
227
# File 'lib/active_support/time_with_zone.rb', line 225

def <=>(other)
  utc <=> other
end

#acts_like_time?Boolean

So that self acts_like?(:time).

Returns:

  • (Boolean)


464
465
466
# File 'lib/active_support/time_with_zone.rb', line 464

def acts_like_time?
  true
end

#advance(options) ⇒ Object

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


392
393
394
395
396
397
398
399
400
# File '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

#ago(other) ⇒ Object

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


331
332
333
# File 'lib/active_support/time_with_zone.rb', line 331

def ago(other)
  since(-other)
end

#as_json(options = nil) ⇒ Object

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"


167
168
169
170
171
172
173
# File '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

#between?(min, max) ⇒ Boolean

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

Returns:

  • (Boolean)


231
232
233
# File 'lib/active_support/time_with_zone.rb', line 231

def between?(min, max)
  utc.between?(min, max)
end

#blank?Boolean

An instance of ActiveSupport::TimeWithZone is never blank

Returns:

  • (Boolean)


475
476
477
# File 'lib/active_support/time_with_zone.rb', line 475

def blank?
  false
end

#change(options) ⇒ Object

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


352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
# File '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

#dst?Boolean Also known 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

Returns:

  • (Boolean)


95
96
97
# File 'lib/active_support/time_with_zone.rb', line 95

def dst?
  period.dst?
end

#encode_with(coder) ⇒ Object

:nodoc:



179
180
181
182
# File 'lib/active_support/time_with_zone.rb', line 179

def encode_with(coder) #:nodoc:
  coder.tag = "!ruby/object:ActiveSupport::TimeWithZone"
  coder.map = { "utc" => utc, "zone" => time_zone, "time" => time }
end

#eql?(other) ⇒ Boolean

Returns true if other is equal to current object.

Returns:

  • (Boolean)


252
253
254
# File 'lib/active_support/time_with_zone.rb', line 252

def eql?(other)
  other.eql?(utc)
end

#formatted_offset(colon = true, alternate_utc_string = nil) ⇒ Object

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"


126
127
128
# File '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

#freezeObject



479
480
481
482
483
# File '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

#future?Boolean

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

Returns:

  • (Boolean)


247
248
249
# File 'lib/active_support/time_with_zone.rb', line 247

def future?
  utc.future?
end

#hashObject



256
257
258
# File 'lib/active_support/time_with_zone.rb', line 256

def hash
  utc.hash
end

#httpdateObject

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"


188
189
190
# File 'lib/active_support/time_with_zone.rb', line 188

def httpdate
  utc.httpdate
end

#in_time_zone(new_zone = ::Time.zone) ⇒ Object

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



78
79
80
81
# File '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

#init_with(coder) ⇒ Object

:nodoc:



175
176
177
# File 'lib/active_support/time_with_zone.rb', line 175

def init_with(coder) #:nodoc:
  initialize(coder["utc"], coder["zone"], coder["time"])
end

#inspectObject

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"


141
142
143
# File 'lib/active_support/time_with_zone.rb', line 141

def inspect
  "#{time.strftime('%a, %d %b %Y %H:%M:%S')} #{zone} #{formatted_offset}"
end

#is_a?(klass) ⇒ Boolean Also known as: kind_of?

Say we’re a Time to thwart type checking.

Returns:

  • (Boolean)


469
470
471
# File 'lib/active_support/time_with_zone.rb', line 469

def is_a?(klass)
  klass == ::Time || super
end

#localtime(utc_offset = nil) ⇒ Object Also known as: getlocal

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



84
85
86
# File 'lib/active_support/time_with_zone.rb', line 84

def localtime(utc_offset = nil)
  utc.getlocal(utc_offset)
end

#marshal_dumpObject



485
486
487
# File 'lib/active_support/time_with_zone.rb', line 485

def marshal_dump
  [utc, time_zone.name, time]
end

#marshal_load(variables) ⇒ Object



489
490
491
# File '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

#past?Boolean

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

Returns:

  • (Boolean)


236
237
238
# File 'lib/active_support/time_with_zone.rb', line 236

def past?
  utc.past?
end

#periodObject

Returns the underlying TZInfo::TimezonePeriod.



73
74
75
# File 'lib/active_support/time_with_zone.rb', line 73

def period
  @period ||= time_zone.period_for_utc(@utc)
end

#respond_to?(sym, include_priv = false) ⇒ Boolean

respond_to_missing? is not called in some cases, such as when type conversion is performed with Kernel#String

Returns:

  • (Boolean)


495
496
497
498
499
# File '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

#respond_to_missing?(sym, include_priv) ⇒ Boolean

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

Returns:

  • (Boolean)


503
504
505
506
# File '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

#rfc2822Object Also known 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"


196
197
198
# File 'lib/active_support/time_with_zone.rb', line 196

def rfc2822
  to_s(:rfc822)
end

#strftime(format) ⇒ Object

Replaces %Z directive with +zone before passing to Time#strftime, so that zone information is correct.



219
220
221
222
# File '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

#timeObject

Returns a Time instance that represents the time in time_zone.



59
60
61
# File 'lib/active_support/time_with_zone.rb', line 59

def time
  @time ||= period.to_local(@utc)
end

#to_aObject

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"]


415
416
417
# File '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

#to_datetimeObject

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


448
449
450
# File '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

#to_fObject

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


423
424
425
# File 'lib/active_support/time_with_zone.rb', line 423

def to_f
  utc.to_f
end

#to_iObject Also known 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


431
432
433
# File 'lib/active_support/time_with_zone.rb', line 431

def to_i
  utc.to_i
end

#to_rObject

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)


440
441
442
# File 'lib/active_support/time_with_zone.rb', line 440

def to_r
  utc.to_r
end

#to_s(format = :default) ⇒ Object Also known as: to_formatted_s

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.



206
207
208
209
210
211
212
213
214
# File '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

#to_timeObject

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.



455
456
457
458
459
460
461
# File '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

#today?Boolean

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

Returns:

  • (Boolean)


242
243
244
# File 'lib/active_support/time_with_zone.rb', line 242

def today?
  time.today?
end

#utcObject Also known as: comparable_time, getgm, getutc, gmtime

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



64
65
66
# File 'lib/active_support/time_with_zone.rb', line 64

def utc
  @utc ||= period.to_utc(@time)
end

#utc?Boolean Also known 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

Returns:

  • (Boolean)


106
107
108
# File 'lib/active_support/time_with_zone.rb', line 106

def utc?
  period.offset.abbreviation == :UTC || period.offset.abbreviation == :UCT
end

#utc_offsetObject Also known as: gmt_offset, gmtoff

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



112
113
114
# File 'lib/active_support/time_with_zone.rb', line 112

def utc_offset
  period.utc_total_offset
end

#xmlschema(fraction_digits = 0) ⇒ Object Also known 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"


149
150
151
# File '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

#zoneObject

Returns the time zone abbreviation.

Time.zone = 'Eastern Time (US & Canada)'   # => "Eastern Time (US & Canada)"
Time.zone.now.zone # => "EST"


134
135
136
# File 'lib/active_support/time_with_zone.rb', line 134

def zone
  period.zone_identifier.to_s
end