class ActiveSupport::TimeWithZone
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
Constants
- PRECISIONS
Attributes
Public Class Methods
Report class name as 'Time' to thwart type checking.
# File lib/active_support/time_with_zone.rb, line 41 def self.name 'Time' end
# File 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 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
# File lib/active_support/time_with_zone.rb, line 274 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
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 lib/active_support/time_with_zone.rb, line 301 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
Use the time in UTC for comparisons.
# File lib/active_support/time_with_zone.rb, line 223 def <=>(other) utc <=> other end
So that self
acts_like?(:time)
.
# File lib/active_support/time_with_zone.rb, line 415 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 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 lib/active_support/time_with_zone.rb, line 354 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 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 lib/active_support/time_with_zone.rb, line 329 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").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 lib/active_support/time_with_zone.rb, line 165 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
Returns true if the current object's time is within the specified
min
and max
time.
# File lib/active_support/time_with_zone.rb, line 229 def between?(min, max) utc.between?(min, max) end
An instance of ActiveSupport::TimeWithZone is never blank
# File lib/active_support/time_with_zone.rb, line 426 def blank? false end
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
# File lib/active_support/time_with_zone.rb, line 94 def dst? period.dst? end
Returns true
if other
is equal to current object.
# File lib/active_support/time_with_zone.rb, line 250 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"
# File 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
# File lib/active_support/time_with_zone.rb, line 430 def freeze period; utc; time # preload instance variables before freezing super end
Returns true if the current object's time is in the future.
# File lib/active_support/time_with_zone.rb, line 245 def future? utc.future? end
# File lib/active_support/time_with_zone.rb, line 254 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"
# File lib/active_support/time_with_zone.rb, line 186 def httpdate utc.httpdate end
Returns the simultaneous time in Time.zone
, or the specified
zone.
# File 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 # => "Thu, 04 Dec 2014 11:00:25 EST -05:00"
# File lib/active_support/time_with_zone.rb, line 140 def inspect "#{time.strftime('%a, %d %b %Y %H:%M:%S')} #{zone} #{formatted_offset}" end
Say we're a Time to thwart type checking.
# File lib/active_support/time_with_zone.rb, line 420 def is_a?(klass) klass == ::Time || super end
Returns a Time
instance of the simultaneous time in the system
timezone.
# File lib/active_support/time_with_zone.rb, line 83 def localtime(utc_offset = nil) utc.getlocal(utc_offset) end
# File lib/active_support/time_with_zone.rb, line 435 def marshal_dump [utc, time_zone.name, time] end
# File lib/active_support/time_with_zone.rb, line 439 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
.
# File lib/active_support/time_with_zone.rb, line 460 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
Returns true if the current object's time is in the past.
# File lib/active_support/time_with_zone.rb, line 234 def past? utc.past? end
Returns the underlying TZInfo::TimezonePeriod.
# File lib/active_support/time_with_zone.rb, line 72 def period @period ||= time_zone.period_for_utc(@utc) end
respond_to_missing? is not called in some cases, such as when type conversion is performed with Kernel#String
# File lib/active_support/time_with_zone.rb, line 445 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.
# File lib/active_support/time_with_zone.rb, line 453 def respond_to_missing?(sym, include_priv) return false if sym.to_sym == :acts_like_date? time.respond_to?(sym, include_priv) end
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"
# File lib/active_support/time_with_zone.rb, line 194 def rfc2822 to_s(:rfc822) end
Replaces %Z
directive with +zone before passing to
Time#strftime, so that zone information is correct.
# File lib/active_support/time_with_zone.rb, line 217 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
.
# File lib/active_support/time_with_zone.rb, line 58 def time @time ||= period.to_local(@utc) 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 UTC +00:00 now.to_a # => [27, 29, 2, 18, 8, 2015, 2, 230, false, "UTC"]
# File lib/active_support/time_with_zone.rb, line 377 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
# File lib/active_support/time_with_zone.rb, line 410 def 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
# File lib/active_support/time_with_zone.rb, line 385 def to_f utc.to_f end
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
# File lib/active_support/time_with_zone.rb, line 393 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)
# File lib/active_support/time_with_zone.rb, line 402 def to_r utc.to_r end
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.
# File lib/active_support/time_with_zone.rb, line 204 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
Returns true if the current object's time falls within the current day.
# File lib/active_support/time_with_zone.rb, line 240 def today? time.today? end
Returns a Time
instance of the simultaneous time in the UTC
timezone.
# File lib/active_support/time_with_zone.rb, line 63 def utc @utc ||= period.to_utc(@time) end
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
# File lib/active_support/time_with_zone.rb, line 105 def utc? period.offset.abbreviation == :UTC || period.offset.abbreviation == :UCT end
Returns the offset from current time to UTC time in seconds.
# File lib/active_support/time_with_zone.rb, line 111 def utc_offset period.utc_total_offset end
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"
# File 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'.freeze)}" end
Returns the time zone abbreviation.
Time.zone = 'Eastern Time (US & Canada)' # => "Eastern Time (US & Canada)" Time.zone.now.zone # => "EST"
# File lib/active_support/time_with_zone.rb, line 133 def zone period.zone_identifier.to_s end
Private Instance Methods
# File lib/active_support/time_with_zone.rb, line 484 def duration_of_variable_length?(obj) ActiveSupport::Duration === obj && obj.parts.any? {|p| [:years, :months, :weeks, :days].include?(p[0]) } end
# File lib/active_support/time_with_zone.rb, line 467 def get_period_and_ensure_valid_local_time(period) # we don't want a Time.local instance enforcing its own DST rules as well, # so transfer time values to a utc constructor if necessary @time = transfer_time_values_to_utc_constructor(@time) unless @time.utc? begin period || @time_zone.period_for_local(@time) rescue ::TZInfo::PeriodNotFound # time is in the "spring forward" hour gap, so we're moving the time forward one hour and trying again @time += 1.hour retry end end
# File lib/active_support/time_with_zone.rb, line 480 def transfer_time_values_to_utc_constructor(time) ::Time.utc(time.year, time.month, time.day, time.hour, time.min, time.sec + time.subsec) end
# File lib/active_support/time_with_zone.rb, line 488 def wrap_with_time_zone(time) if time.acts_like?(:time) periods = time_zone.periods_for_local(time) self.class.new(nil, time_zone, time, periods.include?(period) ? period : nil) elsif time.is_a?(Range) wrap_with_time_zone(time.begin)..wrap_with_time_zone(time.end) else time end end