123456789_123456789_123456789_123456789_123456789_

Class: ActiveSupport::Duration

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

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

Instance Method Summary

Dynamic Method Handling

This class handles dynamic methods through the method_missing method

#method_missing (private)

[ GitHub ] 

  


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



def method_missing(...)
  value.public_send(...)
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 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


  








  

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



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


  







Instance Attribute Details



  

    #value   (readonly)
  

  [ GitHub ]


  

  


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



attr_reader :value


  







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


  








  

    #*(other)  
  



  

    

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


  



  [ GitHub ]


  

  


# 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


  








  

    #+(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 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


  








  

    #-(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 282



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


  








  

    #<=>(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 258



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 341



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 440



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 444



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 448



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 426



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 439



alias :from_now :since


  








  

    #hash  
  

  [ GitHub ]


  

  


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



def hash
  @value.hash
end


  








  

    #in_days  
  



  

    

Returns the amount of days a duration covers as a float



12.hours.in_days # => 0.5


  



  [ GitHub ]


  

  


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



def in_days
  in_seconds / SECONDS_PER_DAY.to_f
end


  








  

    #in_hours  
  



  

    

Returns the amount of hours a duration covers as a float



1.day.in_hours # => 24.0


  



  [ GitHub ]


  

  


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



def in_hours
  in_seconds / SECONDS_PER_HOUR.to_f
end


  








  

    #in_minutes  
  



  

    

Returns the amount of minutes a duration covers as a float



1.day.in_minutes # => 1440.0


  



  [ GitHub ]


  

  


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



def in_minutes
  in_seconds / SECONDS_PER_MINUTE.to_f
end


  








  

    #in_months  
  



  

    

Returns the amount of months a duration covers as a float



9.weeks.in_months # => 2.07


  



  [ GitHub ]


  

  


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



def in_months
  in_seconds / SECONDS_PER_MONTH.to_f
end


  








  

    #in_seconds  
  



  

    

Alias for #to_i.


  



  [ GitHub ]


  

  


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



alias :in_seconds :to_i


  








  

    #in_weeks  
  



  

    

Returns the amount of weeks a duration covers as a float



2.months.in_weeks # => 8.696


  



  [ GitHub ]


  

  


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



def in_weeks
  in_seconds / SECONDS_PER_WEEK.to_f
end


  








  

    #in_years  
  



  

    

Returns the amount of years a duration covers as a float



30.days.in_years # => 0.082


  



  [ GitHub ]


  

  


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



def in_years
  in_seconds / SECONDS_PER_YEAR.to_f
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 473



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 333



alias :kind_of? :is_a?


  








  

    #parts  
  



  

    

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



5.minutes.parts # => {:minutes=>5}
3.years.parts # => {:years=>3}


  



  [ GitHub ]


  

  


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



def parts
  @parts.dup
end


  








  

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



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


  








  

    #to_i  
    Also known as: #in_seconds
  



  

    

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 377



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 353



def to_s
  @value.to_s
end


  








  

    #until(time = ::Time.current)  
  



  

    

Alias for #ago.


  



  [ GitHub ]


  

  


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



alias :until :ago