unit_measurements 4.8.0 → 4.10.0

data/lib/unit_measurements/conversion.rb

@@ -3,14 +3,28 @@
 # -*- warn_indent: true -*-
 
 module UnitMeasurements
+  # The +UnitMeasurements::Conversion+ mixin module defines methods for converting
+  # quantity of the measurement to various numeric types. These methods allow for
+  # flexibility in handling measurements in different numeric formats.
+  #
+  # This module is included into the +Measurement+ class to allow conversion of
+  # the measurement quantity to other numeric types.
+  #
+  # @see Measurement
+  # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+  # @since 1.7.0
   module Conversion
     # Converts quantity of the measurement to +Integer+.
     #
     # @example
-    #   UnitMeasurements::Weight.new(2.25567, "kg").to_i
-    #   => 2 kg
+    #   UnitMeasurements::Length.new(2.25567, "km").to_i
+    #   => 2 km
     #
     # @return [Measurement]
+    #   A new +Measurement+ instance with the quantity converted to an +Integer+.
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 1.7.0
     def to_i
       self.class.new(quantity.to_i, unit)
     end
@@ -18,10 +32,14 @@ module UnitMeasurements
     # Converts quantity of the measurement to +Float+.
     #
     # @example
-    #   UnitMeasurements::Weight.new(2.25567, "kg").to_f
-    #   => 2.25567 kg
+    #   UnitMeasurements::Length.new(2.25567, "km").to_f
+    #   => 2.25567 km
     #
     # @return [Measurement]
+    #   A new +Measurement+ instance with the quantity converted to a +Float+.
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 1.7.0
     def to_f
       self.class.new(quantity.to_f, unit)
     end
@@ -29,10 +47,14 @@ module UnitMeasurements
     # Converts quantity of the measurement to +Rational+.
     #
     # @example
-    #   UnitMeasurements::Weight.new(2.25567, "kg").to_r
-    #   => 225567/100000 kg
+    #   UnitMeasurements::Length.new(2.25567, "km").to_r
+    #   => 225567/100000 km
     #
     # @return [Measurement]
+    #   A new +Measurement+ instance with the quantity converted to a +Rational+.
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 1.7.0
     def to_r
       self.class.new(quantity.to_r, unit)
     end
@@ -40,10 +62,14 @@ module UnitMeasurements
     # Converts quantity of the measurement to +Complex+.
     #
     # @example
-    #   UnitMeasurements::Weight.new(2.25567, "kg").to_c
-    #   => 2.25567+0i kg
+    #   UnitMeasurements::Length.new(2.25567, "km").to_c
+    #   => 2.25567+0i km
     #
     # @return [Measurement]
+    #   A new +Measurement+ instance with the quantity converted to a +Complex+ number.
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 1.7.0
     def to_c
       self.class.new(quantity.to_c, unit)
     end
@@ -51,10 +77,14 @@ module UnitMeasurements
     # Converts quantity of the measurement to +BigDecimal+.
     #
     # @example
-    #   UnitMeasurements::Weight.new(2.25567, "kg").to_d
-    #   => 2.25567 kg
+    #   UnitMeasurements::Length.new(2.25567, "km").to_d
+    #   => 2.25567 km
     #
     # @return [Measurement]
+    #   A new +Measurement+ instance with the quantity converted to a +BigDecimal+.
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 1.7.0
     def to_d
       self.class.new(quantity.to_d, unit)
     end

data/lib/unit_measurements/errors/parse_error.rb

@@ -3,9 +3,29 @@
 # -*- warn_indent: true -*-
 
 module UnitMeasurements
+  # The +UnitMeasurements::ParseError+ class is used to represent an error
+  # condition where the library encounters difficulty in parsing a given string.
+  # This can occur due to invalid or unexpected input formats.
+  #
+  # The error message states that the parser encountered an error while parsing
+  # and provides the string that caused the parsing error.
+  #
+  # @see BaseError
+  # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+  # @since 1.0.0
   class ParseError < BaseError
+    # The input string that caused the error while parsing.
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 1.0.0
     attr_reader :string
 
+    # Initializes a new +ParseError+ instance.
+    #
+    # @param [String] string The input string that caused the error while parsing.
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 1.0.0
     def initialize(string)
       @string = string
 

data/lib/unit_measurements/errors/primitive_unit_already_set_error.rb

@@ -3,7 +3,18 @@
 # -*- warn_indent: true -*-
 
 module UnitMeasurements
+  # The +UnitMeasurements::PrimitiveUnitAlreadySetError+ class represents an
+  # error that occurs when attempting to set a primitive unit for the unit group
+  # that already has a primitive unit defined.
+  #
+  # @see BaseError
+  # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+  # @since 4.0.0
   class PrimitiveUnitAlreadySetError < BaseError
+    # Initializes a new +PrimitiveUnitAlreadySetError+ instance.
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 4.0.0
     def initialize
       super("The primitive unit is already set for the unit group.")
     end

data/lib/unit_measurements/errors/unit_already_defined_error.rb

@@ -3,9 +3,29 @@
 # -*- warn_indent: true -*-
 
 module UnitMeasurements
+  # The +UnitMeasurements::UnitAlreadyDefinedError+ class is used to indicate
+  # that an attempt was made to define a unit that has already been defined
+  # within a unit group.
+  #
+  # The error message states that the unit is already defined and provides the
+  # name of the conflicting unit.
+  #
+  # @see BaseError
+  # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+  # @since 1.0.0
   class UnitAlreadyDefinedError < BaseError
+    # The name of the unit that is already defined.
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 1.0.0
     attr_reader :unit
 
+    # Initializes a new +UnitAlreadyDefinedError+ instance.
+    #
+    # @param [String] unit The name of the unit that is already defined.
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 1.0.0
     def initialize(unit)
       @unit = unit
 

data/lib/unit_measurements/errors/unit_error.rb

@@ -3,9 +3,28 @@
 # -*- warn_indent: true -*-
 
 module UnitMeasurements
+  # The +UnitMeasurements::UnitError+ class is used to indicate that an invalid
+  # unit was encountered. The error message states that the unit is invalid and
+  # provides the name of the problematic unit.
+  #
+  # This error is raised when the unit is not defined within the unit group.
+  #
+  # @see BaseError
+  # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+  # @since 1.0.0
   class UnitError < BaseError
+    # The name of the invalid unit.
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 1.0.0
     attr_reader :unit
 
+    # Initializes a new +UnitError+ instance.
+    #
+    # @param [String] unit The name of the invalid unit.
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 1.0.0
     def initialize(unit)
       @unit = unit
 

data/lib/unit_measurements/formatter.rb

@@ -3,23 +3,45 @@
 # -*- warn_indent: true -*-
 
 module UnitMeasurements
+  # The +UnitMeasurements::Formatter+ mixin module contains methods for formatting
+  # measurements into human-readable strings. It provides the ability to customize
+  # the output format based on user-defined preferences.
+  #
+  # This module is included in the +Measurement+ class to allow customization of
+  # the output of the measurements.
+  #
+  # @see Measurement
+  # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+  # @since 1.1.0
   module Formatter
-    # The default format for formatting measurements.
+    # The default format used for formatting measurements. It is a format string
+    # containing placeholders for +quantity+ and +unit+.
     DEFAULT_FORMAT = "%.2<quantity>f %<unit>s".freeze
 
     # Formats measurement to certain formatted string specified by +format+.
-    # If +format+ is not specified, it uses +DEFAULT_FORMAT+ for
-    # formatting the measurement
+    # If +format+ is not specified, it uses +DEFAULT_FORMAT+ for formatting the
+    # measurement.
+    #
+    # The format method allows for customization of the output format of a
+    # measurement. It uses format placeholders for +quantity+ and +unit+. If no
+    # custom format is provided, it will use the +DEFAULT_FORMAT+.
     #
     # @example
-    #   UnitMeasurements::Weight.parse("2 kg").to("st").format
-    #   => "0.31 st"
-    #   UnitMeasurements::Weight.parse("2 kg").to("st").format("%.4<quantity>f %<unit>s")
-    #   => "0.3149 st"
+    #   UnitMeasurements::Length.new(1, "m").to("in").format
+    #   => "39.37 in"
+    #
+    #   UnitMeasurements::Length.new(1, "m").to("in").format("%.4<quantity>f %<unit>s")
+    #   => "39.3701 in"
+    #
+    # @param [String, optional] format
+    #   The custom format string for formatting the measurement. If not provided,
+    #   +DEFAULT_FORMAT+ is used.
     #
-    # @param [String] format
+    # @return [String] A formatted string representing the measurement.
     #
-    # @return [String]
+    # @see DEFAULT_FORMAT
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 1.1.0
     def format(format = nil)
       kwargs = {quantity: quantity, unit: unit.to_s}
 

data/lib/unit_measurements/math.rb

@@ -3,17 +3,32 @@
 # -*- warn_indent: true -*-
 
 module UnitMeasurements
+  # The +UnitMeasurements::Math+ mixin module provides methods for performing
+  # mathematical functions on the measurement.
+  #
+  # This module is included in the +Measurement+ class to allow mathematical
+  # functions on the measurement.
+  #
+  # @see Measurement
+  # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+  # @since 1.6.0
   module Math
-    # Rounds quantity of the measurement. If `ndigits` is not specified,
-    # quantity is rounded to +Integer+.
+    # Rounds quantity of the measurement. If +ndigits+ is not specified, quantity
+    # is rounded to +Integer+.
     #
     # @example
-    #   UnitMeasurements::Weight.new(1, "g").convert_to("st").round(4)
-    #   => 0.0002 st
+    #   UnitMeasurements::Length.new(17.625, "m").round
+    #   => 18 m
     #
-    # @param [Integer] ndigits
+    #   UnitMeasurements::Length.new(17.625, "m").round(2)
+    #   => 17.63 m
     #
-    # @return [Measurement]
+    # @param [Integer, optional] ndigits The number of digits to round to.
+    #
+    # @return [Measurement] A new +Measurement+ instance with the rounded quantity.
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 1.6.0
     def round(ndigits = 0)
       self.class.new(quantity.round(ndigits), unit)
     end
@@ -25,30 +40,52 @@ module UnitMeasurements
     #   => 17.625 m
     #
     # @return [Measurement]
+    #   A new +Measurement+ instance with the absolute value of the quantity.
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 1.6.0
     def abs
       self.class.new(quantity.abs, unit)
     end
 
-    # Rounds quantity of the measurement to next lower integer.
+    # Returns floored quantity of the measurement. If +ndigits+ is not specified,
+    # quantity is rounded to next lower +Integer+.
     #
     # @example
     #   UnitMeasurements::Length.new(17.625, "m").floor
     #   => 17 m
     #
-    # @return [Measurement]
-    def floor(*args)
-      self.class.new(quantity.floor(*args), unit)
+    #   UnitMeasurements::Length.new(17.625, "m").floor(2)
+    #   => 17.62 m
+    #
+    # @param [Integer, optional] ndigits The number of digits to round to.
+    #
+    # @return [Measurement] A new +Measurement+ instance with the floored quantity.
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 1.6.0
+    def floor(ndigits =0)
+      self.class.new(quantity.floor(ndigits), unit)
     end
 
-    # Rounds quantity of the measurement to next higher integer.
+    # Returns ceiled quantity of the measurement. If +ndigits+ is not specified,
+    # quantity is rounded to next higher +Integer+.
     #
     # @example
     #   UnitMeasurements::Length.new(17.625, "m").ceil
     #   => 18 m
     #
-    # @return [Measurement]
-    def ceil(*args)
-      self.class.new(quantity.ceil(*args), unit)
+    #   UnitMeasurements::Length.new(17.625, "m").ceil(2)
+    #   => 17.63 m
+    #
+    # @param [Integer, optional] ndigits The number of digits to round to.
+    #
+    # @return [Measurement] A new +Measurement+ instance with the ceiled quantity.
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 1.6.0
+    def ceil(ndigits =0)
+      self.class.new(quantity.ceil(ndigits), unit)
     end
   end
 end