Class: ActiveSupport::Duration

Inherits:
Object
  • Object
show all
Defined in:
activesupport/lib/active_support/duration.rb,
activesupport/lib/active_support/duration/iso8601_parser.rb,
activesupport/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
VARIABLE_PARTS = 
[:years, :months, :weeks, :days].freeze

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(value, parts, variable = nil) ⇒ Duration

:nodoc:



223
224
225
226
227
228
229
230
231
232
 
# File 'activesupport/lib/active_support/duration.rb', line 223

def initialize(value, parts, variable = nil) # :nodoc:
  @value, @parts = value, parts
  @parts.reject! { |k, v| v.zero? } unless value == 0
  @parts.freeze
  @variable = variable

  if @variable.nil?
    @variable = @parts.any? { |part, _| VARIABLE_PARTS.include?(part) }
  end
end

Dynamic Method Handling

This class handles dynamic methods through the method_missing method

#method_missing(method, *args, &block) ⇒ Object (private) 



506
507
508
 
# File 'activesupport/lib/active_support/duration.rb', line 506

def method_missing(method, *args, &block)
  value.public_send(method, *args, &block)
end

Instance Attribute Details

#value ⇒ Object (readonly)

Returns the value of attribute value



132
133
134
 
# File 'activesupport/lib/active_support/duration.rb', line 132

def value
  @value
end

Class Method Details

.===(other) ⇒ Object

:nodoc:



148
149
150
151
152
 
# File 'activesupport/lib/active_support/duration.rb', line 148

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}



188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
 
# File 'activesupport/lib/active_support/duration.rb', line 188

def build(value)
  unless value.is_a?(::Numeric)
    raise TypeError, "can't build an #{self.name} from a #{value.class.name}"
  end

  parts = {}
  remainder_sign = value <=> 0
  remainder = value.round(9).abs
  variable = false

  PARTS.each do |part|
    unless part == :seconds
      part_in_seconds = PARTS_IN_SECONDS[part]
      parts[part] = remainder.div(part_in_seconds) * remainder_sign
      remainder %= part_in_seconds

      unless parts[part].zero?
        variable ||= VARIABLE_PARTS.include?(part)
      end
    end
  end unless value == 0

  parts[:seconds] = remainder * remainder_sign

  new(value, parts, variable)
end

.days(value) ⇒ Object

:nodoc:



166
167
168
 
# File 'activesupport/lib/active_support/duration.rb', line 166

def days(value) # :nodoc:
  new(value * SECONDS_PER_DAY, { days: value }, true)
end

.hours(value) ⇒ Object

:nodoc:



162
163
164
 
# File 'activesupport/lib/active_support/duration.rb', line 162

def hours(value) # :nodoc:
  new(value * SECONDS_PER_HOUR, { hours: value }, false)
end

.minutes(value) ⇒ Object

:nodoc:



158
159
160
 
# File 'activesupport/lib/active_support/duration.rb', line 158

def minutes(value) # :nodoc:
  new(value * SECONDS_PER_MINUTE, { minutes: value }, false)
end

.months(value) ⇒ Object

:nodoc:



174
175
176
 
# File 'activesupport/lib/active_support/duration.rb', line 174

def months(value) # :nodoc:
  new(value * SECONDS_PER_MONTH, { months: value }, true)
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.



143
144
145
146
 
# File 'activesupport/lib/active_support/duration.rb', line 143

def parse(iso8601duration)
  parts = ISO8601Parser.new(iso8601duration).parse!
  new(calculate_total_seconds(parts), parts)
end

.seconds(value) ⇒ Object

:nodoc:



154
155
156
 
# File 'activesupport/lib/active_support/duration.rb', line 154

def seconds(value) # :nodoc:
  new(value, { seconds: value }, false)
end

.weeks(value) ⇒ Object

:nodoc:



170
171
172
 
# File 'activesupport/lib/active_support/duration.rb', line 170

def weeks(value) # :nodoc:
  new(value * SECONDS_PER_WEEK, { weeks: value }, true)
end

.years(value) ⇒ Object

:nodoc:



178
179
180
 
# File 'activesupport/lib/active_support/duration.rb', line 178

def years(value) # :nodoc:
  new(value * SECONDS_PER_YEAR, { years: value }, true)
end

Instance Method Details

#%(other) ⇒ Object

Returns the modulo of this Duration by another Duration or Numeric. Numeric values are treated as seconds.



306
307
308
309
310
311
312
313
314
 
# File 'activesupport/lib/active_support/duration.rb', line 306

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.



281
282
283
284
285
286
287
288
289
 
# File 'activesupport/lib/active_support/duration.rb', line 281

def *(other)
  if Scalar === other || Duration === other
    Duration.new(value * other.value, @parts.transform_values { |number| number * other.value }, @variable || other.variable?)
  elsif Numeric === other
    Duration.new(value * other, @parts.transform_values { |number| number * other }, @variable)
  else
    raise_type_error(other)
  end
end

#+(other) ⇒ Object

Adds another Duration or a Numeric to this Duration. Numeric values are treated as seconds.



262
263
264
265
266
267
268
269
270
271
272
 
# File 'activesupport/lib/active_support/duration.rb', line 262

def +(other)
  if Duration === other
    parts = @parts.merge(other._parts) do |_key, value, other_value|
      value + other_value
    end
    Duration.new(value + other.value, parts, @variable || other.variable?)
  else
    seconds = @parts.fetch(:seconds, 0) + other
    Duration.new(value + other, @parts.merge(seconds: seconds), @variable)
  end
end

#+@ ⇒ Object

:nodoc:



320
321
322
 
# File 'activesupport/lib/active_support/duration.rb', line 320

def +@ # :nodoc:
  self
end

#-(other) ⇒ Object

Subtracts another Duration or a Numeric from this Duration. Numeric values are treated as seconds.



276
277
278
 
# File 'activesupport/lib/active_support/duration.rb', line 276

def -(other)
  self + (-other)
end

#-@ ⇒ Object

:nodoc:



316
317
318
 
# File 'activesupport/lib/active_support/duration.rb', line 316

def -@ # :nodoc:
  Duration.new(-value, @parts.transform_values(&:-@), @variable)
end

#/(other) ⇒ Object

Divides this Duration by a Numeric and returns a new Duration.



292
293
294
295
296
297
298
299
300
301
302
 
# File 'activesupport/lib/active_support/duration.rb', line 292

def /(other)
  if Scalar === other
    Duration.new(value / other.value, @parts.transform_values { |number| number / other.value }, @variable)
  elsif Duration === other
    value / other.value
  elsif Numeric === other
    Duration.new(value / other, @parts.transform_values { |number| number / other }, @variable)
  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.



252
253
254
255
256
257
258
 
# File 'activesupport/lib/active_support/duration.rb', line 252

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.



335
336
337
338
339
340
341
 
# File 'activesupport/lib/active_support/duration.rb', line 335

def ==(other)
  if Duration === other
    other.value == value
  else
    other == value
  end
end

#_parts ⇒ Object

:nodoc:



475
476
477
 
# File 'activesupport/lib/active_support/duration.rb', line 475

def _parts # :nodoc:
  @parts
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.



438
439
440
 
# File 'activesupport/lib/active_support/duration.rb', line 438

def ago(time = ::Time.current)
  sum(-1, time)
end

#as_json(options = nil) ⇒ Object

:nodoc:



453
454
455
 
# File 'activesupport/lib/active_support/duration.rb', line 453

def as_json(options = nil) # :nodoc:
  to_i
end

#coerce(other) ⇒ Object

:nodoc:



239
240
241
242
243
244
245
246
247
248
 
# File 'activesupport/lib/active_support/duration.rb', line 239

def coerce(other) # :nodoc:
  case other
  when Scalar
    [other, self]
  when Duration
    [Scalar.new(other.value), self]
  else
    [Scalar.new(other), self]
  end
end

#encode_with(coder) ⇒ Object

:nodoc:



461
462
463
 
# File 'activesupport/lib/active_support/duration.rb', line 461

def encode_with(coder) # :nodoc:
  coder.map = { "value" => @value, "parts" => @parts }
end

#eql?(other) ⇒ Boolean

Returns true if other is also a Duration instance, which has the same parts as this one.

Returns:

  • (Boolean) 


420
421
422
 
# File 'activesupport/lib/active_support/duration.rb', line 420

def eql?(other)
  Duration === other && other.value.eql?(value)
end

#hash ⇒ Object 



424
425
426
 
# File 'activesupport/lib/active_support/duration.rb', line 424

def hash
  @value.hash
end

#in_days ⇒ Object

Returns the amount of days a duration covers as a float

12.hours.in_days # => 0.5



393
394
395
 
# File 'activesupport/lib/active_support/duration.rb', line 393

def in_days
  in_seconds / SECONDS_PER_DAY.to_f
end

#in_hours ⇒ Object

Returns the amount of hours a duration covers as a float

1.day.in_hours # => 24.0



386
387
388
 
# File 'activesupport/lib/active_support/duration.rb', line 386

def in_hours
  in_seconds / SECONDS_PER_HOUR.to_f
end

#in_minutes ⇒ Object

Returns the amount of minutes a duration covers as a float

1.day.in_minutes # => 1440.0



379
380
381
 
# File 'activesupport/lib/active_support/duration.rb', line 379

def in_minutes
  in_seconds / SECONDS_PER_MINUTE.to_f
end

#in_months ⇒ Object

Returns the amount of months a duration covers as a float

9.weeks.in_months # => 2.07



407
408
409
 
# File 'activesupport/lib/active_support/duration.rb', line 407

def in_months
  in_seconds / SECONDS_PER_MONTH.to_f
end

#in_weeks ⇒ Object

Returns the amount of weeks a duration covers as a float

2.months.in_weeks # => 8.696



400
401
402
 
# File 'activesupport/lib/active_support/duration.rb', line 400

def in_weeks
  in_seconds / SECONDS_PER_WEEK.to_f
end

#in_years ⇒ Object

Returns the amount of years a duration covers as a float

30.days.in_years # => 0.082



414
415
416
 
# File 'activesupport/lib/active_support/duration.rb', line 414

def in_years
  in_seconds / SECONDS_PER_YEAR.to_f
end

#init_with(coder) ⇒ Object

:nodoc:



457
458
459
 
# File 'activesupport/lib/active_support/duration.rb', line 457

def init_with(coder) # :nodoc:
  initialize(coder["value"], coder["parts"])
end

#inspect ⇒ Object

:nodoc:



444
445
446
447
448
449
450
451
 
# File 'activesupport/lib/active_support/duration.rb', line 444

def inspect # :nodoc:
  return "#{value} seconds" if @parts.empty?

  @parts.
    sort_by { |unit,  _ | PARTS.index(unit) }.
    map     { |unit, val| "#{val} #{val == 1 ? unit.to_s.chop : unit.to_s}" }.
    to_sentence(locale: false)
end

#instance_of?(klass) ⇒ Boolean

:nodoc:

Returns:

  • (Boolean) 


329
330
331
 
# File 'activesupport/lib/active_support/duration.rb', line 329

def instance_of?(klass) # :nodoc:
  Duration == klass || value.instance_of?(klass)
end

#is_a?(klass) ⇒ Boolean Also known as: kind_of?

:nodoc:

Returns:

  • (Boolean) 


324
325
326
 
# File 'activesupport/lib/active_support/duration.rb', line 324

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.



467
468
469
 
# File 'activesupport/lib/active_support/duration.rb', line 467

def iso8601(precision: nil)
  ISO8601Serializer.new(self, precision: precision).serialize
end

#parts ⇒ Object

Returns a copy of the parts hash that defines the duration



235
236
237
 
# File 'activesupport/lib/active_support/duration.rb', line 235

def parts
  @parts.dup
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.



430
431
432
 
# File 'activesupport/lib/active_support/duration.rb', line 430

def since(time = ::Time.current)
  sum(1, time)
end

#to_i ⇒ Object Also known as: in_seconds

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.



371
372
373
 
# File 'activesupport/lib/active_support/duration.rb', line 371

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"



347
348
349
 
# File 'activesupport/lib/active_support/duration.rb', line 347

def to_s
  @value.to_s
end

#variable? ⇒ Boolean

:nodoc:

Returns:

  • (Boolean) 


471
472
473
 
# File 'activesupport/lib/active_support/duration.rb', line 471

def variable? # :nodoc:
  @variable
end