ActiveSupport::Duration

class ActiveSupport::Duration

Parent:: Object

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_IN_SECONDS
SECONDS_PER_DAY
SECONDS_PER_HOUR
SECONDS_PER_MINUTE
SECONDS_PER_MONTH
SECONDS_PER_WEEK
SECONDS_PER_YEAR

Attributes

parts[RW]

value[RW]

Public Class Methods

parse(iso8601duration) Show 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 activesupport/lib/active_support/duration.rb, line 101
def parse(iso8601duration)
  parts = ISO8601Parser.new(iso8601duration).parse!
  new(calculate_total_seconds(parts), parts)
end

Public Instance Methods

*(other) Show source

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

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

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

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

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

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

/(other) Show source

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

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

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

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

==(other) Show source

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

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

after(time = ::Time.current)

Alias for: since

ago(time = ::Time.current) Show source

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

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

Also aliased as: until, before

before(time = ::Time.current)

Alias for: ago

eql?(other) Show source

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

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

from_now(time = ::Time.current)

Alias for: since

hash() Show source

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

iso8601(precision: nil) Show source

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

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

since(time = ::Time.current) Show source

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

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

Also aliased as: from_now, after

to_i() Show 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 activesupport/lib/active_support/duration.rb, line 266
def to_i
  @value.to_i
end

to_s() Show 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 activesupport/lib/active_support/duration.rb, line 242
def to_s
  @value.to_s
end

until(time = ::Time.current)

Alias for: ago