Module: ActiveSupport::CoreExtensions::Time::Calculations
- Included in:
- Time
- Defined in:
- lib/active_support/core_ext/time/calculations.rb
Overview
Enables the use of time calculations within Time itself
Defined Under Namespace
Modules: ClassMethods
Constant Summary collapse
- COMMON_YEAR_DAYS_IN_MONTH =
[nil, 31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31]
Class Method Summary collapse
-
.included(base) ⇒ Object
:nodoc:.
Instance Method Summary collapse
-
#advance(options) ⇒ Object
Uses Date to provide precise Time calculations for years, months, and days.
-
#ago(seconds) ⇒ Object
Returns a new Time representing the time a number of seconds ago, this is basically a wrapper around the Numeric extension.
-
#beginning_of_day ⇒ Object
(also: #midnight, #at_midnight, #at_beginning_of_day)
Returns a new Time representing the start of the day (0:00).
-
#beginning_of_month ⇒ Object
(also: #at_beginning_of_month)
Returns a new Time representing the start of the month (1st of the month, 0:00).
-
#beginning_of_quarter ⇒ Object
(also: #at_beginning_of_quarter)
Returns a new Time representing the start of the quarter (1st of january, april, july, october, 0:00).
-
#beginning_of_week ⇒ Object
(also: #monday, #at_beginning_of_week)
Returns a new Time representing the “start” of this week (Monday, 0:00).
-
#beginning_of_year ⇒ Object
(also: #at_beginning_of_year)
Returns a new Time representing the start of the year (1st of january, 0:00).
-
#change(options) ⇒ Object
Returns a new Time where one or more of the elements have been changed according to the
options
parameter. -
#compare_with_coercion(other) ⇒ Object
Layers additional behavior on Time#<=> so that DateTime and ActiveSupport::TimeWithZone instances can be chronologically compared with a Time.
-
#end_of_day ⇒ Object
Returns a new Time representing the end of the day (23:59:59).
-
#end_of_month ⇒ Object
(also: #at_end_of_month)
Returns a new Time representing the end of the month (last day of the month, 0:00).
-
#end_of_quarter ⇒ Object
(also: #at_end_of_quarter)
Returns a new Time representing the end of the quarter (last day of march, june, september, december, 23:59:59).
-
#end_of_week ⇒ Object
(also: #at_end_of_week)
Returns a new Time representing the end of this week (Sunday, 23:59:59).
-
#end_of_year ⇒ Object
(also: #at_end_of_year)
Returns a new Time representing the end of the year (31st of december, 23:59:59).
-
#future? ⇒ Boolean
Tells whether the Time object’s time lies in the future.
-
#last_month ⇒ Object
Short-hand for months_ago(1).
-
#last_year ⇒ Object
Short-hand for years_ago(1).
-
#minus_with_coercion(other) ⇒ Object
Time#- can also be used to determine the number of seconds between two Time instances.
-
#minus_with_duration(other) ⇒ Object
:nodoc:.
-
#months_ago(months) ⇒ Object
Returns a new Time representing the time a number of specified months ago.
-
#months_since(months) ⇒ Object
Returns a new Time representing the time a number of specified months in the future.
-
#next_month ⇒ Object
Short-hand for months_since(1).
-
#next_week(day = :monday) ⇒ Object
Returns a new Time representing the start of the given day in next week (default is Monday).
-
#next_year ⇒ Object
Short-hand for years_since(1).
-
#past? ⇒ Boolean
Tells whether the Time object’s time lies in the past.
-
#plus_with_duration(other) ⇒ Object
:nodoc:.
-
#seconds_since_midnight ⇒ Object
Seconds since midnight: Time.now.seconds_since_midnight.
-
#since(seconds) ⇒ Object
(also: #in)
Returns a new Time representing the time a number of seconds since the instance time, this is basically a wrapper around the Numeric extension.
-
#today? ⇒ Boolean
Tells whether the Time object’s time is today.
-
#tomorrow ⇒ Object
Convenience method which returns a new Time representing the time 1 day since the instance time.
-
#years_ago(years) ⇒ Object
Returns a new Time representing the time a number of specified years ago.
-
#years_since(years) ⇒ Object
Returns a new Time representing the time a number of specified years in the future.
-
#yesterday ⇒ Object
Convenience method which returns a new Time representing the time 1 day ago.
Class Method Details
.included(base) ⇒ Object
:nodoc:
8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 |
# File 'lib/active_support/core_ext/time/calculations.rb', line 8 def self.included(base) #:nodoc: base.extend ClassMethods base.class_eval do alias_method :plus_without_duration, :+ alias_method :+, :plus_with_duration alias_method :minus_without_duration, :- alias_method :-, :minus_with_duration alias_method :minus_without_coercion, :- alias_method :-, :minus_with_coercion alias_method :compare_without_coercion, :<=> alias_method :<=>, :compare_with_coercion end end |
Instance Method Details
#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
.
102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 |
# File 'lib/active_support/core_ext/time/calculations.rb', line 102 def advance() unless [:weeks].nil? [:weeks], partial_weeks = [:weeks].divmod(1) [:days] = ([:days] || 0) + 7 * partial_weeks end unless [:days].nil? [:days], partial_days = [:days].divmod(1) [:hours] = ([:hours] || 0) + 24 * partial_days end d = to_date.advance() time_advanced_by_date = change(:year => d.year, :month => d.month, :day => d.day) seconds_to_advance = ([:seconds] || 0) + ([:minutes] || 0) * 60 + ([:hours] || 0) * 3600 seconds_to_advance == 0 ? time_advanced_by_date : time_advanced_by_date.since(seconds_to_advance) 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
120 121 122 |
# File 'lib/active_support/core_ext/time/calculations.rb', line 120 def ago(seconds) self.since(-seconds) 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)
203 204 205 206 |
# File 'lib/active_support/core_ext/time/calculations.rb', line 203 def beginning_of_day #(self - seconds_since_midnight).change(:usec => 0) change(:hour => 0, :min => 0, :sec => 0, :usec => 0) end |
#beginning_of_month ⇒ Object Also known as: at_beginning_of_month
Returns a new Time representing the start of the month (1st of the month, 0:00)
217 218 219 220 |
# File 'lib/active_support/core_ext/time/calculations.rb', line 217 def beginning_of_month #self - ((self.mday-1).days + self.seconds_since_midnight) change(:day => 1,:hour => 0, :min => 0, :sec => 0, :usec => 0) end |
#beginning_of_quarter ⇒ Object Also known as: at_beginning_of_quarter
Returns a new Time representing the start of the quarter (1st of january, april, july, october, 0:00)
232 233 234 |
# File 'lib/active_support/core_ext/time/calculations.rb', line 232 def beginning_of_quarter beginning_of_month.change(:month => [10, 7, 4, 1].detect { |m| m <= self.month }) end |
#beginning_of_week ⇒ Object Also known as: monday, at_beginning_of_week
Returns a new Time representing the “start” of this week (Monday, 0:00)
182 183 184 185 |
# File 'lib/active_support/core_ext/time/calculations.rb', line 182 def beginning_of_week days_to_monday = self.wday!=0 ? self.wday-1 : 6 (self - days_to_monday.days).midnight end |
#beginning_of_year ⇒ Object Also known as: at_beginning_of_year
Returns a new Time representing the start of the year (1st of january, 0:00)
244 245 246 |
# File 'lib/active_support/core_ext/time/calculations.rb', line 244 def beginning_of_year change(:month => 1,:day => 1,:hour => 0, :min => 0, :sec => 0, :usec => 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, minute, 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.
85 86 87 88 89 90 91 92 93 94 95 96 |
# File 'lib/active_support/core_ext/time/calculations.rb', line 85 def change() ::Time.send( self.utc? ? :utc_time : :local_time, [:year] || self.year, [:month] || self.month, [:day] || self.day, [:hour] || self.hour, [:min] || ([:hour] ? 0 : self.min), [:sec] || (([:hour] || [:min]) ? 0 : self.sec), [:usec] || (([:hour] || [:min] || [:sec]) ? 0 : self.usec) ) end |
#compare_with_coercion(other) ⇒ Object
Layers additional behavior on Time#<=> so that DateTime and ActiveSupport::TimeWithZone instances can be chronologically compared with a Time
291 292 293 294 295 296 297 298 299 300 |
# File 'lib/active_support/core_ext/time/calculations.rb', line 291 def compare_with_coercion(other) # if other is an ActiveSupport::TimeWithZone, coerce a Time instance from it so we can do <=> comparison other = other.comparable_time if other.respond_to?(:comparable_time) if other.acts_like?(:date) # other is a Date/DateTime, so coerce self #to_datetime and hand off to DateTime#<=> to_datetime.compare_without_coercion(other) else compare_without_coercion(other) end end |
#end_of_day ⇒ Object
Returns a new Time representing the end of the day (23:59:59)
212 213 214 |
# File 'lib/active_support/core_ext/time/calculations.rb', line 212 def end_of_day change(:hour => 23, :min => 59, :sec => 59) end |
#end_of_month ⇒ Object Also known as: at_end_of_month
Returns a new Time representing the end of the month (last day of the month, 0:00)
224 225 226 227 228 |
# File 'lib/active_support/core_ext/time/calculations.rb', line 224 def end_of_month #self - ((self.mday-1).days + self.seconds_since_midnight) last_day = ::Time.days_in_month( self.month, self.year ) change(:day => last_day, :hour => 23, :min => 59, :sec => 59, :usec => 0) end |
#end_of_quarter ⇒ Object Also known as: at_end_of_quarter
Returns a new Time representing the end of the quarter (last day of march, june, september, december, 23:59:59)
238 239 240 |
# File 'lib/active_support/core_ext/time/calculations.rb', line 238 def end_of_quarter beginning_of_month.change(:month => [3, 6, 9, 12].detect { |m| m >= self.month }).end_of_month end |
#end_of_week ⇒ Object Also known as: at_end_of_week
Returns a new Time representing the end of this week (Sunday, 23:59:59)
190 191 192 193 |
# File 'lib/active_support/core_ext/time/calculations.rb', line 190 def end_of_week days_to_sunday = self.wday!=0 ? 7-self.wday : 0 (self + days_to_sunday.days).end_of_day end |
#end_of_year ⇒ Object Also known as: at_end_of_year
Returns a new Time representing the end of the year (31st of december, 23:59:59)
250 251 252 |
# File 'lib/active_support/core_ext/time/calculations.rb', line 250 def end_of_year change(:month => 12,:day => 31,:hour => 23, :min => 59, :sec => 59) end |
#future? ⇒ Boolean
Tells whether the Time object’s time lies in the future
73 74 75 |
# File 'lib/active_support/core_ext/time/calculations.rb', line 73 def future? self > ::Time.current end |
#last_month ⇒ Object
Short-hand for months_ago(1)
172 173 174 |
# File 'lib/active_support/core_ext/time/calculations.rb', line 172 def last_month months_ago(1) end |
#last_year ⇒ Object
Short-hand for years_ago(1)
161 162 163 |
# File 'lib/active_support/core_ext/time/calculations.rb', line 161 def last_year years_ago(1) end |
#minus_with_coercion(other) ⇒ Object
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
284 285 286 287 |
# File 'lib/active_support/core_ext/time/calculations.rb', line 284 def minus_with_coercion(other) other = other.comparable_time if other.respond_to?(:comparable_time) minus_without_coercion(other) end |
#minus_with_duration(other) ⇒ Object
:nodoc:
273 274 275 276 277 278 279 |
# File 'lib/active_support/core_ext/time/calculations.rb', line 273 def minus_with_duration(other) #:nodoc: if ActiveSupport::Duration === other other.until(self) else minus_without_duration(other) end end |
#months_ago(months) ⇒ Object
Returns a new Time representing the time a number of specified months ago
141 142 143 |
# File 'lib/active_support/core_ext/time/calculations.rb', line 141 def months_ago(months) advance(:months => -months) end |
#months_since(months) ⇒ Object
Returns a new Time representing the time a number of specified months in the future
146 147 148 |
# File 'lib/active_support/core_ext/time/calculations.rb', line 146 def months_since(months) advance(:months => months) end |
#next_month ⇒ Object
Short-hand for months_since(1)
177 178 179 |
# File 'lib/active_support/core_ext/time/calculations.rb', line 177 def next_month months_since(1) end |
#next_week(day = :monday) ⇒ Object
Returns a new Time representing the start of the given day in next week (default is Monday).
197 198 199 200 |
# File 'lib/active_support/core_ext/time/calculations.rb', line 197 def next_week(day = :monday) days_into_week = { :monday => 0, :tuesday => 1, :wednesday => 2, :thursday => 3, :friday => 4, :saturday => 5, :sunday => 6} since(1.week).beginning_of_week.since(days_into_week[day].day).change(:hour => 0) end |
#next_year ⇒ Object
Short-hand for years_since(1)
166 167 168 |
# File 'lib/active_support/core_ext/time/calculations.rb', line 166 def next_year years_since(1) end |
#past? ⇒ Boolean
Tells whether the Time object’s time lies in the past
63 64 65 |
# File 'lib/active_support/core_ext/time/calculations.rb', line 63 def past? self < ::Time.current end |
#plus_with_duration(other) ⇒ Object
:nodoc:
265 266 267 268 269 270 271 |
# File 'lib/active_support/core_ext/time/calculations.rb', line 265 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
78 79 80 |
# File 'lib/active_support/core_ext/time/calculations.rb', line 78 def seconds_since_midnight self.to_i - self.change(:hour => 0).to_i + (self.usec/1.0e+6) end |
#since(seconds) ⇒ Object Also known as: in
Returns a new Time representing the time a number of seconds since the instance time, this is basically a wrapper around the Numeric extension.
126 127 128 129 130 131 132 133 134 135 136 137 |
# File 'lib/active_support/core_ext/time/calculations.rb', line 126 def since(seconds) f = seconds.since(self) if ActiveSupport::Duration === seconds f else initial_dst = self.dst? ? 1 : 0 final_dst = f.dst? ? 1 : 0 (seconds.abs >= 86400 && initial_dst != final_dst) ? f + (initial_dst - final_dst).hours : f end rescue self.to_datetime.since(seconds) end |
#today? ⇒ Boolean
Tells whether the Time object’s time is today
68 69 70 |
# File 'lib/active_support/core_ext/time/calculations.rb', line 68 def today? self.to_date == ::Date.current end |
#tomorrow ⇒ Object
Convenience method which returns a new Time representing the time 1 day since the instance time
261 262 263 |
# File 'lib/active_support/core_ext/time/calculations.rb', line 261 def tomorrow advance(:days => 1) end |
#years_ago(years) ⇒ Object
Returns a new Time representing the time a number of specified years ago
151 152 153 |
# File 'lib/active_support/core_ext/time/calculations.rb', line 151 def years_ago(years) advance(:years => -years) end |
#years_since(years) ⇒ Object
Returns a new Time representing the time a number of specified years in the future
156 157 158 |
# File 'lib/active_support/core_ext/time/calculations.rb', line 156 def years_since(years) advance(:years => years) end |
#yesterday ⇒ Object
Convenience method which returns a new Time representing the time 1 day ago
256 257 258 |
# File 'lib/active_support/core_ext/time/calculations.rb', line 256 def yesterday advance(:days => -1) end |