Class: Time

Inherits:
Object show all
Includes:
DateAndTime::Calculations
Defined in:
lib/active_support/json/encoding.rb,
lib/active_support/core_ext/time/zones.rb,
lib/active_support/core_ext/time/marshal.rb,
lib/active_support/core_ext/time/acts_like.rb,
lib/active_support/core_ext/time/conversions.rb,
lib/active_support/core_ext/time/calculations.rb

Constant Summary collapse

DATE_FORMATS = 
{
  :db           => '%Y-%m-%d %H:%M:%S',
  :number       => '%Y%m%d%H%M%S',
  :nsec         => '%Y%m%d%H%M%S%9N',
  :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}")
  }
}
COMMON_YEAR_DAYS_IN_MONTH = 
[nil, 31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31]

Constants included from DateAndTime::Calculations

DateAndTime::Calculations::DAYS_INTO_WEEK

Class Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from DateAndTime::Calculations

#beginning_of_month, #beginning_of_quarter, #beginning_of_week, #beginning_of_year, #days_ago, #days_since, #days_to_week_start, #end_of_month, #end_of_quarter, #end_of_week, #end_of_year, #future?, #monday, #months_ago, #months_since, #next_month, #next_quarter, #next_week, #next_year, #past?, #prev_month, #prev_quarter, #prev_week, #prev_year, #sunday, #today?, #tomorrow, #weeks_ago, #weeks_since, #years_ago, #years_since, #yesterday

Class Attribute Details

.zone_default ⇒ Object

Returns the value of attribute zone_default.



5
6
7
 
# File 'lib/active_support/core_ext/time/zones.rb', line 5

def zone_default
  @zone_default
end

Class Method Details

.===(other) ⇒ Object

Overriding case equality method so that it returns true for ActiveSupport::TimeWithZone instances



15
16
17
 
# File 'lib/active_support/core_ext/time/calculations.rb', line 15

def ===(other)
  super || (self == Time && other.is_a?(ActiveSupport::TimeWithZone))
end

._load(marshaled_time) ⇒ Object 



8
9
10
11
12
13
14
15
16
17
18
19
20
 
# File 'lib/active_support/core_ext/time/marshal.rb', line 8

def _load(marshaled_time)
  time = _load_without_zone(marshaled_time)
  time.instance_eval do
    if zone = defined?(@_zone) && remove_instance_variable('@_zone')
      ary = to_a
      ary[0] += subsec if ary[0] == sec
      ary[-1] = zone
      utc? ? Time.utc(*ary) : Time.local(*ary)
    else
      self
    end
  end
end

._load_without_zone ⇒ Object 



7
 
# File 'lib/active_support/core_ext/time/marshal.rb', line 7

alias_method :_load_without_zone, :_load

.at_with_coercion(*args) ⇒ Object Also known as: at

Layers additional behavior on Time.at so that ActiveSupport::TimeWithZone and DateTime instances can be used when called with a single argument



71
72
73
74
75
76
77
78
79
80
81
82
 
# File 'lib/active_support/core_ext/time/calculations.rb', line 71

def at_with_coercion(*args)
  return at_without_coercion(*args) if args.size != 1

  # Time.at can be called with a time or numerical value
  time_or_number = args.first

  if time_or_number.is_a?(ActiveSupport::TimeWithZone) || time_or_number.is_a?(DateTime)
    at_without_coercion(time_or_number.to_f).getlocal
  else
    at_without_coercion(time_or_number)
  end
end

.current ⇒ Object

Returns Time.zone.now when Time.zone or config.time_zone are set, otherwise just returns Time.now.



65
66
67
 
# File 'lib/active_support/core_ext/time/calculations.rb', line 65

def current
  ::Time.zone ? ::Time.zone.now : ::Time.now
end

.days_in_month(month, year = now.year) ⇒ Object

Return the number of days in the given month. If no year is specified, it will use the current year.



21
22
23
24
25
26
27
 
# File 'lib/active_support/core_ext/time/calculations.rb', line 21

def days_in_month(month, year = now.year)
  if month == 2 && ::Date.gregorian_leap?(year)
    29
  else
    COMMON_YEAR_DAYS_IN_MONTH[month]
  end
end

.find_zone(time_zone) ⇒ Object 



72
73
74
 
# File 'lib/active_support/core_ext/time/zones.rb', line 72

def find_zone(time_zone)
  find_zone!(time_zone) rescue nil
end

.find_zone!(time_zone) ⇒ Object

Returns a TimeZone instance or nil, or raises an ArgumentError for invalid timezones.



52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
 
# File 'lib/active_support/core_ext/time/zones.rb', line 52

def find_zone!(time_zone)
  if !time_zone || time_zone.is_a?(ActiveSupport::TimeZone)
    time_zone
  else
    # lookup timezone based on identifier (unless we've been passed a TZInfo::Timezone)
    unless time_zone.respond_to?(:period_for_local)
      time_zone = ActiveSupport::TimeZone[time_zone] || TZInfo::Timezone.get(time_zone)
    end

    # Return if a TimeZone instance, or wrap in a TimeZone instance if a TZInfo::Timezone
    if time_zone.is_a?(ActiveSupport::TimeZone)
      time_zone
    else
      ActiveSupport::TimeZone.create(time_zone.name, nil, time_zone)
    end
  end
rescue TZInfo::InvalidTimezoneIdentifier
  raise ArgumentError, "Invalid Timezone: #{time_zone}"
end

.local_time(*args) ⇒ Object

DEPRECATED: Use Time#local instead.

Wraps class method time_with_datetime_fallback with utc_or_local set to :local.



59
60
61
62
 
# File 'lib/active_support/core_ext/time/calculations.rb', line 59

def local_time(*args)
  ActiveSupport::Deprecation.warn 'local_time is deprecated. Use Time#local instead', caller
  time_with_datetime_fallback(:local, *args)
end

.time_with_datetime_fallback(utc_or_local, year, month = 1, day = 1, hour = 0, min = 0, sec = 0, usec = 0) ⇒ Object

DEPRECATED: Use Time#utc or Time#local instead.

Returns a new Time if requested year can be accommodated by Ruby’s Time class (i.e., if year is within either 1970..2038 or 1902..2038, depending on system architecture); otherwise returns a DateTime.



34
35
36
37
38
39
40
41
42
43
44
45
46
 
# File 'lib/active_support/core_ext/time/calculations.rb', line 34

def time_with_datetime_fallback(utc_or_local, year, month=1, day=1, hour=0, min=0, sec=0, usec=0)
  ActiveSupport::Deprecation.warn 'time_with_datetime_fallback is deprecated. Use Time#utc or Time#local instead', caller
  time = ::Time.send(utc_or_local, year, month, day, hour, min, sec, usec)

  # This check is needed because Time.utc(y) returns a time object in the 2000s for 0 <= y <= 138.
  if time.year == year
    time
  else
    ::DateTime.civil_from_format(utc_or_local, year, month, day, hour, min, sec)
  end
rescue
  ::DateTime.civil_from_format(utc_or_local, year, month, day, hour, min, sec)
end

.use_zone(time_zone) ⇒ Object

Allows override of Time.zone locally inside supplied block; resets Time.zone to existing value when done.



41
42
43
44
45
46
47
48
49
 
# File 'lib/active_support/core_ext/time/zones.rb', line 41

def use_zone(time_zone)
  new_zone = find_zone!(time_zone)
  begin
    old_zone, ::Time.zone = ::Time.zone, new_zone
    yield
  ensure
    ::Time.zone = old_zone
  end
end

.utc_time(*args) ⇒ Object

DEPRECATED: Use Time#utc instead.

Wraps class method time_with_datetime_fallback with utc_or_local set to :utc.



51
52
53
54
 
# File 'lib/active_support/core_ext/time/calculations.rb', line 51

def utc_time(*args)
  ActiveSupport::Deprecation.warn 'utc_time is deprecated. Use Time#utc instead', caller
  time_with_datetime_fallback(:utc, *args)
end

.zone ⇒ Object

Returns the TimeZone for the current request, if this has been set (via Time.zone=). If Time.zone has not been set for the current request, returns the TimeZone specified in config.time_zone.



9
10
11
 
# File 'lib/active_support/core_ext/time/zones.rb', line 9

def zone
  Thread.current[:time_zone] || zone_default
end

.zone=(time_zone) ⇒ Object

Sets Time.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::Timezone object.

  • An identifier for a TZInfo::Timezone object (e.g., “America/New_York”).

Here’s an example of how you might set Time.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:

class ApplicationController < ActionController::Base
  around_filter :set_time_zone

  def set_time_zone
    if logged_in?
      Time.use_zone(current_user.time_zone) { yield }
    else
      yield
    end
  end
end



36
37
38
 
# File 'lib/active_support/core_ext/time/zones.rb', line 36

def zone=(time_zone)
  Thread.current[:time_zone] = find_zone!(time_zone)
end

Instance Method Details

#_dump(*args) ⇒ Object 



24
25
26
27
28
 
# File 'lib/active_support/core_ext/time/marshal.rb', line 24

def _dump(*args)
  obj = dup
  obj.instance_variable_set('@_zone', zone)
  obj.send :_dump_without_zone, *args
end

#_dump_without_zone ⇒ Object 



23
 
# File 'lib/active_support/core_ext/time/marshal.rb', line 23

alias_method :_dump_without_zone, :_dump

#acts_like_time? ⇒ Boolean

Duck-types as a Time-like class. See Object#acts_like?.

Returns:

  • (Boolean) 


5
6
7
 
# File 'lib/active_support/core_ext/time/acts_like.rb', line 5

def acts_like_time?
  true
end

#advance(options) ⇒ Object

Uses Date to provide precise Time calculations for years, months, and days. The options parameter takes a hash with any of these keys: :years, :months, :weeks, :days, :hours, :minutes, :seconds.



134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
 
# File 'lib/active_support/core_ext/time/calculations.rb', line 134

def advance(options)
  unless options[:weeks].nil?
    options[:weeks], partial_weeks = options[:weeks].divmod(1)
    options[:days] = options.fetch(:days, 0) + 7 * partial_weeks
  end

  unless options[:days].nil?
    options[:days], partial_days = options[:days].divmod(1)
    options[:hours] = options.fetch(:hours, 0) + 24 * partial_days
  end

  d = to_date.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) * 3600

  if seconds_to_advance.zero?
    time_advanced_by_date
  else
    time_advanced_by_date.since(seconds_to_advance)
  end
end

#ago(seconds) ⇒ Object

Returns a new Time representing the time a number of seconds ago, this is basically a wrapper around the Numeric extension



160
161
162
 
# File 'lib/active_support/core_ext/time/calculations.rb', line 160

def ago(seconds)
  since(-seconds)
end

#all_day ⇒ Object

Returns a Range representing the whole day of the current time.



224
225
226
 
# File 'lib/active_support/core_ext/time/calculations.rb', line 224

def all_day
  beginning_of_day..end_of_day
end

#all_month ⇒ Object

Returns a Range representing the whole month of the current time.



235
236
237
 
# File 'lib/active_support/core_ext/time/calculations.rb', line 235

def all_month
  beginning_of_month..end_of_month
end

#all_quarter ⇒ Object

Returns a Range representing the whole quarter of the current time.



240
241
242
 
# File 'lib/active_support/core_ext/time/calculations.rb', line 240

def all_quarter
  beginning_of_quarter..end_of_quarter
end

#all_week(start_day = Date.beginning_of_week) ⇒ Object

Returns a Range representing the whole week of the current time. Week starts on start_day, default is Date.week_start or config.week_start when set.



230
231
232
 
# File 'lib/active_support/core_ext/time/calculations.rb', line 230

def all_week(start_day = Date.beginning_of_week)
  beginning_of_week(start_day)..end_of_week(start_day)
end

#all_year ⇒ Object

Returns a Range representing the whole year of the current time.



245
246
247
 
# File 'lib/active_support/core_ext/time/calculations.rb', line 245

def all_year
  beginning_of_year..end_of_year
end

#as_json(options = nil) ⇒ Object

:nodoc:



311
312
313
314
315
316
317
 
# File 'lib/active_support/json/encoding.rb', line 311

def as_json(options = nil) #:nodoc:
  if ActiveSupport.use_standard_json_time_format
    xmlschema
  else
    %(#{strftime("%Y/%m/%d %H:%M:%S")} #{formatted_offset(false)})
  end
end

#beginning_of_day ⇒ Object Also known as: midnight, at_midnight, at_beginning_of_day

Returns a new Time representing the start of the day (0:00)



173
174
175
176
 
# File 'lib/active_support/core_ext/time/calculations.rb', line 173

def beginning_of_day
  #(self - seconds_since_midnight).change(usec: 0)
  change(:hour => 0)
end

#beginning_of_hour ⇒ Object Also known as: at_beginning_of_hour

Returns a new Time representing the start of the hour (x:00)



193
194
195
 
# File 'lib/active_support/core_ext/time/calculations.rb', line 193

def beginning_of_hour
  change(:min => 0)
end

#beginning_of_minute ⇒ Object Also known as: at_beginning_of_minute

Returns a new Time representing the start of the minute (x:xx:00)



209
210
211
 
# File 'lib/active_support/core_ext/time/calculations.rb', line 209

def beginning_of_minute
  change(:sec => 0)
end

#change(options) ⇒ Object

Returns a new Time where one or more of the elements have been changed according to the options parameter. The time options (:hour, :min, :sec, :usec) reset cascadingly, so if only the hour is passed, then minute, sec, and usec is set to 0. If the hour and minute is passed, then sec and usec is set to 0. The options parameter takes a hash with any of these keys: :year, :month, :day, :hour, :min, :sec, :usec.

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)



112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
 
# File 'lib/active_support/core_ext/time/calculations.rb', line 112

def change(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_usec  = options.fetch(:usec, (options[:hour] || options[:min] || options[:sec]) ? 0 : Rational(nsec, 1000))

  if utc?
    ::Time.utc(new_year, new_month, new_day, new_hour, new_min, new_sec, new_usec)
  elsif zone
    ::Time.local(new_year, new_month, new_day, new_hour, new_min, new_sec, new_usec)
  else
    ::Time.new(new_year, new_month, new_day, new_hour, new_min, new_sec + (new_usec.to_r / 1000000), utc_offset)
  end
end

#compare_with_coercion(other) ⇒ Object Also known as: <=>

Layers additional behavior on Time#<=> so that DateTime and ActiveSupport::TimeWithZone instances can be chronologically compared with a Time



281
282
283
284
285
286
287
288
 
# File 'lib/active_support/core_ext/time/calculations.rb', line 281

def compare_with_coercion(other)
  # we're avoiding Time#to_datetime cause it's expensive
  if other.is_a?(Time)
    compare_without_coercion(other.to_time)
  else
    to_datetime <=> other
  end
end

#end_of_day ⇒ Object Also known as: at_end_of_day

Returns a new Time representing the end of the day, 23:59:59.999999 (.999999999 in ruby1.9)



182
183
184
185
186
187
188
189
 
# File 'lib/active_support/core_ext/time/calculations.rb', line 182

def end_of_day
  change(
    :hour => 23,
    :min => 59,
    :sec => 59,
    :usec => Rational(999999999, 1000)
  )
end

#end_of_hour ⇒ Object Also known as: at_end_of_hour

Returns a new Time representing the end of the hour, x:59:59.999999 (.999999999 in ruby1.9)



199
200
201
202
203
204
205
 
# File 'lib/active_support/core_ext/time/calculations.rb', line 199

def end_of_hour
  change(
    :min => 59,
    :sec => 59,
    :usec => Rational(999999999, 1000)
  )
end

#end_of_minute ⇒ Object Also known as: at_end_of_minute

Returns a new Time representing the end of the minute, x:xx:59.999999 (.999999999 in ruby1.9)



215
216
217
218
219
220
 
# File 'lib/active_support/core_ext/time/calculations.rb', line 215

def end_of_minute
  change(
    :sec => 59,
    :usec => Rational(999999999, 1000)
  )
end

#eql_with_coercion(other) ⇒ Object Also known as: eql?

Layers additional behavior on Time#eql? so that ActiveSupport::TimeWithZone instances can be eql? to an equivalent Time



294
295
296
297
298
 
# File 'lib/active_support/core_ext/time/calculations.rb', line 294

def eql_with_coercion(other)
  # if other is an ActiveSupport::TimeWithZone, coerce a Time instance from it so we can do eql? comparison
  other = other.comparable_time if other.respond_to?(:comparable_time)
  eql_without_coercion(other)
end

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

Returns the UTC offset as an +HH:MM formatted string.

Time.local(2000).formatted_offset        # => "-06:00"
Time.local(2000).formatted_offset(false) # => "-0600"



60
61
62
 
# File 'lib/active_support/core_ext/time/conversions.rb', line 60

def formatted_offset(colon = true, alternate_utc_string = nil)
  utc? && alternate_utc_string || ActiveSupport::TimeZone.seconds_to_utc_offset(utc_offset, colon)
end

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

Returns the simultaneous time in Time.zone.

Time.zone = 'Hawaii'        # => 'Hawaii'
Time.utc(2000).in_time_zone # => Fri, 31 Dec 1999 14:00:00 HST -10:00

This method is similar to Time#localtime, except that it uses Time.zone as the local zone instead of the operating system’s time zone.

You can also pass in a TimeZone instance or string that identifies a TimeZone as an argument, and the conversion will be based on that zone instead of Time.zone.

Time.utc(2000).in_time_zone('Alaska') # => Fri, 31 Dec 1999 15:00:00 AKST -09:00



89
90
91
92
93
94
95
 
# File 'lib/active_support/core_ext/time/zones.rb', line 89

def in_time_zone(zone = ::Time.zone)
  if zone
    ActiveSupport::TimeWithZone.new(utc? ? self : getutc, ::Time.find_zone!(zone))
  else
    self
  end
end

#minus_with_coercion(other) ⇒ Object Also known as: -

Time#- can also be used to determine the number of seconds between two Time instances. We’re layering on additional behavior so that ActiveSupport::TimeWithZone instances are coerced into values that Time#- will recognize



272
273
274
275
 
# File 'lib/active_support/core_ext/time/calculations.rb', line 272

def minus_with_coercion(other)
  other = other.comparable_time if other.respond_to?(:comparable_time)
  other.is_a?(DateTime) ? to_f - other.to_f : minus_without_coercion(other)
end

#minus_with_duration(other) ⇒ Object

:nodoc:



259
260
261
262
263
264
265
 
# File 'lib/active_support/core_ext/time/calculations.rb', line 259

def minus_with_duration(other) #:nodoc:
  if ActiveSupport::Duration === other
    other.until(self)
  else
    minus_without_duration(other)
  end
end

#plus_with_duration(other) ⇒ Object Also known as: +

:nodoc:



249
250
251
252
253
254
255
 
# File 'lib/active_support/core_ext/time/calculations.rb', line 249

def plus_with_duration(other) #:nodoc:
  if ActiveSupport::Duration === other
    other.since(self)
  else
    plus_without_duration(other)
  end
end

#seconds_since_midnight ⇒ Object

Seconds since midnight: Time.now.seconds_since_midnight



88
89
90
 
# File 'lib/active_support/core_ext/time/calculations.rb', line 88

def seconds_since_midnight
  to_i - change(:hour => 0).to_i + (usec / 1.0e+6)
end

#seconds_until_end_of_day ⇒ Object

Returns the number of seconds until 23:59:59.

Time.new(2012, 8, 29,  0,  0,  0).seconds_until_end_of_day # => 86399
Time.new(2012, 8, 29, 12, 34, 56).seconds_until_end_of_day # => 41103
Time.new(2012, 8, 29, 23, 59, 59).seconds_until_end_of_day # => 0



97
98
99
 
# File 'lib/active_support/core_ext/time/calculations.rb', line 97

def seconds_until_end_of_day
  end_of_day.to_i - to_i
end

#since(seconds) ⇒ Object Also known as: in

Returns a new Time representing the time a number of seconds since the instance time



165
166
167
168
169
 
# File 'lib/active_support/core_ext/time/calculations.rb', line 165

def since(seconds)
  self + seconds
rescue
  to_datetime.since(seconds)
end

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

Converts to a formatted string. See DATE_FORMATS for builtin formats.

This method is aliased to to_s.

time = Time.now                    # => Thu Jan 18 06:10:17 CST 2007

time.to_formatted_s(:time)         # => "06:10"
time.to_s(:time)                   # => "06:10"

time.to_formatted_s(:db)           # => "2007-01-18 06:10:17"
time.to_formatted_s(:number)       # => "20070118061017"
time.to_formatted_s(:short)        # => "18 Jan 06:10"
time.to_formatted_s(:long)         # => "January 18, 2007 06:10"
time.to_formatted_s(:long_ordinal) # => "January 18th, 2007 06:10"
time.to_formatted_s(:rfc822)       # => "Thu, 18 Jan 2007 06:10:17 -0600"

Adding your own time formats to to_formatted_s

You can add your own formats to the Time::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.rb
Time::DATE_FORMATS[:month_and_year] = '%B %Y'
Time::DATE_FORMATS[:short_ordinal]  = ->(time) { time.strftime("%B #{time.day.ordinalize}") }



46
47
48
49
50
51
52
 
# File 'lib/active_support/core_ext/time/conversions.rb', line 46

def to_formatted_s(format = :default)
  if formatter = DATE_FORMATS[format]
    formatter.respond_to?(:call) ? formatter.call(self).to_s : strftime(formatter)
  else
    to_default_s
  end
end