Class: ActiveSupport::Duration
- Defined in:
- lib/active_support/duration.rb,
lib/active_support/duration/iso8601_parser.rb,
lib/active_support/duration/iso8601_serializer.rb
Overview
Provides accurate date and time measurements using Date#advance and Time#advance, respectively. It mainly supports the methods on Numeric.
1.month.ago # equivalent to Time.now.advance(months: -1)
Defined Under Namespace
Classes: ISO8601Parser, ISO8601Serializer, Scalar
Constant Summary collapse
- SECONDS_PER_MINUTE =
60
- SECONDS_PER_HOUR =
3600
- SECONDS_PER_DAY =
86400
- SECONDS_PER_WEEK =
604800
- SECONDS_PER_MONTH =
1/12 of a gregorian year
2629746
- SECONDS_PER_YEAR =
length of a gregorian year (365.2425 days)
31556952
- PARTS_IN_SECONDS =
{ seconds: 1, minutes: SECONDS_PER_MINUTE, hours: SECONDS_PER_HOUR, days: SECONDS_PER_DAY, weeks: SECONDS_PER_WEEK, months: SECONDS_PER_MONTH, years: SECONDS_PER_YEAR }.freeze
- PARTS =
[:years, :months, :weeks, :days, :hours, :minutes, :seconds].freeze
Instance Attribute Summary collapse
-
#parts ⇒ Object
Returns the value of attribute parts.
-
#value ⇒ Object
Returns the value of attribute value.
Class Method Summary collapse
-
.===(other) ⇒ Object
:nodoc:.
-
.build(value) ⇒ Object
Creates a new Duration from a seconds value that is converted to the individual parts:.
-
.days(value) ⇒ Object
:nodoc:.
-
.hours(value) ⇒ Object
:nodoc:.
-
.minutes(value) ⇒ Object
:nodoc:.
-
.months(value) ⇒ Object
:nodoc:.
-
.parse(iso8601duration) ⇒ Object
Creates a new Duration from string formatted according to ISO 8601 Duration.
-
.seconds(value) ⇒ Object
:nodoc:.
-
.weeks(value) ⇒ Object
:nodoc:.
-
.years(value) ⇒ Object
:nodoc:.
Instance Method Summary collapse
-
#%(other) ⇒ Object
Returns the modulo of this Duration by another Duration or Numeric.
-
#*(other) ⇒ Object
Multiplies this Duration by a Numeric and returns a new Duration.
-
#+(other) ⇒ Object
Adds another Duration or a Numeric to this Duration.
-
#-(other) ⇒ Object
Subtracts another Duration or a Numeric from this Duration.
-
#-@ ⇒ Object
:nodoc:.
-
#/(other) ⇒ Object
Divides this Duration by a Numeric and returns a new Duration.
-
#<=>(other) ⇒ Object
Compares one Duration with another or a Numeric to this Duration.
-
#==(other) ⇒ Object
Returns
true
ifother
is also a Duration instance with the samevalue
, or ifother == value
. -
#ago(time = ::Time.current) ⇒ Object
(also: #until, #before)
Calculates a new Time or Date that is as far in the past as this Duration represents.
-
#as_json(options = nil) ⇒ Object
:nodoc:.
-
#coerce(other) ⇒ Object
:nodoc:.
-
#eql?(other) ⇒ Boolean
Returns
true
ifother
is also a Duration instance, which has the same parts as this one. - #hash ⇒ Object
-
#initialize(value, parts) ⇒ Duration
constructor
:nodoc:.
-
#inspect ⇒ Object
:nodoc:.
-
#instance_of?(klass) ⇒ Boolean
:nodoc:.
-
#is_a?(klass) ⇒ Boolean
(also: #kind_of?)
:nodoc:.
-
#iso8601(precision: nil) ⇒ Object
Build ISO 8601 Duration string for this duration.
-
#respond_to_missing?(method, include_private = false) ⇒ Boolean
:nodoc:.
-
#since(time = ::Time.current) ⇒ Object
(also: #from_now, #after)
Calculates a new Time or Date that is as far in the future as this Duration represents.
-
#to_i ⇒ Object
Returns the number of seconds that this Duration represents.
-
#to_s ⇒ Object
Returns the amount of seconds a duration covers as a string.
Constructor Details
#initialize(value, parts) ⇒ Duration
:nodoc:
209 210 211 212 |
# File 'lib/active_support/duration.rb', line 209 def initialize(value, parts) #:nodoc: @value, @parts = value, parts.to_h @parts.default = 0 end |
Dynamic Method Handling
This class handles dynamic methods through the method_missing method
#method_missing(method, *args, &block) ⇒ Object (private)
412 413 414 |
# File 'lib/active_support/duration.rb', line 412 def method_missing(method, *args, &block) value.send(method, *args, &block) end |
Instance Attribute Details
#parts ⇒ Object
Returns the value of attribute parts.
126 127 128 |
# File 'lib/active_support/duration.rb', line 126 def parts @parts end |
#value ⇒ Object
Returns the value of attribute value.
126 127 128 |
# File 'lib/active_support/duration.rb', line 126 def value @value end |
Class Method Details
.===(other) ⇒ Object
:nodoc:
142 143 144 145 146 |
# File 'lib/active_support/duration.rb', line 142 def ===(other) #:nodoc: other.is_a?(Duration) rescue ::NoMethodError false end |
.build(value) ⇒ Object
Creates a new Duration from a seconds value that is converted to the individual parts:
ActiveSupport::Duration.build(31556952).parts # => {:years=>1}
ActiveSupport::Duration.build(2716146).parts # => {:months=>1, :days=>1}
182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 |
# File 'lib/active_support/duration.rb', line 182 def build(value) parts = {} remainder = value.to_f PARTS.each do |part| unless part == :seconds part_in_seconds = PARTS_IN_SECONDS[part] parts[part] = remainder.div(part_in_seconds) remainder = (remainder % part_in_seconds).round(9) end end parts[:seconds] = remainder parts.reject! { |k, v| v.zero? } new(value, parts) end |
.days(value) ⇒ Object
:nodoc:
160 161 162 |
# File 'lib/active_support/duration.rb', line 160 def days(value) #:nodoc: new(value * SECONDS_PER_DAY, [[:days, value]]) end |
.hours(value) ⇒ Object
:nodoc:
156 157 158 |
# File 'lib/active_support/duration.rb', line 156 def hours(value) #:nodoc: new(value * SECONDS_PER_HOUR, [[:hours, value]]) end |
.minutes(value) ⇒ Object
:nodoc:
152 153 154 |
# File 'lib/active_support/duration.rb', line 152 def minutes(value) #:nodoc: new(value * SECONDS_PER_MINUTE, [[:minutes, value]]) end |
.months(value) ⇒ Object
:nodoc:
168 169 170 |
# File 'lib/active_support/duration.rb', line 168 def months(value) #:nodoc: new(value * SECONDS_PER_MONTH, [[:months, value]]) end |
.parse(iso8601duration) ⇒ Object
Creates a new Duration from string formatted according to ISO 8601 Duration.
See ISO 8601 for more information. This method allows negative parts to be present in pattern. If invalid string is provided, it will raise ActiveSupport::Duration::ISO8601Parser::ParsingError
.
137 138 139 140 |
# File 'lib/active_support/duration.rb', line 137 def parse(iso8601duration) parts = ISO8601Parser.new(iso8601duration).parse! new(calculate_total_seconds(parts), parts) end |
.seconds(value) ⇒ Object
:nodoc:
148 149 150 |
# File 'lib/active_support/duration.rb', line 148 def seconds(value) #:nodoc: new(value, [[:seconds, value]]) end |
.weeks(value) ⇒ Object
:nodoc:
164 165 166 |
# File 'lib/active_support/duration.rb', line 164 def weeks(value) #:nodoc: new(value * SECONDS_PER_WEEK, [[:weeks, value]]) end |
.years(value) ⇒ Object
:nodoc:
172 173 174 |
# File 'lib/active_support/duration.rb', line 172 def years(value) #:nodoc: new(value * SECONDS_PER_YEAR, [[:years, value]]) end |
Instance Method Details
#%(other) ⇒ Object
Returns the modulo of this Duration by another Duration or Numeric. Numeric values are treated as seconds.
279 280 281 282 283 284 285 286 287 |
# File 'lib/active_support/duration.rb', line 279 def %(other) if Duration === other || Scalar === other Duration.build(value % other.value) elsif Numeric === other Duration.build(value % other) else raise_type_error(other) end end |
#*(other) ⇒ Object
Multiplies this Duration by a Numeric and returns a new Duration.
254 255 256 257 258 259 260 261 262 |
# File 'lib/active_support/duration.rb', line 254 def *(other) if Scalar === other || Duration === other Duration.new(value * other.value, parts.map { |type, number| [type, number * other.value] }) elsif Numeric === other Duration.new(value * other, parts.map { |type, number| [type, number * other] }) else raise_type_error(other) end end |
#+(other) ⇒ Object
Adds another Duration or a Numeric to this Duration. Numeric values are treated as seconds.
234 235 236 237 238 239 240 241 242 243 244 245 |
# File 'lib/active_support/duration.rb', line 234 def +(other) if Duration === other parts = @parts.dup other.parts.each do |(key, value)| parts[key] += value end Duration.new(value + other.value, parts) else seconds = @parts[:seconds] + other Duration.new(value + other, @parts.merge(seconds: seconds)) end end |
#-(other) ⇒ Object
Subtracts another Duration or a Numeric from this Duration. Numeric values are treated as seconds.
249 250 251 |
# File 'lib/active_support/duration.rb', line 249 def -(other) self + (-other) end |
#-@ ⇒ Object
:nodoc:
289 290 291 |
# File 'lib/active_support/duration.rb', line 289 def -@ #:nodoc: Duration.new(-value, parts.map { |type, number| [type, -number] }) end |
#/(other) ⇒ Object
Divides this Duration by a Numeric and returns a new Duration.
265 266 267 268 269 270 271 272 273 274 275 |
# File 'lib/active_support/duration.rb', line 265 def /(other) if Scalar === other Duration.new(value / other.value, parts.map { |type, number| [type, number / other.value] }) elsif Duration === other value / other.value elsif Numeric === other Duration.new(value / other, parts.map { |type, number| [type, number / other] }) else raise_type_error(other) end end |
#<=>(other) ⇒ Object
Compares one Duration with another or a Numeric to this Duration. Numeric values are treated as seconds.
224 225 226 227 228 229 230 |
# File 'lib/active_support/duration.rb', line 224 def <=>(other) if Duration === other value <=> other.value elsif Numeric === other value <=> other end end |
#==(other) ⇒ Object
Returns true
if other
is also a Duration instance with the same value
, or if other == value
.
304 305 306 307 308 309 310 |
# File 'lib/active_support/duration.rb', line 304 def ==(other) if Duration === other other.value == value else other == value end end |
#ago(time = ::Time.current) ⇒ Object Also known as: until, before
Calculates a new Time or Date that is as far in the past as this Duration represents.
364 365 366 |
# File 'lib/active_support/duration.rb', line 364 def ago(time = ::Time.current) sum(-1, time) end |
#as_json(options = nil) ⇒ Object
:nodoc:
378 379 380 |
# File 'lib/active_support/duration.rb', line 378 def as_json( = nil) #:nodoc: to_i end |
#coerce(other) ⇒ Object
:nodoc:
214 215 216 217 218 219 220 |
# File 'lib/active_support/duration.rb', line 214 def coerce(other) #:nodoc: if Scalar === other [other, self] else [Scalar.new(other), self] end end |
#eql?(other) ⇒ Boolean
Returns true
if other
is also a Duration instance, which has the same parts as this one.
346 347 348 |
# File 'lib/active_support/duration.rb', line 346 def eql?(other) Duration === other && other.value.eql?(value) end |
#hash ⇒ Object
350 351 352 |
# File 'lib/active_support/duration.rb', line 350 def hash @value.hash end |
#inspect ⇒ Object
:nodoc:
370 371 372 373 374 375 376 |
# File 'lib/active_support/duration.rb', line 370 def inspect #:nodoc: parts. reduce(::Hash.new(0)) { |h, (l, r)| h[l] += r; h }. sort_by { |unit, _ | PARTS.index(unit) }. map { |unit, val| "#{val} #{val == 1 ? unit.to_s.chop : unit.to_s}" }. to_sentence(locale: ::I18n.default_locale) end |
#instance_of?(klass) ⇒ Boolean
:nodoc:
298 299 300 |
# File 'lib/active_support/duration.rb', line 298 def instance_of?(klass) # :nodoc: Duration == klass || value.instance_of?(klass) end |
#is_a?(klass) ⇒ Boolean Also known as: kind_of?
:nodoc:
293 294 295 |
# File 'lib/active_support/duration.rb', line 293 def is_a?(klass) #:nodoc: Duration == klass || value.is_a?(klass) end |
#iso8601(precision: nil) ⇒ Object
Build ISO 8601 Duration string for this duration. The precision
parameter can be used to limit seconds’ precision of duration.
388 389 390 |
# File 'lib/active_support/duration.rb', line 388 def iso8601(precision: nil) ISO8601Serializer.new(self, precision: precision).serialize end |
#respond_to_missing?(method, include_private = false) ⇒ Boolean
:nodoc:
382 383 384 |
# File 'lib/active_support/duration.rb', line 382 def respond_to_missing?(method, include_private = false) #:nodoc: @value.respond_to?(method, include_private) end |
#since(time = ::Time.current) ⇒ Object Also known as: from_now, after
Calculates a new Time or Date that is as far in the future as this Duration represents.
356 357 358 |
# File 'lib/active_support/duration.rb', line 356 def since(time = ::Time.current) sum(1, time) end |
#to_i ⇒ Object
Returns the number of seconds that this Duration represents.
1.minute.to_i # => 60
1.hour.to_i # => 3600
1.day.to_i # => 86400
Note that this conversion makes some assumptions about the duration of some periods, e.g. months are always 1/12 of year and years are 365.2425 days:
# equivalent to (1.year / 12).to_i
1.month.to_i # => 2629746
# equivalent to 365.2425.days.to_i
1.year.to_i # => 31556952
In such cases, Ruby’s core Date and Time should be used for precision date and time arithmetic.
340 341 342 |
# File 'lib/active_support/duration.rb', line 340 def to_i @value.to_i end |
#to_s ⇒ Object
Returns the amount of seconds a duration covers as a string. For more information check to_i method.
1.day.to_s # => "86400"
316 317 318 |
# File 'lib/active_support/duration.rb', line 316 def to_s @value.to_s end |