Ticket #8848: docs_numeric_time.2.diff
| File docs_numeric_time.2.diff, 5.9 kB (added by jeremymcanally, 8 months ago) |
|---|
-
activesupport/lib/active_support/core_ext/numeric/time.rb
old new 1 1 module ActiveSupport #:nodoc: 2 2 module CoreExtensions #:nodoc: 3 3 module Numeric #:nodoc: 4 # Enables the use of time calculations and declarations, like 45.minutes + 2.hours + 4.years. 4 # Enables the use of time calculations and declarations, like <tt>45.minutes + 2.hours + 4.years</tt>. 5 # 6 # These methods use +Time#advance+ for precise date calculations when using from_now, ago, and so on, 7 # as well as adding or subtracting their results from a +Time+ object. For example: 5 8 # 6 # These methods use Time#advance for precise date calculations when using from_now, ago, etc.7 # as well as adding or subtracting their results from a Time object. For example:8 #9 9 # # equivalent to Time.now.advance(:months => 1) 10 10 # 1.month.from_now 11 11 # … … 16 16 # (4.months + 5.years).from_now 17 17 # 18 18 # While these methods provide precise calculation when used as in the examples above, care 19 # should be taken to note that this is not true if the result of `months', `years', etcis19 # should be taken to note that this is not true if the result of +months+, +years+, and so on is 20 20 # converted before use: 21 21 # 22 22 # # equivalent to 30.days.to_i.from_now … … 28 28 # In such cases, Ruby's core 29 29 # Date[http://stdlib.rubyonrails.org/libdoc/date/rdoc/index.html] and 30 30 # Time[http://stdlib.rubyonrails.org/libdoc/time/rdoc/index.html] should be used for precision 31 # date and time arithmetic 31 # date and time arithmetic. 32 32 module Time 33 33 def seconds 34 34 ActiveSupport::Duration.new(self, [[:seconds, self]]) 35 35 end 36 36 alias :second :seconds 37 37 38 # Returns the number of seconds for the specified number of minutes 39 # 40 # 30.minutes 41 # # => 1800 seconds 42 # 43 # 30.minutes.to_i 44 # # => 1800 38 45 def minutes 39 46 ActiveSupport::Duration.new(self * 60, [[:seconds, self * 60]]) 40 47 end 41 48 alias :minute :minutes 42 49 50 # Returns the number of seconds for the specified number of hours 51 # 52 # 2.hours 53 # # => 7200 seconds 54 # 55 # 2.hours.to_i 56 # # => 7200 43 57 def hours 44 58 ActiveSupport::Duration.new(self * 3600, [[:seconds, self * 3600]]) 45 59 end 46 60 alias :hour :hours 47 61 62 # Returns the number of seconds for the specified number of days. 63 # The default return is a string representation of the seconds in days. 64 # 65 # 2.days 66 # # => 2 days 67 # 68 # 2.days.to_i 69 # # => 172800 48 70 def days 49 71 ActiveSupport::Duration.new(self * 24.hours, [[:days, self]]) 50 72 end 51 73 alias :day :days 52 74 75 # Returns the number of seconds for the specified number of weeks. 76 # The default return is a string representation of the seconds in days. 77 # 78 # 3.weeks 79 # # => 21 days 80 # 81 # 3.weeks.to_i 82 # # => 1814400 53 83 def weeks 54 84 ActiveSupport::Duration.new(self * 7.days, [[:days, self * 7]]) 55 85 end 56 86 alias :week :weeks 57 87 88 # Returns the number of seconds for the specified number of fortnights. 89 # The default return is a string representation of the seconds in days. 90 # 91 # 2.fortnights 92 # # => 28 days 93 # 94 # 2.fortnights 95 # # => 2419200 58 96 def fortnights 59 97 ActiveSupport::Duration.new(self * 2.weeks, [[:days, self * 14]]) 60 98 end 61 99 alias :fortnight :fortnights 62 100 101 # Returns the number of seconds for the specified number of months. 102 # The default return is a string representation of the seconds in months. 103 # 104 # 2.months 105 # # => 2 months 106 # 107 # 2.months 108 # # => 5184000 63 109 def months 64 110 ActiveSupport::Duration.new(self * 30.days, [[:months, self]]) 65 111 end 66 112 alias :month :months 67 113 114 # Returns the number of seconds for the number of years specified. 115 # The default return is a string representation of the seconds in years. 116 # 117 # 5.years 118 # # => 5 years 119 # 120 # 5.years.to_i 121 # # => 157788000 68 122 def years 69 123 ActiveSupport::Duration.new(self * 365.25.days, [[:years, self]]) 70 124 end 71 125 alias :year :years 72 126 73 # Reads best without arguments: 10.minutes.ago 127 # Returns a +Time+ object of the current time adjusted backward by the specified amount. 128 # 129 # DateTime.now 130 # # => Sun, 01 Jul 2007 02:00:00 -0500 131 # 132 # 1.hour.ago 133 # # => Sun, 01 Jul 2007 01:00:00 -0500 74 134 def ago(time = ::Time.now) 75 135 time - self 76 136 end 77 137 78 # Reads best with argument: 10.minutes.until(time)138 # Reads best with argument: <tt>10.minutes.until(time)</tt> 79 139 alias :until :ago 80 140 81 # Reads best with argument: 10.minutes.since(time)141 # Reads best with argument: <tt>10.minutes.since(time)</tt> 82 142 def since(time = ::Time.now) 83 143 time + self 84 144 end 85 145 86 # Reads best without arguments: 10.minutes.from_now 146 # Returns a +Time+ object of the current time adjusted forward by the specified amount. 147 # 148 # DateTime.now 149 # # => Sun, 01 Jul 2007 02:00:00 -0500 150 # 151 # 1.hour.from_now 152 # # => Sun, 01 Jul 2007 03:00:00 -0500 87 153 alias :from_now :since 88 154 end 89 155 end
