vector_number 0.3.0 → 0.4.0

data/lib/vector_number/math_converting.rb

@@ -3,45 +3,105 @@
 class VectorNumber
   # Various mathematical operations that are also conversions.
   module MathConverting
-    # Return the absolute value of the vector, i.e. its length.
+    # Calculate the absolute value of the vector, i.e. its length.
+    #
+    # @example
+    #   VectorNumber[5.3].abs # => 5.3
+    #   VectorNumber[-5.3i].magnitude # => 5.3
+    #   VectorNumber[-5.3i, "i"].abs # => 5.3935146240647205
+    #
     # @return [Float]
+    #
+    # @since 0.2.2
     def abs
-      Math.sqrt(coefficients.sum(&:abs2)) # rubocop:disable Naming/VariableNumber
+      Math.sqrt(abs2)
     end
 
     alias magnitude abs
 
-    # Return the square of absolute value.
+    # Calculate the square of absolute value.
+    #
+    # @example
+    #   VectorNumber[5.3].abs2 # => 5.3
+    #   VectorNumber[-5.3i].abs2 # => 5.3
+    #   VectorNumber[-5.3i, "i"].abs2 # => 29.09
+    #
     # @return [Float]
-    def abs2 # rubocop:disable Naming/VariableNumber
-      abs**2
+    #
+    # @since 0.2.2
+    def abs2
+      coefficients.sum(&:abs2)
     end
 
     # Return a new vector with every coefficient truncated using their +#truncate+.
+    #
+    # @example
+    #   VectorNumber[5.39].truncate # => (5)
+    #   VectorNumber[-5.35i].truncate # => (-5i)
+    #   VectorNumber[-5.35i, "i"].truncate # => (-5i + 1⋅'i')
+    #   VectorNumber[-5.35i, "i"].truncate(1) # => (-5.3i + 1⋅'i')
+    #   VectorNumber[-5.35i, "i"].truncate(-1) # => (0)
+    #
     # @param digits [Integer]
     # @return [VectorNumber]
+    #
+    # @since 0.2.1
     def truncate(digits = 0)
       new { _1.truncate(digits) }
     end
 
     # Return a new vector with every coefficient rounded using their +#ceil+.
+    #
+    # @example
+    #   VectorNumber[5.39].ceil # => (6)
+    #   VectorNumber[-5.35i].ceil # => (-5i)
+    #   VectorNumber[-5.35i, "i"].ceil # => (-5i + 1⋅'i')
+    #   VectorNumber[-5.35i, "i"].ceil(1) # => (-5.3i + 1⋅'i')
+    #   VectorNumber[-5.35i, "i"].ceil(-1) # => (10⋅'i')
+    #
     # @param digits [Integer]
     # @return [VectorNumber]
+    #
+    # @since 0.2.2
     def ceil(digits = 0)
       new { _1.ceil(digits) }
     end
 
     # Return a new vector with every coefficient rounded using their +#floor+.
+    #
+    # @example
+    #   VectorNumber[5.39].floor # => (5)
+    #   VectorNumber[-5.35i].floor # => (-6i)
+    #   VectorNumber[-5.35i, "i"].floor # => (-6i + 1⋅'i')
+    #   VectorNumber[-5.35i, "i"].floor(1) # => (-5.4i + 1⋅'i')
+    #   VectorNumber[-5.35i, "i"].floor(-1) # => (-10i)
+    #
     # @param digits [Integer]
     # @return [VectorNumber]
+    #
+    # @since 0.2.2
     def floor(digits = 0)
       new { _1.floor(digits) }
     end
 
     # Return a new vector with every coefficient rounded using their +#round+.
+    #
+    # @example
+    #   VectorNumber[-4.5i, "i"].round(half: :up) # => (-5i + 1⋅'i')
+    #   VectorNumber[-4.5i, "i"].round(half: :even) # => (-4i + 1⋅'i')
+    #   VectorNumber[-5.5i, "i"].round(half: :even) # => (-6i + 1⋅'i')
+    #   VectorNumber[-5.5i, "i"].round(half: :down) # => (-5i + 1⋅'i')
+    #   VectorNumber[-5.35i, "i"].round(1) # => (-5.4i + 1⋅'i')
+    #   VectorNumber[-5.35i, "i"].round(-1) # => (-10i)
+    #
     # @param digits [Integer]
-    # @param half [Symbol, nil] one of +:up+, +:down+ or +:even+, see +Float#round+ for meaning
+    # @param half [Symbol, nil] one of +:up+, +:down+ or +:even+,
+    #   see +Float#round+ for meaning
     # @return [VectorNumber]
+    #
+    # @see Float#round
+    #
+    # @since 0.2.2
     def round(digits = 0, half: :up)
       if defined?(BigDecimal)
         bd_mode =

data/lib/vector_number/mathing.rb

@@ -2,11 +2,26 @@
 
 class VectorNumber
   # Methods for performing actual math.
+  #
+  # All operators (like +*+) have aliases (like +mult+)
+  # to make method chaining easier and more natural.
   module Mathing
     # The coerce method provides support for Ruby type coercion.
-    # Unlike most numeric types, VectorNumber can coerce *anything*.
+    #
+    # Unlike other numeric types, VectorNumber can coerce *anything*.
+    #
+    # @example
+    #   VectorNumber["a"].coerce(5) # => [(5), (1⋅'a')]
+    #   VectorNumber[7].coerce([]) # => [(1⋅[]), (7)]
+    #   VectorNumber["a"] + 5 # => (1⋅'a' + 5)
+    #   # Direct reverse coercion doesn't work, but Numeric types know how to call #coerce:
+    #   5.coerce(VectorNumber["a"]) # RangeError
+    #   5 + VectorNumber["a"] # => (5 + 1⋅'a')
+    #
     # @param other [Object]
     # @return [Array(VectorNumber, VectorNumber)]
+    #
+    # @since 0.2.0
     def coerce(other)
       case other
       when VectorNumber
@@ -16,44 +31,87 @@ class VectorNumber
       end
     end
 
-    # Return self.
-    # @return [VectorNumber]
-    alias +@ itself
-
-    # Return new vector with negated coefficients.
-    # This preserves order of units.
+    # Return new vector with negated coefficients (additive inverse).
+    #
+    # @example
+    #   -VectorNumber[12, "i"] # => (-12 - 1⋅'i')
+    #   VectorNumber["a", "b", "a"].neg # => (-2⋅'a' - 1⋅'b')
+    #   -VectorNumber["a"] + VectorNumber["a"] # => (0)
+    #
     # @return [VectorNumber]
+    #
+    # @since 0.2.0
     def -@
       new(&:-@)
     end
 
+    # @since 0.3.0
     alias neg -@
 
-    # Return new vector as a sum of this and other value.
+    # Return new vector as a sum of this and +other+ value.
     # This is analogous to {VectorNumber.[]}.
+    #
+    # @example
+    #   VectorNumber[5] + 10 # => (15)
+    #   VectorNumber["a"].add(VectorNumber["b"]) # => (1⋅'a' + 1⋅'b')
+    #   VectorNumber["a"] + "b" # => (1⋅'a' + 1⋅'b')
+    # @example numeric types can be added in reverse
+    #   10 + VectorNumber[5] # => (15)
+    #   10 + VectorNumber["a"] # => (10 + 1⋅'a')
+    #
     # @param other [Object]
     # @return [VectorNumber]
+    #
+    # @since 0.2.0
     def +(other)
       new([self, other])
     end
 
+    # @since 0.3.0
     alias add +
 
-    # Return new vector as a sum of this and negative of the other value.
-    # This is analogous to {VectorNumber.[]}, but allows to negate anything.
+    # Return new vector as a sum of this and additive inverse of +other+ value.
+    #
+    # This is implemented through {#+} and {#-@}.
+    #
+    # @example
+    #   VectorNumber[5] - 3 # => (2)
+    #   VectorNumber["a"].sub(VectorNumber["b"]) # => (1⋅'a' - 1⋅'b')
+    #   VectorNumber["a"] - "b" # => (1⋅'a' - 1⋅'b')
+    # @example numeric types can be subtracted in reverse
+    #   3 - VectorNumber[5] # => (-2)
+    #   3 - VectorNumber["a"] # => (3 - 1⋅'a')
+    #
     # @param other [Object]
     # @return [VectorNumber]
+    #
+    # @since 0.2.0
     def -(other)
       self + new([other], &:-@)
     end
 
+    # @since 0.3.0
     alias sub -
 
-    # Multiply all coefficients by a real number, returning new vector.
-    # This effectively multiplies magnitude by the specified factor.
+    # Multiply all coefficients by a real +other+, returning new vector.
+    #
+    # This effectively multiplies {#magnitude} by +other+.
+    #
+    # @example
+    #   VectorNumber[5] * 2 # => (10)
+    #   VectorNumber["a", "b", 6].mult(2) # => (2⋅'a' + 2⋅'b' + 12)
+    #   VectorNumber["a"] * VectorNumber[2] # => (2⋅'a')
+    #   # Can't multiply by a non-real:
+    #   VectorNumber["a"] * VectorNumber["b"] # RangeError
+    # @example numeric types can be multiplied in reverse
+    #   2 * VectorNumber[5] # => (10)
+    #   2 * VectorNumber["a"] # => (2⋅'a')
+    #
     # @param other [Integer, Float, Rational, BigDecimal, VectorNumber]
     # @return [VectorNumber]
     # @raise [RangeError] if +other+ is not a number or +other+ can't be multiplied by this one
+    #
+    # @since 0.2.1
     def *(other)
       if real_number?(other)
         other = other.real
@@ -67,32 +125,67 @@ class VectorNumber
       end
     end
 
+    # @since 0.3.0
     alias mult *
 
-    # Divide all coefficients by a real number, returning new vector.
-    # This effectively multiplies magnitude by reciprocal of +other+.
+    # Divide all coefficients by a real +other+, returning new vector.
+    #
+    # This effectively multiplies {#magnitude} by reciprocal of +other+.
+    # @note This method never does integer division.
+    #
+    # @example
+    #   VectorNumber[10] / 2 # => (5)
+    #   VectorNumber["a", "b", 6].quo(2) # => (1/2⋅'a' + 1/2⋅'b' + 3/1)
+    #   VectorNumber["a"] / VectorNumber[2] # => (1/2⋅'a')
+    #   # Can't divide by a non-real:
+    #   VectorNumber["a"] / VectorNumber["b"] # RangeError
+    # @example numeric types can be divided in reverse
+    #   2 / VectorNumber[10] # => (1/5)
+    #   # Can't divide by a non-real:
+    #   2 / VectorNumber["a"] # RangeError
+    #
     # @param other [Integer, Float, Rational, BigDecimal, VectorNumber]
     # @return [VectorNumber]
     # @raise [RangeError] if +other+ is not a number or is not a real number
     # @raise [ZeroDivisionError] if +other+ is zero
+    #
+    # @since 0.2.1
     def /(other)
       check_divisibility(other)
 
       other = other.real
       # Prevent integer division, but without loss of accuracy.
-      other = Rational(other) if other.is_a?(Integer)
+      other = Rational(other) if other.integer?
       # @type var other: Float
       new { _1 / other }
     end
 
+    # @since 0.2.6
     alias quo /
+    # to fix syntax highlighting: /
 
-    # Divide all coefficients by a real number using +fdiv+, returning new vector
-    # with Float coefficients.
+    # Divide all coefficients by a real +other+ using +fdiv+,
+    # returning new vector with Float (or BigDecimal) coefficients.
+    #
+    # There isn't much benefit to this method, as {#/} doesn't do integer division,
+    # but it is provided for consistency.
+    #
+    # @example
+    #   VectorNumber[10].fdiv(2) # => (5.0)
+    #   VectorNumber["a", "b", 6].fdiv(2) # => (0.5⋅'a' + 0.5⋅'b' + 3.0)
+    #   VectorNumber["a"].fdiv(VectorNumber[2]) # => (0.5⋅'a')
+    #   # Can't divide by a non-real:
+    #   VectorNumber["a"].fdiv(VectorNumber["b"]) # RangeError
+    # @example reverse division may return non-vector results
+    #   2.fdiv(VectorNumber[10]) # => 0.2 (Float)
+    #   2.0.fdiv(VectorNumber[10]) # => (0.2) (VectorNumber)
+    #
     # @param other [Integer, Float, Rational, BigDecimal, VectorNumber]
     # @return [VectorNumber]
     # @raise [RangeError] if +other+ is not a number or is not a real number
     # @raise [ZeroDivisionError] if +other+ is zero
+    #
+    # @since 0.2.1
     def fdiv(other)
       check_divisibility(other)
 
@@ -100,14 +193,30 @@ class VectorNumber
       new { _1.fdiv(other) }
     end
 
-    # Divide all coefficients by +other+, rounding results with {#floor}.
+    # Divide all coefficients by a real +other+, rounding results with +#floor+.
+    #
     # This is requal to +(self / other).floor+.
+    #
+    # @example
+    #   VectorNumber[10].div(3) # => (3)
+    #   VectorNumber["a"].div(2) # => (0⋅'a')
+    #   VectorNumber["a"].div(VectorNumber[2]) # => (0⋅'a')
+    #   # Can't divide by a non-real:
+    #   VectorNumber["a"].div(VectorNumber["b"]) # RangeError
+    # @example numeric types can be divided in reverse
+    #   2.div(VectorNumber[10]) # => (0)
+    #   # Can't divide by a non-real:
+    #   2.div(VectorNumber["a"]) # RangeError
+    #
+    # @see #divmod
+    # @see #%
+    #
     # @param other [Integer, Float, Rational, BigDecimal, VectorNumber]
     # @return [VectorNumber]
     # @raise [RangeError] if +other+ is not a number or is not a real number
     # @raise [ZeroDivisionError] if +other+ is zero
-    # @see #divmod
-    # @see #%
+    #
+    # @since 0.2.6
     def div(other)
       check_divisibility(other)
 
@@ -115,16 +224,36 @@ class VectorNumber
       new { _1.div(other) }
     end
 
-    # Return the modulus of dividing self by +other+ as a vector.
-    # This is equal to +self - other * (self/other).floor+.
+    # Return the modulus of dividing self by a real +other+ as a vector.
+    #
+    # This is equal to +self - other * (self/other).floor+,
+    # or, alternatively, +self - other * self.div(other)+.
+    #
+    # @example
+    #   VectorNumber[10] % 3 # => (1)
+    #   VectorNumber["a", "b", 6].modulo(2) # => (1⋅'a' + 1⋅'b')
+    #   -VectorNumber["a"] % VectorNumber[2] # => (1⋅'a')
+    #   # Can't divide by a non-real:
+    #   VectorNumber["a"] % VectorNumber["b"] # RangeError
+    # @example numeric types can be divided in reverse
+    #   3 % VectorNumber[10] # => (3)
+    #   # Can't divide by a non-real:
+    #   3 % VectorNumber["a"] # RangeError
+    # @example compare to #remainder
+    #   VectorNumber[-5] % 3 # => (1)
+    #   VectorNumber[-5].remainder(3) # => (-2)
+    #
+    # @see #divmod
+    # @see #div
+    # @see #remainder
+    # @see Numeric#%
+    #
     # @param other [Integer, Float, Rational, BigDecimal, VectorNumber]
     # @return [VectorNumber]
     # @raise [RangeError] if +other+ is not a number or is not a real number
     # @raise [ZeroDivisionError] if +other+ is zero
-    # @see #divmod
-    # @see #div
-    # @see #remainder for alternative
-    # @see Numeric#% for examples
+    #
+    # @since 0.2.6
     def %(other)
       check_divisibility(other)
 
@@ -132,28 +261,63 @@ class VectorNumber
       new { _1 % other }
     end
 
+    # @since 0.2.6
     alias modulo %
 
-    # Return the quotient and modulus of dividing self by +other+.
+    # Return the quotient and modulus of dividing self by a real +other+.
     # There is no performance benefit compared to calling {#div} and {#%} separately.
+    #
+    # @example
+    #   VectorNumber[10].divmod(3) # => [(3), (1)]
+    #   VectorNumber["a"].divmod(2) # => [(0⋅'a'), (1⋅'a')]
+    #   VectorNumber["a"].divmod(VectorNumber[2]) # => [(0⋅'a'), (1⋅'a')]
+    #   # Can't divide by a non-real:
+    #   VectorNumber["a"].divmod(VectorNumber["b"]) # RangeError
+    # @example numeric types can be divided in reverse
+    #   3.divmod(VectorNumber[10]) # => [(0), (3)]
+    #   # Can't divide by a non-real:
+    #   3.divmod(VectorNumber["a"]) # RangeError
+    #
+    # @see #div
+    # @see #%
+    #
     # @param other [Integer, Float, Rational, BigDecimal, VectorNumber]
     # @return [Array(VectorNumber, VectorNumber)]
     # @raise [RangeError] if +other+ is not a number or is not a real number
     # @raise [ZeroDivisionError] if +other+ is zero
-    # @see #div
-    # @see #%
+    #
+    # @since 0.2.6
     def divmod(other)
       [div(other), modulo(other)]
     end
 
-    # Return the remainder of dividing self by +other+ as a vector.
+    # Return the remainder of dividing self by a real +other+ as a vector.
+    #
     # This is equal to +self - other * (self/other).truncate+.
+    #
+    # @example
+    #   VectorNumber[10].remainder(3) # => (1)
+    #   VectorNumber["a"].remainder(2) # => (1⋅'a')
+    #   -VectorNumber["a"].remainder(VectorNumber[2]) # => (-1⋅'a')
+    #   # Can't divide by a non-real:
+    #   VectorNumber["a"].remainder(VectorNumber["b"]) # RangeError
+    # @example numeric types can be divided in reverse
+    #   3.remainder(VectorNumber[10]) # => (3)
+    #   # Can't divide by a non-real:
+    #   3.remainder(VectorNumber["a"]) # RangeError
+    # @example compare to #%
+    #   VectorNumber[-5] % 3 # => (1)
+    #   VectorNumber[-5].remainder(3) # => (-2)
+    #
+    # @see #%
+    # @see Numeric#remainder
+    #
     # @param other [Integer, Float, Rational, BigDecimal, VectorNumber]
     # @return [VectorNumber]
     # @raise [RangeError] if +other+ is not a number or is not a real number
     # @raise [ZeroDivisionError] if +other+ is zero
-    # @see #% for alternative
-    # @see Numeric#remainder for examples
+    #
+    # @since 0.2.6
     def remainder(other)
       check_divisibility(other)
 
@@ -163,8 +327,18 @@ class VectorNumber
 
     private
 
+    # @param other [Object]
+    # @return [void]
+    # @raise [RangeError] unless +other+ is a real number
+    # @raise [ZeroDivisionError]
+    #
+    # @see real_number?
+    #
+    # @since 0.2.6
     def check_divisibility(other)
-      raise RangeError, "can't divide #{self} by #{other}", caller unless real_number?(other)
+      unless real_number?(other)
+        raise RangeError, "can't divide #{self} by #{other.inspect}", caller
+      end
       raise ZeroDivisionError, "divided by 0", caller if other.zero?
     end
   end

data/lib/vector_number/numeric_refinements.rb

@@ -1,21 +1,36 @@
 # frozen_string_literal: true
 
 class VectorNumber
-  # Refinements of Numeric classes to better work with VectorNumber and similar classes.
+  # Refinements of Numeric classes and Kernel to better work with VectorNumber and similar classes.
+  #
+  # These do not depend on +VectorNumber+ and can technically be used separately.
+  # Currently includes:
+  # - refinement for +Complex#<=>+ to work with classes implementing +<=>+;
+  # - refinement for +Kernel#BigDecimal+ to work with classes implementing +to_d+.
+  #
+  # @example activating refinements
+  #   require "vector_number/numeric_refinements"
+  #   using VectorNumber::NumericRefinements
+  #
+  # @since 0.2.0
   module NumericRefinements
     # Refinement module to provide a +#<=>+ method that can work backwards.
+    #
     # @note Currently only applies to Complex on *3.1*,
     #   as other numeric classes rely on +#coerce+.
+    # @example without refinements
+    #   VectorNumber[2] <=> Complex(1, 0) #=> 1
+    #   Complex(1, 0) <=> VectorNumber[2] #=> nil
+    # @example with refinements
+    #   require "vector_number/numeric_refinements"
+    #   using VectorNumber::NumericRefinements
+    #   VectorNumber[2] <=> Complex(1, 0) #=> 1
+    #   Complex(1, 0) <=> VectorNumber[2] #=> -1
+    #
+    # @since 0.2.1
     module CommutativeShuttle
       # Commutative +#<=>+.
-      # @example without refinements
-      #   Complex(1, 0) <=> VectorNumber[2] # => nil
-      #   VectorNumber[2] <=> Complex(1, 0) # => 1
-      # @example with refinements
-      #   require "vector_number/numeric_refinements"
-      #   using VectorNumber::NumericRefinements
-      #   Complex(1, 0) <=> VectorNumber[2] # => -1
-      #   VectorNumber[2] <=> Complex(1, 0) # => 1
+      # Tries to call +other <=> self+ if +self <=> other+ returns +nil+.
       def <=>(other)
         comparison = super
         return comparison if comparison || !other.respond_to?(:<=>)
@@ -30,7 +45,16 @@ class VectorNumber
     end
 
     # Refinement module to change Kernel#BigDecimal so it works with +#to_d+.
+    #
     # @note `BigDecimal` needs to be defined for this refinement to activate.
+    # @example without refinements
+    #   BigDecimal(VectorNumber[2]) # can't convert VectorNumber into BigDecimal (TypeError)
+    # @example with refinements
+    #   require "vector_number/numeric_refinements"
+    #   using VectorNumber::NumericRefinements
+    #   BigDecimal(VectorNumber[2]) #=> 0.2e1
+    #
+    # @since 0.2.1
     module BigDecimalToD
       # BigDecimal() that first tries to use #to_d.
       # @param value [Object]