class ActiveSupport::TimeWithZone
Experimental RBS support (using type sampling data from the type_fusion
project).
# sig/active_support/time_with_zone.rbs class ActiveSupport::TimeWithZone def advance: (Hash options) -> ActiveSupport::TimeWithZone def incorporate_utc_offset: (Time time, Integer offset) -> Time def initialize: (Time? utc_time, ActiveSupport::TimeZone time_zone, ?Time? local_time, ?TZInfo::OffsetTimezonePeriod? period) -> void def is_a?: (Class klass) -> bool def period: () -> TZInfo::OffsetTimezonePeriod def respond_to?: (Symbol sym, ?bool include_priv) -> bool def time: () -> Time def to_fs: (?Symbol format) -> String def to_s: (?Object format) -> String def transfer_time_values_to_utc_constructor: (Time time) -> Time def utc: () -> Time def utc?: () -> true def utc_offset: () -> Integer def zone: () -> String end
t.is_a?(ActiveSupport::TimeWithZone) # => true
t.is_a?(Time) # => true
t > Time.utc(1999) # => true
t.beginning_of_year # => Tue, 01 Jan 2008 00:00:00.000000000 EST -05:00
t + 1.day # => Mon, 19 May 2008 13:27:25.031505668 EDT -04:00
t.to_fs(:rfc822) # => “Sun, 18 May 2008 13:27:25 -0400”
t.zone # => “EDT”
t.utc_offset # => -14400
t.dst? # => true
t.hour # => 13
t = Time.zone.now # => Sun, 18 May 2008 13:27:25.031505668 EDT -04:00
that Time and TimeWithZone instances are interchangeable.
TimeWithZone instances implement the same API as Ruby Time instances, so
See Time and TimeZone for further documentation of these methods.
Time.utc(2007, 2, 10, 20, 30, 45).in_time_zone # => 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.zone.at(1171139445) # => 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.local(2007, 2, 10, 15, 30, 45) # => Sat, 10 Feb 2007 15:30:45.000000000 EST -05:00
Time.zone = ‘Eastern Time (US & Canada)’ # => ‘Eastern Time (US & Canada)’
and in_time_zone
on Time and DateTime instances.
Instead use methods local
, parse
, at
, and now
on TimeZone instances,
You shouldn’t ever need to create a TimeWithZone instance directly via new
.
system’s ENV['TZ']
zone.
because standard Ruby Time instances are limited to UTC and the
A Time-like class that can represent a time in any time zone. Necessary
def self.name
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
def +(other)
now + 24.hours # => Mon, 03 Nov 2014 00:26:28.725182881 EST -05:00
time + 1.day will advance 23-25 hours, depending on the day.
For instance, a time + 24.hours will advance exactly 24 hours, while a
when moving across DST boundaries.
move forward from #time, otherwise move forward from #utc, for accuracy
If we're adding a Duration of variable length (i.e., years, months, days),
now + 1000 # => Sun, 02 Nov 2014 01:43:08.725182881 EDT -04:00
now = Time.zone.now # => Sun, 02 Nov 2014 01:26:28.725182881 EDT -04:00
Time.zone = 'Eastern Time (US & Canada)' # => 'Eastern Time (US & Canada)'
value as a new TimeWithZone object.
Adds an interval of time to the current object's time and returns that
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
def -(other)
Time.zone.now - 1.day.ago # => 86399.999967
will be returned.
If both the TimeWithZone object and the other value act like Time, a Float
now - 1.day # => Sun, 02 Nov 2014 00:26:28.725182881 EDT -04:00
now - 24.hours # => Sun, 02 Nov 2014 01:26:28.725182881 EDT -04:00
time - 1.day will subtract 23-25 hours, depending on the day.
For instance, a time - 24.hours will go subtract exactly 24 hours, while a
when moving across DST boundaries.
move backward from #time, otherwise move backward from #utc, for accuracy
If subtracting a Duration of variable length (i.e., years, months, days),
now - 1000 # => Mon, 03 Nov 2014 00:09:48.725182881 EST -05:00
now = Time.zone.now # => Mon, 03 Nov 2014 00:26:28.725182881 EST -05:00
Time.zone = 'Eastern Time (US & Canada)' # => 'Eastern Time (US & Canada)'
other time and return the difference in seconds as a Float.
the other value +acts_like?+ time. In which case, it will subtract the
Subtracts an interval of time and returns a new TimeWithZone object unless
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
def <=>(other)
def <=>(other) utc <=> other end
def acts_like_time?
def acts_like_time? true end
def advance(options)
Experimental RBS support (using type sampling data from the type_fusion
project).
def advance: (years | Integer options) -> ActiveSupport::TimeWithZone
This signature was generated using 1 sample from 1 application.
now.advance(months: 1) # => Tue, 02 Dec 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(days: 1) # => Mon, 03 Nov 2014 01:26:28.558049687 EST -05:00
now.advance(hours: 1) # => Sun, 02 Nov 2014 01:26:28.558049687 EST -05:00
now.advance(minutes: 1) # => Sun, 02 Nov 2014 01:27:28.558049687 EDT -04:00
now.advance(seconds: 1) # => Sun, 02 Nov 2014 01:26:29.558049687 EDT -04:00
now = Time.zone.now # => Sun, 02 Nov 2014 01:26:28.558049687 EDT -04:00
Time.zone = 'Eastern Time (US & Canada)' # => 'Eastern Time (US & Canada)'
accuracy when moving across DST boundaries.
days), move forward from #time, otherwise move forward from #utc, for
If advancing by a value of variable length (i.e., years, weeks, months,
:hours, :minutes, :seconds.
:years, :months, :weeks, :days,
The +options+ parameter takes a hash with any of these keys:
new TimeWithZone object.
according to the proleptic Gregorian calendar. The result is returned as a
Uses Date to provide precise Time calculations for years, months, and days
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
def ago(other)
now.ago(24.hours) # => Sun, 02 Nov 2014 01:26:28.725182881 EDT -04:00
the day.
while time.ago(1.day) will move back 23-25 hours, depending on
For instance, time.ago(24.hours) will move back exactly 24 hours,
accuracy when moving across DST boundaries.
days), move backward from #time, otherwise move backward from #utc, for
If we're subtracting a Duration of variable length (i.e., years, months,
now.ago(1000) # => Mon, 03 Nov 2014 00:09:48.725182881 EST -05:00
now = Time.zone.now # => Mon, 03 Nov 2014 00:26:28.725182881 EST -05:00
Time.zone = 'Eastern Time (US & Canada)' # => 'Eastern Time (US & Canada)'
the result as a new TimeWithZone object.
Subtracts an interval of time from the current object's time and returns
def ago(other) since(-other) end
def as_json(options = nil)
Time.utc(2005,2,1,15,15,10).in_time_zone("Hawaii").to_json
# With ActiveSupport::JSON::Encoding.use_standard_json_time_format = false
# => "2005-02-01T05:15:10.000-10:00"
Time.utc(2005,2,1,15,15,10).in_time_zone("Hawaii").to_json
# With ActiveSupport::JSON::Encoding.use_standard_json_time_format = true
to +false+.
ActiveSupport::JSON::Encoding.use_standard_json_time_format
You can get %Y/%m/%d %H:%M:%S +offset style by setting
Coerces time to a string for JSON encoding. The default format is ISO 8601.
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
def between?(min, max)
Returns true if the current object's time is within the specified
def between?(min, max) utc.between?(min, max) end
def blank?
def blank? false end
def change(options)
t.change(offset: "-10:00") # => Fri, 14 Apr 2017 11:45:15.116992711 HST -10:00
t.change(min: 30) # => Fri, 14 Apr 2017 11:30:00.116992711 EST -05:00
t.change(hour: 12) # => Fri, 14 Apr 2017 12:00:00.116992711 EST -05:00
t.change(year: 2020) # => Tue, 14 Apr 2020 11:45:15.116992711 EST -05:00
t = Time.zone.now # => Fri, 14 Apr 2017 11:45:15.116992711 EST -05:00
:offset, not both.
or :nsec, not both. Similarly, pass either :zone or
:nsec, :offset, :zone. Pass either :usec
:day, :hour, :min, :sec, :usec,
parameter takes a hash with any of these keys: :year, :month,
hour and minute is passed, then sec, usec, and nsec is set to 0. The +options+
so if only the hour is passed, then minute, sec, usec, and nsec is set to 0. If the
:min, :sec, :usec, :nsec) reset cascadingly,
been changed according to the +options+ parameter. The time options (:hour,
Returns a new +ActiveSupport::TimeWithZone+ where one or more of the elements have
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
def dst?
Time.zone.parse("2012-5-30").dst? # => true
Time.zone = 'Eastern Time (US & Canada)' # => 'Eastern Time (US & Canada)'
specified time zone.
Returns true if the current time is within Daylight Savings Time for the
def dst? period.dst? end
def duration_of_variable_length?(obj)
def duration_of_variable_length?(obj) ActiveSupport::Duration === obj && obj.variable? end
def encode_with(coder) # :nodoc:
def encode_with(coder) # :nodoc: coder.map = { "utc" => utc, "zone" => time_zone, "time" => time } end
def eql?(other)
def eql?(other) other.eql?(utc) end
def formatted_offset(colon = true, alternate_utc_string = nil)
Time.zone = 'UTC' # => "UTC"
Time.zone.now.formatted_offset(false) # => "-0500"
Time.zone.now.formatted_offset(true) # => "-05:00"
Time.zone = 'Eastern Time (US & Canada)' # => "Eastern Time (US & Canada)"
string if the time zone is already UTC.
Returns a formatted string of the offset from UTC, or an alternative
def formatted_offset(colon = true, alternate_utc_string = nil) utc? && alternate_utc_string || TimeZone.seconds_to_utc_offset(utc_offset, colon) end
def freeze
def freeze # preload instance variables before freezing period; utc; time; to_datetime; to_time super end
def future?
def future? utc.future? end
def get_period_and_ensure_valid_local_time(period)
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
def hash
def hash utc.hash end
def httpdate
HTTP requests.
Returns a string of the object's date and time in the format used by
def httpdate utc.httpdate end
def in_time_zone(new_zone = ::Time.zone)
def in_time_zone(new_zone = ::Time.zone) return self if time_zone == new_zone utc.in_time_zone(new_zone) end
def incorporate_utc_offset(time, offset)
Experimental RBS support (using type sampling data from the type_fusion
project).
def incorporate_utc_offset: (Time time, Integer offset) -> Time
This signature was generated using 4 samples from 1 application.
def incorporate_utc_offset(time, offset) if time.kind_of?(Date) time + Rational(offset, SECONDS_PER_DAY) else time + offset end end
def init_with(coder) # :nodoc:
def init_with(coder) # :nodoc: initialize(coder["utc"], coder["zone"], coder["time"]) end
def initialize(utc_time, time_zone, local_time = nil, period = nil)
Experimental RBS support (using type sampling data from the type_fusion
project).
def initialize: (Time? utc_time, ActiveSupport::TimeZone time_zone, ?Time? local_time, ?TZInfo::OffsetTimezonePeriod? period) -> void
This signature was generated using 12 samples from 2 applications.
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
def inspect
Returns a string of the object's date, time, zone, and offset from UTC.
def inspect "#{time.strftime('%a, %d %b %Y %H:%M:%S.%9N')} #{zone} #{formatted_offset}" end
def is_a?(klass)
Experimental RBS support (using type sampling data from the type_fusion
project).
def is_a?: (Class klass) -> bool
This signature was generated using 34 samples from 2 applications.
def is_a?(klass) klass == ::Time || super end
def localtime(utc_offset = nil)
def localtime(utc_offset = nil) utc.getlocal(utc_offset) end
def marshal_dump
def marshal_dump [utc, time_zone.name, time] end
def marshal_load(variables)
def marshal_load(variables) initialize(variables[0].utc, ::Time.find_zone(variables[1]), variables[2].utc) end
def method_missing(...)
Send the missing method to +time+ instance, and wrap result in a new
def method_missing(...) wrap_with_time_zone time.__send__(...) rescue NoMethodError => e raise e, e.message.sub(time.inspect, inspect).sub("Time", "ActiveSupport::TimeWithZone"), e.backtrace end
def past?
def past? utc.past? end
def period
Experimental RBS support (using type sampling data from the type_fusion
project).
def period: () -> TZInfo::OffsetTimezonePeriod
This signature was generated using 15 samples from 2 applications.
def period @period ||= time_zone.period_for_utc(@utc) end
def respond_to?(sym, include_priv = false)
Experimental RBS support (using type sampling data from the type_fusion
project).
def respond_to?: (Symbol sym, ?bool include_priv) -> bool
This signature was generated using 76 samples from 2 applications.
respond_to_missing? is not called in some cases, such as when type conversion is
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
def respond_to_missing?(sym, include_priv)
Ensure proxy class responds to all methods that underlying time instance
def respond_to_missing?(sym, include_priv) return false if sym.to_sym == :acts_like_date? time.respond_to?(sym, include_priv) end
def rfc2822
format.
Returns a string of the object's date and time in the RFC 2822 standard
def rfc2822 to_fs(:rfc822) end
def strftime(format)
Replaces %Z directive with +zone before passing to Time#strftime,
def strftime(format) format = format.gsub(/((?:\A|[^%])(?:%%)*)%Z/, "\\1#{zone}") getlocal(utc_offset).strftime(format) end
def time
Experimental RBS support (using type sampling data from the type_fusion
project).
def time: () -> Time
This signature was generated using 48 samples from 2 applications.
def time @time ||= incorporate_utc_offset(@utc, utc_offset) end
def to_a
now = Time.zone.now # => Tue, 18 Aug 2015 02:29:27.485278555 UTC +00:00
[seconds, minutes, hours, day, month, year, weekday, yearday, dst?, zone].
Returns Array of parts of Time in sequence of
def to_a [time.sec, time.min, time.hour, time.day, time.mon, time.year, time.wday, time.yday, dst?, zone] end
def to_datetime
Time.zone.now.to_datetime # => Tue, 18 Aug 2015 02:32:20 +0000
Returns an instance of DateTime with the timezone's UTC offset
def to_datetime @to_datetime ||= utc.to_datetime.new_offset(Rational(utc_offset, 86_400)) end
def to_f
since the Epoch (January 1, 1970 00:00 UTC).
Returns the object's date and time as a floating-point number of seconds
def to_f utc.to_f end
def to_fs(format = :default)
Experimental RBS support (using type sampling data from the type_fusion
project).
def to_fs: (?Symbol format) -> String
This signature was generated using 1 sample from 1 application.
* :db - format outputs time in UTC :db time. See Time#to_fs(:db).
* :default - default value, mimics Ruby Time#to_s format.
Accepts an optional format:
This method is aliased to to_formatted_s.
Returns a string of the object's date and time.
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
def to_i
since the Epoch (January 1, 1970 00:00 UTC).
Returns the object's date and time as an integer number of seconds
def to_i utc.to_i end
def to_r
since the Epoch (January 1, 1970 00:00 UTC).
Returns the object's date and time as a rational number of seconds
def to_r utc.to_r end
def to_s(format = NOT_SET)
Experimental RBS support (using type sampling data from the type_fusion
project).
def to_s: (?Object format) -> String
This signature was generated using 2 samples from 1 application.
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 if formatter = ::Time::DATE_FORMATS[:default] ActiveSupport::Deprecation.warn( "Using a :default format for TimeWithZone#to_s is deprecated. Please use TimeWithZone#to_fs instead." ) 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 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
def to_time
as +self+ or in the local system timezone depending on the setting
Returns an instance of +Time+, either with the same UTC offset
def to_time if preserve_timezone @to_time_with_instance_offset ||= getlocal(utc_offset) else @to_time_with_system_offset ||= getlocal end end
def today?
Returns true if the current object's time falls within
def today? time.today? end
def tomorrow?
Returns true if the current object's time falls within
def tomorrow? time.tomorrow? end
def transfer_time_values_to_utc_constructor(time)
Experimental RBS support (using type sampling data from the type_fusion
project).
def transfer_time_values_to_utc_constructor: (Time time) -> Time
This signature was generated using 5 samples from 2 applications.
def transfer_time_values_to_utc_constructor(time) # avoid creating another Time object if possible return time if time.instance_of?(::Time) && time.utc? ::Time.utc(time.year, time.month, time.day, time.hour, time.min, time.sec + time.subsec) end
def utc
Experimental RBS support (using type sampling data from the type_fusion
project).
def utc: () -> Time
This signature was generated using 4 samples from 1 application.
def utc @utc ||= incorporate_utc_offset(@time, -utc_offset) end
def utc?
Experimental RBS support (using type sampling data from the type_fusion
project).
def utc?: () -> true
This signature was generated using 17 samples from 2 applications.
Time.zone = 'Eastern Time (US & Canada)' # => 'Eastern Time (US & Canada)'
Time.zone.now.utc? # => true
Time.zone = 'UTC' # => 'UTC'
Returns true if the current time zone is set to UTC.
def utc? zone == "UTC" || zone == "UCT" end
def utc_offset
Experimental RBS support (using type sampling data from the type_fusion
project).
def utc_offset: () -> Integer
This signature was generated using 1 sample from 1 application.
def utc_offset period.observed_utc_offset end
def wrap_with_time_zone(time)
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
def xmlschema(fraction_digits = 0)
format.
Returns a string of the object's date and time in the ISO 8601 standard
def xmlschema(fraction_digits = 0) "#{time.strftime(PRECISIONS[fraction_digits.to_i])}#{formatted_offset(true, 'Z')}" end
def yesterday?
Returns true if the current object's time falls within
def yesterday? time.yesterday? end
def zone
Experimental RBS support (using type sampling data from the type_fusion
project).
def zone: () -> String
This signature was generated using 15 samples from 1 application.
Time.zone = 'Eastern Time (US & Canada)' # => "Eastern Time (US & Canada)"
Returns the time zone abbreviation.
def zone period.abbreviation end