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

build(value) Show source

# File activesupport/lib/active_support/duration.rb, line 183
def build(value)
  unless value.is_a?(::Numeric)
    raise TypeError, "can't build an #{self.name} from a #{value.class.name}"
  end

  parts = {}
  remainder = value.round(9)

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

  parts[:seconds] = remainder

  new(value, parts)
end

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}

parse(iso8601duration) Show source

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

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.

Public Instance Methods

%(other) Show source

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

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

*(other) Show source

# File activesupport/lib/active_support/duration.rb, line 259
def *(other)
  if Scalar === other || Duration === other
    Duration.new(value * other.value, parts.transform_values { |number| number * other.value })
  elsif Numeric === other
    Duration.new(value * other, parts.transform_values { |number| number * other })
  else
    raise_type_error(other)
  end
end

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

+(other) Show source

# File activesupport/lib/active_support/duration.rb, line 240
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)
  else
    seconds = @parts.fetch(:seconds, 0) + other
    Duration.new(value + other, @parts.merge(seconds: seconds))
  end
end

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

-(other) Show source

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

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

/(other) Show source

# File activesupport/lib/active_support/duration.rb, line 270
def /(other)
  if Scalar === other
    Duration.new(value / other.value, parts.transform_values { |number| number / other.value })
  elsif Duration === other
    value / other.value
  elsif Numeric === other
    Duration.new(value / other, parts.transform_values { |number| number / other })
  else
    raise_type_error(other)
  end
end

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

<=>(other) Show source

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

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

==(other) Show source

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

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

after(time = ::Time.current)

Alias for: since

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

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

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

Also aliased as: until, before

before(time = ::Time.current)

Alias for: ago

eql?(other) Show source

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

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

from_now(time = ::Time.current)

Alias for: since

hash() Show source

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

in_days() Show source

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

Returns the amount of days a duration covers as a float

12.hours.in_days # => 0.5

in_hours() Show source

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

Returns the amount of hours a duration covers as a float

1.day.in_hours # => 24.0

in_minutes() Show source

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

Returns the amount of minutes a duration covers as a float

1.day.in_minutes # => 1440.0

in_months() Show source

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

Returns the amount of months a duration covers as a float

9.weeks.in_months # => 2.07

in_seconds()

Alias for: to_i

in_weeks() Show source

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

Returns the amount of weeks a duration covers as a float

2.months.in_weeks # => 8.696

in_years() Show source

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

Returns the amount of years a duration covers as a float

30.days.in_years # => 0.082

iso8601(precision: nil) Show source

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

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

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

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

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

Also aliased as: from_now, after

to_i() Show source

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

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

to_s() Show source

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

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

1.day.to_s # => "86400"

until(time = ::Time.current)

Alias for: ago