Class: ActiveSupport::Duration

Relationships & Source Files
Inherits:	Object
Defined in:	activesupport/lib/active_support/duration.rb, activesupport/lib/active_support/duration/iso8601_parser.rb, activesupport/lib/active_support/duration/iso8601_serializer.rb

Overview

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)

Constant Summary

PARTS =
# File 'activesupport/lib/active_support/duration.rb', line 126

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

PARTS_IN_SECONDS =
# File 'activesupport/lib/active_support/duration.rb', line 116

{
  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 =
# File 'activesupport/lib/active_support/duration.rb', line 111
```
86400
```
SECONDS_PER_HOUR =
# File 'activesupport/lib/active_support/duration.rb', line 110
```
3600
```
SECONDS_PER_MINUTE =
# File 'activesupport/lib/active_support/duration.rb', line 109
```
60
```
SECONDS_PER_MONTH =

1/12 of a gregorian year

# File 'activesupport/lib/active_support/duration.rb', line 113
```
2629746
```
SECONDS_PER_WEEK =
# File 'activesupport/lib/active_support/duration.rb', line 112
```
604800
```
SECONDS_PER_YEAR =

length of a gregorian year (365.2425 days)

# File 'activesupport/lib/active_support/duration.rb', line 114
```
31556952
```

Class Method Summary

.build(value)

Creates a new Duration from a seconds value that is converted to the individual parts:
.parse(iso8601duration)

Creates a new Duration from string formatted according to ISO 8601 Duration.

Instance Method Summary

#%(other)

Returns the modulo of this Duration by another Duration or ::Numeric.
#*(other)

Multiplies this Duration by a ::Numeric and returns a new Duration.
#+(other)

Adds another Duration or a ::Numeric to this Duration.
#-(other)

Subtracts another Duration or a ::Numeric from this Duration.
#/(other)

Divides this Duration by a ::Numeric and returns a new Duration.
#<=>(other)

Compares one Duration with another or a ::Numeric to this Duration.
#==(other)

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) (also: #until, #before)

Calculates a new ::Time or ::Date that is as far in the past as this Duration represents.
#before(time = ::Time.current)

Alias for #ago.
#eql?(other) ⇒ Boolean

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
#iso8601(precision: nil)

Build ISO 8601 Duration string for this duration.
#kind_of?(klass)

Alias for #is_a?.
#since(time = ::Time.current) (also: #from_now, #after)

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

Returns the number of seconds that this Duration represents.
#to_s

Returns the amount of seconds a duration covers as a string.
#until(time = ::Time.current)

Alias for #ago.

Dynamic Method Handling

This class handles dynamic methods through the method_missing method

#method_missing(method, *args, &block) (private)

[ GitHub ]

# File 'activesupport/lib/active_support/duration.rb', line 428


def method_missing(method, *args, &block)
  value.public_send(method, *args, &block)
end

Class Method Details

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

[ GitHub ]

# File 'activesupport/lib/active_support/duration.rb', line 184


def build(value)
  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

.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 Duration::ISO8601Parser::ParsingError.

[ GitHub ]

# File 'activesupport/lib/active_support/duration.rb', line 139


def parse(iso8601duration)
  parts = ISO8601Parser.new(iso8601duration).parse!
  new(calculate_total_seconds(parts), parts)
end

Instance Attribute Details

#parts (rw)

[ GitHub ]

# File 'activesupport/lib/active_support/duration.rb', line 128


attr_accessor :value, :parts

#value (rw)

[ GitHub ]

# File 'activesupport/lib/active_support/duration.rb', line 128


attr_accessor :value, :parts

Instance Method Details

#%(other)

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

[ GitHub ]

# File 'activesupport/lib/active_support/duration.rb', line 281


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.

[ GitHub ]

# File 'activesupport/lib/active_support/duration.rb', line 256


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)

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

[ GitHub ]

# File 'activesupport/lib/active_support/duration.rb', line 236


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)

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

[ GitHub ]

# File 'activesupport/lib/active_support/duration.rb', line 251


def -(other)
  self + (-other)
end

#/(other)

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

[ GitHub ]

# File 'activesupport/lib/active_support/duration.rb', line 267


def /(other)
  if Scalar === other
    Duration.new(value / other.value, parts.map { |type, number| [type, number / other.value] })
  elsif Duration === other
    value / other.value
  elsif Numeric === other
    Duration.new(value / other, parts.map { |type, number| [type, number / other] })
  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.

[ GitHub ]

# File 'activesupport/lib/active_support/duration.rb', line 226


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.

[ GitHub ]

# File 'activesupport/lib/active_support/duration.rb', line 306


def ==(other)
  if Duration === other
    other.value == value
  else
    other == value
  end
end

#after(time = ::Time.current)

Alias for #since.

[ GitHub ]

# File 'activesupport/lib/active_support/duration.rb', line 362


alias :after :since

#ago(time = ::Time.current) Also known as: #until, #before

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

[ GitHub ]

# File 'activesupport/lib/active_support/duration.rb', line 366


def ago(time = ::Time.current)
  sum(-1, time)
end

#before(time = ::Time.current)

Alias for #ago.

[ GitHub ]

# File 'activesupport/lib/active_support/duration.rb', line 370


alias :before :ago

#eql?(other) ⇒ `Boolean`

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

[ GitHub ]

# File 'activesupport/lib/active_support/duration.rb', line 348


def eql?(other)
  Duration === other && other.value.eql?(value)
end

#from_now(time = ::Time.current)

Alias for #since.

[ GitHub ]

# File 'activesupport/lib/active_support/duration.rb', line 361


alias :from_now :since

#hash

[ GitHub ]

# File 'activesupport/lib/active_support/duration.rb', line 352


def hash
  @value.hash
end

#iso8601(precision: nil)

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

[ GitHub ]

# File 'activesupport/lib/active_support/duration.rb', line 396


def iso8601(precision: nil)
  ISO8601Serializer.new(self, precision: precision).serialize
end

#kind_of?(klass)

Alias for #is_a?.

[ GitHub ]

# File 'activesupport/lib/active_support/duration.rb', line 298


alias :kind_of? :is_a?

#since(time = ::Time.current) Also known as: #from_now, #after

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

[ GitHub ]

# File 'activesupport/lib/active_support/duration.rb', line 358


def since(time = ::Time.current)
  sum(1, time)
end

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

[ GitHub ]

# File 'activesupport/lib/active_support/duration.rb', line 342


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"

[ GitHub ]

# File 'activesupport/lib/active_support/duration.rb', line 318


def to_s
  @value.to_s
end

#until(time = ::Time.current)

Alias for #ago.

[ GitHub ]

# File 'activesupport/lib/active_support/duration.rb', line 369


alias :until :ago

Class: ActiveSupport::Duration

Overview

Constant Summary

Class Method Summary

Instance Attribute Summary

Instance Method Summary

Dynamic Method Handling

#method_missing(method, *args, &block) (private)

Class Method Details

.build(value)

.parse(iso8601duration)

Instance Attribute Details

#parts (rw)

#value (rw)

Instance Method Details

#%(other)

#*(other)

#+(other)

#-(other)

#/(other)

#<=>(other)

#==(other)

#after(time = ::Time.current)

#ago(time = ::Time.current) Also known as: #until, #before

#before(time = ::Time.current)

#eql?(other) ⇒ Boolean

#from_now(time = ::Time.current)

#hash

#iso8601(precision: nil)

#kind_of?(klass)

#since(time = ::Time.current) Also known as: #from_now, #after

#to_i

#to_s

#until(time = ::Time.current)

#eql?(other) ⇒ `Boolean`