class ActiveSupport::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
PARTS_IN_SECONDS
SECONDS_PER_DAY
SECONDS_PER_HOUR
SECONDS_PER_MINUTE
SECONDS_PER_MONTH
SECONDS_PER_WEEK
SECONDS_PER_YEAR
VARIABLE_PARTS

Attributes

value[R]

Public Class Methods

build(value) click to toggle source

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}

# File 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

parse(iso8601duration) click to toggle source

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.

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

Private Class Methods

calculate_total_seconds(parts) click to toggle source

# File lib/active_support/duration.rb, line 216
def calculate_total_seconds(parts)
  parts.inject(0) do |total, (part, value)|
    total + value * PARTS_IN_SECONDS[part]
  end
end

Public Instance Methods

%(other) click to toggle source

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

# File 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) click to toggle source

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

# File 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) click to toggle source

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

# File 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

-(other) click to toggle source

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

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

/(other) click to toggle source

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

# File 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) click to toggle source

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

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

==(other) click to toggle source

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

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

after(time = ::Time.current)

Alias for: since

ago(time = ::Time.current) click to toggle source

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

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

Also aliased as: until, before

before(time = ::Time.current)

Alias for: ago

eql?(other) click to toggle source

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

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

from_now(time = ::Time.current)

Alias for: since

hash() click to toggle source

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

in_days() click to toggle source

Returns the amount of days a duration covers as a float

12.hours.in_days # => 0.5

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

in_hours() click to toggle source

Returns the amount of hours a duration covers as a float

1.day.in_hours # => 24.0

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

in_minutes() click to toggle source

Returns the amount of minutes a duration covers as a float

1.day.in_minutes # => 1440.0

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

in_months() click to toggle source

Returns the amount of months a duration covers as a float

9.weeks.in_months # => 2.07

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

in_seconds()

Alias for: to_i

in_weeks() click to toggle source

Returns the amount of weeks a duration covers as a float

2.months.in_weeks # => 8.696

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

in_years() click to toggle source

Returns the amount of years a duration covers as a float

30.days.in_years # => 0.082

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

iso8601(precision: nil) click to toggle source

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

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

parts() click to toggle source

Returns a copy of the parts hash that defines the duration

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

since(time = ::Time.current) click to toggle source

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

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

Also aliased as: from_now, after

to_i() click to toggle source

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.

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

Also aliased as: in_seconds

to_s() click to toggle source

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

1.day.to_s # => "86400"

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

until(time = ::Time.current)

Alias for: ago

Private Instance Methods

method_missing(method, *args, &block) click to toggle source

# File lib/active_support/duration.rb, line 506
def method_missing(method, *args, &block)
  value.public_send(method, *args, &block)
end

raise_type_error(other) click to toggle source

# File lib/active_support/duration.rb, line 510
def raise_type_error(other)
  raise TypeError, "no implicit conversion of #{other.class} into #{self.class}"
end

respond_to_missing?(method, _) click to toggle source

# File lib/active_support/duration.rb, line 502
def respond_to_missing?(method, _)
  value.respond_to?(method)
end

sum(sign, time = ::Time.current) click to toggle source

# File lib/active_support/duration.rb, line 480
def sum(sign, time = ::Time.current)
  unless time.acts_like?(:time) || time.acts_like?(:date)
    raise ::ArgumentError, "expected a time or date, got #{time.inspect}"
  end

  if @parts.empty?
    time.since(sign * value)
  else
    @parts.inject(time) do |t, (type, number)|
      if type == :seconds
        t.since(sign * number)
      elsif type == :minutes
        t.since(sign * number * 60)
      elsif type == :hours
        t.since(sign * number * 3600)
      else
        t.advance(type => sign * number)
      end
    end
  end
end