- #
- A
- B
- C
- D
- E
- F
- I
- M
- N
- P
- R
- S
- T
- U
- Z
Constants
| COMMON_YEAR_DAYS_IN_MONTH | = | [nil, 31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31] |
| DATE_FORMATS | = | {db: "%Y-%m-%d %H:%M:%S",inspect: "%Y-%m-%d %H:%M:%S.%9N %z",number: "%Y%m%d%H%M%S",nsec: "%Y%m%d%H%M%S%9N",usec: "%Y%m%d%H%M%S%6N",time: "%H:%M",short: "%d %b %H:%M",long: "%B %d, %Y %H:%M",long_ordinal: lambda { |time|day_format = ActiveSupport::Inflector.ordinalize(time.day)time.strftime("%B #{day_format}, %Y %H:%M")},rfc822: lambda { |time|offset_format = time.formatted_offset(false)time.strftime("%a, %d %b %Y %H:%M:%S #{offset_format}")},rfc2822: lambda { |time| time.rfc2822 },iso8601: lambda { |time| time.iso8601 }} |
Attributes
| [RW] | zone_default |
Class Public methods
===(other)Link
Overriding case equality method so that it returns true forActiveSupport::TimeWithZone instances
at_with_coercion(time_or_number, *args)Link
Layers additional behavior onTime.at so thatActiveSupport::TimeWithZone andDateTime instances can be used when called with a single argument
# File activesupport/lib/active_support/core_ext/time/calculations.rb, line 45defat_with_coercion(time_or_number,*args)ifargs.empty?iftime_or_number.is_a?(ActiveSupport::TimeWithZone)at_without_coercion(time_or_number.to_r).getlocalelsiftime_or_number.is_a?(DateTime)at_without_coercion(time_or_number.to_f).getlocalelseat_without_coercion(time_or_number)endelseat_without_coercion(time_or_number,*args)endend
current()Link
ReturnsTime.zone.now whenTime.zone orconfig.time_zone are set, otherwise just returnsTime.now.
days_in_month(month, year = current.year)Link
Returns the number of days in the given month. If no year is specified, it will use the current year.
days_in_year(year = current.year)Link
Returns the number of days in the given year. If no year is specified, it will use the current year.
find_zone(time_zone)Link
Returns a TimeZone instance matching the time zone provided. Accepts the time zone in any format supported byTime.zone=. Returnsnil for invalid time zones.
Time.find_zone"America/New_York"# => #<ActiveSupport::TimeZone @name="America/New_York" ...>Time.find_zone"NOT-A-TIMEZONE"# => nil
find_zone!(time_zone)Link
Returns a TimeZone instance matching the time zone provided. Accepts the time zone in any format supported byTime.zone=. Raises anArgumentError for invalid time zones.
Time.find_zone!"America/New_York"# => #<ActiveSupport::TimeZone @name="America/New_York" ...>Time.find_zone!"EST"# => #<ActiveSupport::TimeZone @name="EST" ...>Time.find_zone!-5.hours# => #<ActiveSupport::TimeZone @name="Bogota" ...>Time.find_zone!nil# => nilTime.find_zone!false# => falseTime.find_zone!"NOT-A-TIMEZONE"# => ArgumentError: Invalid Timezone: NOT-A-TIMEZONE
rfc3339(str)Link
Creates aTime instance from an RFC 3339 string.
Time.rfc3339('1999-12-31T14:00:00-10:00')# => 2000-01-01 00:00:00 -1000
If the time or offset components are missing then anArgumentError will be raised.
Time.rfc3339('1999-12-31')# => ArgumentError: invalid date
# File activesupport/lib/active_support/core_ext/time/calculations.rb, line 69defrfc3339(str)parts =Date._rfc3339(str)raiseArgumentError,"invalid date"ifparts.empty?Time.new(parts.fetch(:year),parts.fetch(:mon),parts.fetch(:mday),parts.fetch(:hour),parts.fetch(:min),parts.fetch(:sec)+parts.fetch(:sec_fraction,0),parts.fetch(:offset) )end
use_zone(time_zone)Link
Allows override ofTime.zone locally inside supplied block; resetsTime.zone to existing value when done.
classApplicationController<ActionController::Basearound_action:set_time_zoneprivatedefset_time_zoneTime.use_zone(current_user.timezone) {yield }endend
NOTE: This won’t affect anyActiveSupport::TimeWithZone objects that have already been created, e.g. any model timestamp attributes that have been read before the block will remain in the application’s default timezone.
zone()Link
Returns the TimeZone for the current request, if this has been set (viaTime.zone=). IfTime.zone has not been set for the current request, returns the TimeZone specified inconfig.time_zone.
zone=(time_zone)Link
SetsTime.zone to a TimeZone object for the current request/thread.
This method accepts any of the following:
A Rails TimeZone object.
An identifier for a Rails TimeZone object (e.g., “Eastern Time (US & Canada)”,
-5.hours).A
TZInfo::Timezoneobject.An identifier for a
TZInfo::Timezoneobject (e.g., “America/New_York”).
Here’s an example of how you might setTime.zone on a per request basis and reset it when the request is done.current_user.time_zone just needs to return a string identifying the user’s preferred time zone:
classApplicationController<ActionController::Basearound_action:set_time_zonedefset_time_zoneiflogged_in?Time.use_zone(current_user.time_zone) {yield }elseyieldendendend
Instance Public methods
-(other)Link
acts_like_time?()Link
Duck-types as a Time-like class. SeeObject#acts_like?.
advance(options)Link
UsesDate to provide preciseTime calculations for years, months, and days according to the proleptic Gregorian calendar. Theoptions parameter takes a hash with any of these keys::years,:months,:weeks,:days,:hours,:minutes,:seconds.
Time.new(2015,8,1,14,35,0).advance(seconds:1)# => 2015-08-01 14:35:01 -0700Time.new(2015,8,1,14,35,0).advance(minutes:1)# => 2015-08-01 14:36:00 -0700Time.new(2015,8,1,14,35,0).advance(hours:1)# => 2015-08-01 15:35:00 -0700Time.new(2015,8,1,14,35,0).advance(days:1)# => 2015-08-02 14:35:00 -0700Time.new(2015,8,1,14,35,0).advance(weeks:1)# => 2015-08-08 14:35:00 -0700
Just likeDate#advance, increments are applied in order of time units from largest to smallest. This order can affect the result around the end of a month.
# File activesupport/lib/active_support/core_ext/time/calculations.rb, line 194defadvance(options)unlessoptions[:weeks].nil?options[:weeks],partial_weeks =options[:weeks].divmod(1)options[:days] =options.fetch(:days,0)+7*partial_weeksendunlessoptions[:days].nil?options[:days],partial_days =options[:days].divmod(1)options[:hours] =options.fetch(:hours,0)+24*partial_daysendd =to_date.gregorian.advance(options)time_advanced_by_date =change(year:d.year,month:d.month,day:d.day)seconds_to_advance = \options.fetch(:seconds,0)+options.fetch(:minutes,0)*60+options.fetch(:hours,0)*3600ifseconds_to_advance.zero?time_advanced_by_dateelsetime_advanced_by_date.since(seconds_to_advance)endend
ago(seconds)Link
at_beginning_of_day()Link
at_beginning_of_hour()Link
at_beginning_of_minute()Link
at_end_of_day()Link
at_end_of_hour()Link
at_end_of_minute()Link
at_midday()Link
at_middle_of_day()Link
at_midnight()Link
at_noon()Link
beginning_of_hour()Link
Returns a newTime representing the start of the hour (x:00)
beginning_of_minute()Link
Returns a newTime representing the start of the minute (x:xx:00)
change(options)Link
Returns a newTime where one or more of the elements have been changed according to theoptions 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. Theoptions parameter takes a hash with any of these keys::year,:month,:day,:hour,:min,:sec,:usec,:nsec,:offset. Pass either:usec or:nsec, not both.
Time.new(2012,8,29,22,35,0).change(day:1)# => Time.new(2012, 8, 1, 22, 35, 0)Time.new(2012,8,29,22,35,0).change(year:1981,day:1)# => Time.new(1981, 8, 1, 22, 35, 0)Time.new(2012,8,29,22,35,0).change(year:1981,hour:0)# => Time.new(1981, 8, 29, 0, 0, 0)
# File activesupport/lib/active_support/core_ext/time/calculations.rb, line 123defchange(options)new_year =options.fetch(:year,year)new_month =options.fetch(:month,month)new_day =options.fetch(:day,day)new_hour =options.fetch(:hour,hour)new_min =options.fetch(:min,options[:hour]?0:min)new_sec =options.fetch(:sec, (options[:hour]||options[:min])?0:sec)new_offset =options.fetch(:offset,nil)ifnew_nsec =options[:nsec]raiseArgumentError,"Can't change both :nsec and :usec at the same time: #{options.inspect}"ifoptions[:usec]new_usec =Rational(new_nsec,1000)elsenew_usec =options.fetch(:usec, (options[:hour]||options[:min]||options[:sec])?0:Rational(nsec,1000))endraiseArgumentError,"argument out of range"ifnew_usec>=1000000new_sec+=Rational(new_usec,1000000)ifnew_offset::Time.new(new_year,new_month,new_day,new_hour,new_min,new_sec,new_offset)elsifutc?::Time.utc(new_year,new_month,new_day,new_hour,new_min,new_sec)elsifzone.respond_to?(:utc_to_local)new_time =::Time.new(new_year,new_month,new_day,new_hour,new_min,new_sec,zone)# Some versions of Ruby have a bug where Time.new with a zone object and# fractional seconds will end up with a broken utc_offset.# This is fixed in Ruby 3.3.1 and 3.2.4unlessnew_time.utc_offset.integer?new_time+=0end# When there are two occurrences of a nominal time due to DST ending,# `Time.new` chooses the first chronological occurrence (the one with a# larger UTC offset). However, for `change`, we want to choose the# occurrence that matches this time's UTC offset.## If the new time's UTC offset is larger than this time's UTC offset, the# new time might be a first chronological occurrence. So we add the offset# difference to fast-forward the new time, and check if the result has the# desired UTC offset (i.e. is the second chronological occurrence).offset_difference =new_time.utc_offset-utc_offsetifoffset_difference>0&& (new_time_2 =new_time+offset_difference).utc_offset==utc_offsetnew_time_2elsenew_timeendelsifzone::Time.local(new_sec,new_min,new_hour,new_day,new_month,new_year,nil,nil,isdst,nil)else::Time.new(new_year,new_month,new_day,new_hour,new_min,new_sec,utc_offset)endend
compare_with_coercion(other)Link
Layers additional behavior onTime#<=> so thatDateTime andActiveSupport::TimeWithZone instances can be chronologically compared with aTime
# File activesupport/lib/active_support/core_ext/time/calculations.rb, line 322defcompare_with_coercion(other)# we're avoiding Time#to_datetime and Time#to_time because they're expensiveifother.class==Timecompare_without_coercion(other)elsifother.is_a?(Time)# also avoid ActiveSupport::TimeWithZone#to_time before Rails 8.0ifother.respond_to?(:comparable_time)compare_without_coercion(other.comparable_time)elsecompare_without_coercion(other.to_time)endelseto_datetime<=>otherendend
end_of_day()Link
Returns a newTime representing the end of the day, 23:59:59.999999
end_of_hour()Link
Returns a newTime representing the end of the hour, x:59:59.999999
end_of_minute()Link
Returns a newTime representing the end of the minute, x:xx:59.999999
eql_with_coercion(other)Link
Layers additional behavior onTime#eql? so thatActiveSupport::TimeWithZone instances can be eql? to an equivalentTime
# File activesupport/lib/active_support/core_ext/time/calculations.rb, line 342defeql_with_coercion(other)# if other is an ActiveSupport::TimeWithZone, coerce a Time instance from it so we can do eql? comparisonother =other.comparable_timeifother.respond_to?(:comparable_time)eql_without_coercion(other)end
formatted_offset(colon = true, alternate_utc_string = nil)Link
Returns a formatted string of the offset from UTC, or an alternative string if the time zone is already UTC.
Time.local(2000).formatted_offset# => "-06:00"Time.local(2000).formatted_offset(false)# => "-0600"
midday()Link
midnight()Link
minus_with_coercion(other)Link
Time#- can also be used to determine the number of seconds between twoTime instances. We’re layering on additional behavior so thatActiveSupport::TimeWithZone instances are coerced into values thatTime#- will recognize
next_day(days = 1)Link
Returns a new time the specified number of days in the future.
next_month(months = 1)Link
Returns a new time the specified number of months in the future.
next_year(years = 1)Link
Returns a new time the specified number of years in the future.
noon()Link
prev_day(days = 1)Link
Returns a new time the specified number of days ago.
prev_month(months = 1)Link
Returns a new time the specified number of months ago.
prev_year(years = 1)Link
Returns a new time the specified number of years ago.
sec_fraction()Link
Returns the fraction of a second as aRational
Time.new(2012,8,29,0,0,0.5).sec_fraction# => (1/2)
seconds_since_midnight()Link
Returns the number of seconds since 00:00:00.
Time.new(2012,8,29,0,0,0).seconds_since_midnight# => 0.0Time.new(2012,8,29,12,34,56).seconds_since_midnight# => 45296.0Time.new(2012,8,29,23,59,59).seconds_since_midnight# => 86399.0
seconds_until_end_of_day()Link
Returns the number of seconds until 23:59:59.
Time.new(2012,8,29,0,0,0).seconds_until_end_of_day# => 86399Time.new(2012,8,29,12,34,56).seconds_until_end_of_day# => 41103Time.new(2012,8,29,23,59,59).seconds_until_end_of_day# => 0
since(seconds)Link
Returns a newTime representing the time a number of seconds since the instance time
to_fs(format = :default)Link
Converts to a formatted string. SeeDATE_FORMATS for built-in formats.
This method is aliased toto_formatted_s.
time =Time.now# => 2007-01-18 06:10:17 -06:00time.to_fs(:time)# => "06:10"time.to_formatted_s(:time)# => "06:10"time.to_fs(:db)# => "2007-01-18 06:10:17"time.to_fs(:number)# => "20070118061017"time.to_fs(:short)# => "18 Jan 06:10"time.to_fs(:long)# => "January 18, 2007 06:10"time.to_fs(:long_ordinal)# => "January 18th, 2007 06:10"time.to_fs(:rfc822)# => "Thu, 18 Jan 2007 06:10:17 -0600"time.to_fs(:rfc2822)# => "Thu, 18 Jan 2007 06:10:17 -0600"time.to_fs(:iso8601)# => "2007-01-18T06:10:17-06:00"
Adding your own time formats toto_fs¶↑
You can add your own formats to theTime::DATE_FORMATS hash. Use the format name as the hash key and either a strftime string or Proc instance that takes a time argument as the value.
# config/initializers/time_formats.rbTime::DATE_FORMATS[:month_and_year] ='%B %Y'Time::DATE_FORMATS[:short_ordinal] =->(time) {time.strftime("%B #{time.day.ordinalize}") }