vendor/rails/activesupport/lib/active_support/core_ext/date/calculations.rb

   1 module ActiveSupport #:nodoc:
   2   module CoreExtensions #:nodoc:
   3     module Date #:nodoc:
   4       # Enables the use of time calculations within Time itself
   5       module Calculations
   6         def self.included(base) #:nodoc:
   7           base.extend ClassMethods
   8
   9           base.instance_eval do
  10             alias_method :plus_without_duration, :+
  11             alias_method :+, :plus_with_duration
  12
  13             alias_method :minus_without_duration, :-
  14             alias_method :-, :minus_with_duration
  15           end
  16         end
  17
  18         module ClassMethods
  19           # Returns a new Date representing the date 1 day ago (i.e. yesterday's date).
  20           def yesterday
  21             ::Date.today.yesterday
  22           end
  23
  24           # Returns a new Date representing the date 1 day after today (i.e. tomorrow's date).
  25           def tomorrow
  26             ::Date.today.tomorrow
  27           end
  28
  29           # Returns Time.zone.today when config.time_zone is set, otherwise just returns Date.today.
  30           def current
  31             ::Time.zone_default ? ::Time.zone.today : ::Date.today
  32           end
  33         end
  34
  35         # Tells whether the Date object's date lies in the past
  36         def past?
  37           self < ::Date.current
  38         end
  39
  40         # Tells whether the Date object's date is today
  41         def today?
  42           self.to_date == ::Date.current # we need the to_date because of DateTime
  43         end
  44
  45         # Tells whether the Date object's date lies in the future
  46         def future?
  47           self > ::Date.current
  48         end
  49
  50         # Converts Date to a Time (or DateTime if necessary) with the time portion set to the beginning of the day (0:00)
  51         # and then subtracts the specified number of seconds
  52         def ago(seconds)
  53           to_time.since(-seconds)
  54         end
  55
  56         # Converts Date to a Time (or DateTime if necessary) with the time portion set to the beginning of the day (0:00)
  57         # and then adds the specified number of seconds
  58         def since(seconds)
  59           to_time.since(seconds)
  60         end
  61         alias :in :since
  62
  63         # Converts Date to a Time (or DateTime if necessary) with the time portion set to the beginning of the day (0:00)
  64         def beginning_of_day
  65           to_time
  66         end
  67         alias :midnight :beginning_of_day
  68         alias :at_midnight :beginning_of_day
  69         alias :at_beginning_of_day :beginning_of_day
  70
  71         # Converts Date to a Time (or DateTime if necessary) with the time portion set to the end of the day (23:59:59)
  72         def end_of_day
  73           to_time.end_of_day
  74         end
  75
  76         def plus_with_duration(other) #:nodoc:
  77           if ActiveSupport::Duration === other
  78             other.since(self)
  79           else
  80             plus_without_duration(other)
  81           end
  82         end
  83
  84         def minus_with_duration(other) #:nodoc:
  85           if ActiveSupport::Duration === other
  86             plus_with_duration(-other)
  87           else
  88             minus_without_duration(other)
  89           end
  90         end
  91
  92         # Provides precise Date calculations for years, months, and days.  The +options+ parameter takes a hash with
  93         # any of these keys: <tt>:years</tt>, <tt>:months</tt>, <tt>:weeks</tt>, <tt>:days</tt>.
  94         def advance(options)
  95           d = self
  96           d = d >> options.delete(:years) * 12 if options[:years]
  97           d = d >> options.delete(:months)     if options[:months]
  98           d = d +  options.delete(:weeks) * 7  if options[:weeks]
  99           d = d +  options.delete(:days)       if options[:days]
 100           d
 101         end
 102
 103         # Returns a new Date where one or more of the elements have been changed according to the +options+ parameter.
 104         #
 105         # Examples:
 106         #
 107         #   Date.new(2007, 5, 12).change(:day => 1)                  # => Date.new(2007, 5, 1)
 108         #   Date.new(2007, 5, 12).change(:year => 2005, :month => 1) # => Date.new(2005, 1, 12)
 109         def change(options)
 110           ::Date.new(
 111             options[:year]  || self.year,
 112             options[:month] || self.month,
 113             options[:day]   || self.day
 114           )
 115         end
 116
 117         # Returns a new Date/DateTime representing the time a number of specified months ago
 118         def months_ago(months)
 119           advance(:months => -months)
 120         end
 121
 122         # Returns a new Date/DateTime representing the time a number of specified months in the future
 123         def months_since(months)
 124           advance(:months => months)
 125         end
 126
 127         # Returns a new Date/DateTime representing the time a number of specified years ago
 128         def years_ago(years)
 129           advance(:years => -years)
 130         end
 131
 132         # Returns a new Date/DateTime representing the time a number of specified years in the future
 133         def years_since(years)
 134           advance(:years => years)
 135         end
 136
 137         # Short-hand for years_ago(1)
 138         def last_year
 139           years_ago(1)
 140         end
 141
 142         # Short-hand for years_since(1)
 143         def next_year
 144           years_since(1)
 145         end
 146
 147         # Short-hand for months_ago(1)
 148         def last_month
 149           months_ago(1)
 150         end
 151
 152         # Short-hand for months_since(1)
 153         def next_month
 154           months_since(1)
 155         end
 156
 157         # Returns a new Date/DateTime representing the "start" of this week (i.e, Monday; DateTime objects will have time set to 0:00)
 158         def beginning_of_week
 159           days_to_monday = self.wday!=0 ? self.wday-1 : 6
 160           result = self - days_to_monday
 161           self.acts_like?(:time) ? result.midnight : result
 162         end
 163         alias :monday :beginning_of_week
 164         alias :at_beginning_of_week :beginning_of_week
 165
 166         # Returns a new Date/DateTime representing the end of this week (Sunday, DateTime objects will have time set to 23:59:59)
 167         def end_of_week
 168           days_to_sunday = self.wday!=0 ? 7-self.wday : 0
 169           result = self + days_to_sunday.days
 170           self.acts_like?(:time) ? result.end_of_day : result
 171         end
 172         alias :at_end_of_week :end_of_week
 173
 174         # Returns a new Date/DateTime representing the start of the given day in next week (default is Monday).
 175         def next_week(day = :monday)
 176           days_into_week = { :monday => 0, :tuesday => 1, :wednesday => 2, :thursday => 3, :friday => 4, :saturday => 5, :sunday => 6}
 177           result = (self + 7).beginning_of_week + days_into_week[day]
 178           self.acts_like?(:time) ? result.change(:hour => 0) : result
 179         end
 180
 181         # Returns a new ; DateTime objects will have time set to 0:00DateTime representing the start of the month (1st of the month; DateTime objects will have time set to 0:00)
 182         def beginning_of_month
 183           self.acts_like?(:time) ? change(:day => 1,:hour => 0, :min => 0, :sec => 0) : change(:day => 1)
 184         end
 185         alias :at_beginning_of_month :beginning_of_month
 186
 187         # Returns a new Date/DateTime representing the end of the month (last day of the month; DateTime objects will have time set to 0:00)
 188         def end_of_month
 189           last_day = ::Time.days_in_month( self.month, self.year )
 190           self.acts_like?(:time) ? change(:day => last_day, :hour => 23, :min => 59, :sec => 59) : change(:day => last_day)
 191         end
 192         alias :at_end_of_month :end_of_month
 193
 194         # Returns a new Date/DateTime representing the start of the quarter (1st of january, april, july, october; DateTime objects will have time set to 0:00)
 195         def beginning_of_quarter
 196           beginning_of_month.change(:month => [10, 7, 4, 1].detect { |m| m <= self.month })
 197         end
 198         alias :at_beginning_of_quarter :beginning_of_quarter
 199
 200         # Returns a new Date/DateTime representing the end of the quarter (last day of march, june, september, december; DateTime objects will have time set to 23:59:59)
 201         def end_of_quarter
 202           beginning_of_month.change(:month => [3, 6, 9, 12].detect { |m| m >= self.month }).end_of_month
 203         end
 204         alias :at_end_of_quarter :end_of_quarter
 205
 206         # Returns a new Date/DateTime representing the start of the year (1st of january; DateTime objects will have time set to 0:00)
 207         def beginning_of_year
 208           self.acts_like?(:time) ? change(:month => 1, :day => 1, :hour => 0, :min => 0, :sec => 0) : change(:month => 1, :day => 1)
 209         end
 210         alias :at_beginning_of_year :beginning_of_year
 211
 212         # Returns a new Time representing the end of the year (31st of december; DateTime objects will have time set to 23:59:59)
 213         def end_of_year
 214           self.acts_like?(:time) ? change(:month => 12,:day => 31,:hour => 23, :min => 59, :sec => 59) : change(:month => 12, :day => 31)
 215         end
 216         alias :at_end_of_year :end_of_year
 217
 218         # Convenience method which returns a new Date/DateTime representing the time 1 day ago
 219         def yesterday
 220           self - 1
 221         end
 222
 223         # Convenience method which returns a new Date/DateTime representing the time 1 day since the instance time
 224         def tomorrow
 225           self + 1
 226         end
 227       end
 228     end
 229   end
 230 end