class `ActiveSupport::Duration`

Active Support Duration

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)

Constants

`PARTS`

[:years, :months, :weeks, :days, :hours, :minutes, :seconds].freeze

`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

`SECONDS_PER_DAY`

`SECONDS_PER_HOUR`

`SECONDS_PER_MINUTE`

`SECONDS_PER_MONTH`

`SECONDS_PER_WEEK`

`SECONDS_PER_YEAR`

31556952

`VARIABLE_PARTS`

[:years, :months, :weeks, :days].freeze

Attributes

[R] value

Public class methods

`build(value)`

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}

Source code GitHub

# File activesupport/lib/active_support/duration.rb, line 189
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

`parse(iso8601duration)`

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.

Source code GitHub

# File activesupport/lib/active_support/duration.rb, line 144
def parse(iso8601duration)
  parts = ISO8601Parser.new(iso8601duration).parse!
  new(calculate_total_seconds(parts), parts)
end

Public instance methods

`%(other)`

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

Source code GitHub

# File activesupport/lib/active_support/duration.rb, line 309
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)`

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

Source code GitHub

# File activesupport/lib/active_support/duration.rb, line 284
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)`

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

Source code GitHub

# File activesupport/lib/active_support/duration.rb, line 265
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

`-(other)`

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

Source code GitHub

# File activesupport/lib/active_support/duration.rb, line 279
def -(other)
  self + (-other)
end

`/(other)`

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

Source code GitHub

# File activesupport/lib/active_support/duration.rb, line 295
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)`

Compares one Duration with another or a Numeric to this Duration. Numeric values are treated as seconds.

Source code GitHub

# File activesupport/lib/active_support/duration.rb, line 255
def <=>(other)
  if Duration === other
    value <=> other.value
  elsif Numeric === other
    value <=> other
  end
end

`==(other)`

Returns true if other is also a Duration instance with the same value, or if other == value.

Source code GitHub

# File activesupport/lib/active_support/duration.rb, line 338
def ==(other)
  if Duration === other
    other.value == value
  else
    other == value
  end
end

`after(time = ::Time.current)`

Alias for: since.

`ago(time = ::Time.current)`

Also aliased as: until, before.

Calculates a new Time or Date that is as far in the past as this Duration represents.

Source code GitHub

# File activesupport/lib/active_support/duration.rb, line 441
def ago(time = ::Time.current)
  sum(-1, time)
end

`before(time = ::Time.current)`

Alias for: ago.

`eql?(other)`

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

Source code GitHub

# File activesupport/lib/active_support/duration.rb, line 423
def eql?(other)
  Duration === other && other.value.eql?(value)
end

`from_now(time = ::Time.current)`

Alias for: since.

`hash()`

Source code GitHub

# File activesupport/lib/active_support/duration.rb, line 427
def hash
  @value.hash
end

`in_days()`

Returns the amount of days a duration covers as a float

12.hours.in_days # => 0.5

Source code GitHub

# File activesupport/lib/active_support/duration.rb, line 396
def in_days
  in_seconds / SECONDS_PER_DAY.to_f
end

`in_hours()`

Returns the amount of hours a duration covers as a float

1.day.in_hours # => 24.0

Source code GitHub

# File activesupport/lib/active_support/duration.rb, line 389
def in_hours
  in_seconds / SECONDS_PER_HOUR.to_f
end

`in_minutes()`

Returns the amount of minutes a duration covers as a float

1.day.in_minutes # => 1440.0

Source code GitHub

# File activesupport/lib/active_support/duration.rb, line 382
def in_minutes
  in_seconds / SECONDS_PER_MINUTE.to_f
end

`in_months()`

Returns the amount of months a duration covers as a float

9.weeks.in_months # => 2.07

Source code GitHub

# File activesupport/lib/active_support/duration.rb, line 410
def in_months
  in_seconds / SECONDS_PER_MONTH.to_f
end

`in_seconds()`

Alias for: to_i.

`in_weeks()`

Returns the amount of weeks a duration covers as a float

2.months.in_weeks # => 8.696

Source code GitHub

# File activesupport/lib/active_support/duration.rb, line 403
def in_weeks
  in_seconds / SECONDS_PER_WEEK.to_f
end

`in_years()`

Returns the amount of years a duration covers as a float

30.days.in_years # => 0.082

Source code GitHub

# File activesupport/lib/active_support/duration.rb, line 417
def in_years
  in_seconds / SECONDS_PER_YEAR.to_f
end

`iso8601(precision: nil)`

Build ISO 8601 Duration string for this duration. The precision parameter can be used to limit seconds’ precision of duration.

Source code GitHub

# File activesupport/lib/active_support/duration.rb, line 470
def iso8601(precision: nil)
  ISO8601Serializer.new(self, precision: precision).serialize
end

`parts()`

Returns a copy of the parts hash that defines the duration

Source code GitHub

# File activesupport/lib/active_support/duration.rb, line 238
def parts
  @parts.dup
end

`since(time = ::Time.current)`

Also aliased as: from_now, after.

Calculates a new Time or Date that is as far in the future as this Duration represents.

Source code GitHub

# File activesupport/lib/active_support/duration.rb, line 433
def since(time = ::Time.current)
  sum(1, time)
end

`to_i()`

Also aliased 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.

Source code GitHub

# File activesupport/lib/active_support/duration.rb, line 374
def to_i
  @value.to_i
end

`to_s()`

Returns the amount of seconds a duration covers as a string. For more information check to_i method.

1.day.to_s # => "86400"

Source code GitHub

# File activesupport/lib/active_support/duration.rb, line 350
def to_s
  @value.to_s
end

`until(time = ::Time.current)`

Alias for: ago.

Namespace

ActiveSupport::Duration::ISO8601Parser

class ActiveSupport::Duration

Constants

PARTS

PARTS_IN_SECONDS

SECONDS_PER_DAY

SECONDS_PER_HOUR

SECONDS_PER_MINUTE

SECONDS_PER_MONTH

SECONDS_PER_WEEK

SECONDS_PER_YEAR

VARIABLE_PARTS

Attributes

Public class methods

build(value)

parse(iso8601duration)

Public instance methods

%(other)

*(other)

+(other)

-(other)

/(other)

<=>(other)

==(other)

after(time = ::Time.current)

ago(time = ::Time.current)

before(time = ::Time.current)

eql?(other)

from_now(time = ::Time.current)

hash()

in_days()

in_hours()

in_minutes()

in_months()

in_seconds()

in_weeks()

in_years()

iso8601(precision: nil)

parts()

since(time = ::Time.current)

to_i()

to_s()

until(time = ::Time.current)

Namespace

Definition files

class `ActiveSupport::Duration`

`PARTS`

`PARTS_IN_SECONDS`

`SECONDS_PER_DAY`

`SECONDS_PER_HOUR`

`SECONDS_PER_MINUTE`

`SECONDS_PER_MONTH`

`SECONDS_PER_WEEK`

`SECONDS_PER_YEAR`

`VARIABLE_PARTS`

`build(value)`

`parse(iso8601duration)`

`%(other)`

`*(other)`

`+(other)`

`-(other)`

`/(other)`

`<=>(other)`

`==(other)`

`after(time = ::Time.current)`

`ago(time = ::Time.current)`

`before(time = ::Time.current)`

`eql?(other)`

`from_now(time = ::Time.current)`

`hash()`

`in_days()`

`in_hours()`

`in_minutes()`

`in_months()`

`in_seconds()`

`in_weeks()`

`in_years()`

`iso8601(precision: nil)`

`parts()`

`since(time = ::Time.current)`

`to_i()`

`to_s()`

`until(time = ::Time.current)`