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)

Namespace

Class

Methods

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 = 86400
SECONDS_PER_HOUR = 3600
SECONDS_PER_MINUTE = 60
SECONDS_PER_MONTH = 2629746
SECONDS_PER_WEEK = 604800
SECONDS_PER_YEAR = 31556952
VARIABLE_PARTS = [:years, :months, :weeks, :days].freeze

Attributes

[R] value

Class Public 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 
# 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
πŸ”Ž See on GitHub

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 
# File activesupport/lib/active_support/duration.rb, line 144
      def parse(iso8601duration)
        parts = ISO8601Parser.new(iso8601duration).parse!
        new(calculate_total_seconds(parts), parts)
      end
πŸ”Ž See on GitHub

Instance Public methods

%(other)

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

πŸ“ Source code 
# File activesupport/lib/active_support/duration.rb, line 312
    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
πŸ”Ž See on GitHub

*(other)

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

πŸ“ Source code 
# File activesupport/lib/active_support/duration.rb, line 287
    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
πŸ”Ž See on GitHub

+(other)

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

πŸ“ Source code 
# File activesupport/lib/active_support/duration.rb, line 268
    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
πŸ”Ž See on GitHub

-(other)

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

πŸ“ Source code 
# File activesupport/lib/active_support/duration.rb, line 282
    def -(other)
      self + (-other)
    end
πŸ”Ž See on GitHub

/(other)

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

πŸ“ Source code 
# File activesupport/lib/active_support/duration.rb, line 298
    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
πŸ”Ž See on GitHub

<=>(other)

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

πŸ“ Source code 
# File activesupport/lib/active_support/duration.rb, line 258
    def <=>(other)
      if Duration === other
        value <=> other.value
      elsif Numeric === other
        value <=> other
      end
    end
πŸ”Ž See on GitHub

==(other)

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

πŸ“ Source code 
# File activesupport/lib/active_support/duration.rb, line 341
    def ==(other)
      if Duration === other
        other.value == value
      else
        other == value
      end
    end
πŸ”Ž See on GitHub

after(time = ::Time.current)

Alias for: since

ago(time = ::Time.current)

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

Also aliased as: until, before
πŸ“ Source code 
# File activesupport/lib/active_support/duration.rb, line 444
    def ago(time = ::Time.current)
      sum(-1, time)
    end
πŸ”Ž See on GitHub

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 
# File activesupport/lib/active_support/duration.rb, line 426
    def eql?(other)
      Duration === other && other.value.eql?(value)
    end
πŸ”Ž See on GitHub

from_now(time = ::Time.current)

Alias for: since

hash()

πŸ“ Source code 
# File activesupport/lib/active_support/duration.rb, line 430
    def hash
      @value.hash
    end
πŸ”Ž See on GitHub

in_days()

Returns the amount of days a duration covers as a float

12.hours.in_days # => 0.5
πŸ“ Source code 
# File activesupport/lib/active_support/duration.rb, line 399
    def in_days
      in_seconds / SECONDS_PER_DAY.to_f
    end
πŸ”Ž See on GitHub

in_hours()

Returns the amount of hours a duration covers as a float

1.day.in_hours # => 24.0
πŸ“ Source code 
# File activesupport/lib/active_support/duration.rb, line 392
    def in_hours
      in_seconds / SECONDS_PER_HOUR.to_f
    end
πŸ”Ž See on GitHub

in_minutes()

Returns the amount of minutes a duration covers as a float

1.day.in_minutes # => 1440.0
πŸ“ Source code 
# File activesupport/lib/active_support/duration.rb, line 385
    def in_minutes
      in_seconds / SECONDS_PER_MINUTE.to_f
    end
πŸ”Ž See on GitHub

in_months()

Returns the amount of months a duration covers as a float

9.weeks.in_months # => 2.07
πŸ“ Source code 
# File activesupport/lib/active_support/duration.rb, line 413
    def in_months
      in_seconds / SECONDS_PER_MONTH.to_f
    end
πŸ”Ž See on GitHub

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 
# File activesupport/lib/active_support/duration.rb, line 406
    def in_weeks
      in_seconds / SECONDS_PER_WEEK.to_f
    end
πŸ”Ž See on GitHub

in_years()

Returns the amount of years a duration covers as a float

30.days.in_years # => 0.082
πŸ“ Source code 
# File activesupport/lib/active_support/duration.rb, line 420
    def in_years
      in_seconds / SECONDS_PER_YEAR.to_f
    end
πŸ”Ž See on GitHub

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 
# File activesupport/lib/active_support/duration.rb, line 473
    def iso8601(precision: nil)
      ISO8601Serializer.new(self, precision: precision).serialize
    end
πŸ”Ž See on GitHub

parts()

Returns a copy of the parts hash that defines the duration.

5.minutes.parts # => {:minutes=>5}
3.years.parts # => {:years=>3}
πŸ“ Source code 
# File activesupport/lib/active_support/duration.rb, line 241
    def parts
      @parts.dup
    end
πŸ”Ž See on GitHub

since(time = ::Time.current)

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

Also aliased as: from_now, after
πŸ“ Source code 
# File activesupport/lib/active_support/duration.rb, line 436
    def since(time = ::Time.current)
      sum(1, time)
    end
πŸ”Ž See on GitHub

to_i()

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.

Also aliased as: in_seconds
πŸ“ Source code 
# File activesupport/lib/active_support/duration.rb, line 377
    def to_i
      @value.to_i
    end
πŸ”Ž See on GitHub

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 
# File activesupport/lib/active_support/duration.rb, line 353
    def to_s
      @value.to_s
    end
πŸ”Ž See on GitHub

until(time = ::Time.current)

Alias for: ago