vector_number 0.4.3 → 0.6.0

data/lib/vector_number.rb

@@ -1,123 +1,196 @@
 # frozen_string_literal: true
 
-require_relative "vector_number/comparing"
-require_relative "vector_number/converting"
-require_relative "vector_number/enumerating"
-require_relative "vector_number/math_converting"
-require_relative "vector_number/mathing"
-require_relative "vector_number/querying"
-require_relative "vector_number/stringifying"
-require_relative "vector_number/version"
-
-# A class to add together anything.
+# VectorNumber provides a Numeric-like experience for doing arithmetics on heterogeneous objects,
+# with more advanced operations based on real vector spaces available when needed.
+#
+# VectorNumber inherits from +Object+ and includes +Enumerable+ and +Comparable+.
+# It implements mostly the same interface as +Numeric+ classes, but can {#coerce} any value.
+# Its behavior follows +Complex+ when possible.
+#
+# All instances are frozen after creation.
+#
+# **Creation**
+# - {.[]}: the simplest way to create a VectorNumber
+# - {#initialize}: an alternative way, with some advanced features
+#
+# **Comparing**
+# - {#==}: test for equal value
+# - {#eql?}: test for equal value and type
+# - {#<=>}: compare real values
+# - {#hash}: calculate hash value for use in +Hash+es
+#
+# **Querying**
+# - {#zero?}: check if all coefficients are zero
+# - {#nonzero?}: check if any coefficient is non-zero
+# - {#positive?}: check if all coefficients are positive
+# - {#negative?}: check if all coefficients are negative
+# - {#finite?}: check if all coefficients are finite
+# - {#infinite?}: check if any coefficient is non-finite
+# - {#numeric?}: test if value is real or complex
+# - {#nonnumeric?}: test if value is not real or complex
+# - {#integer?}: +false+
+# - {#real?}: +false+
+#
+# **Unary** **math** **operations**
+# - {#+}/{#dup}: return self
+# - {#-@}/{#neg}: negate value
+# - {#abs}/{#magnitude}: return absolute value (magnitude, length)
+# - {#abs2}: return square of absolute value
+#
+# **Arithmetic** **operations**
+# - {#coerce}: convert any object to a VectorNumber
+# - {#+}/{#add}: add object
+# - {#-}/{#sub}: subtract object
+# - {#*}/{#mult}: multiply (scale) by a real number
+# - {#/}/{#quo}: divide (scale) by a real number
+# - {#fdiv}: divide (scale) by a real number, using +fdiv+
+# - {#div}: perform integer division
+# - {#%}/{#modulo}: return modulus from integer division
+# - {#divmod}: combination of {#div} and {#modulo}
+# - {#remainder}: return remainder from integer division
+#
+# **Rounding**
+# - {#round}: round each coefficient
+# - {#ceil}: round each coefficient up towards +∞
+# - {#floor}: round each coefficient down towards -∞
+# - {#truncate}: truncate each coefficient towards 0
+#
+# **Type** **conversion**
+# - {#real}: return real part
+# - {#imag}/{#imaginary}: return imaginary part
+# - {#to_i}/{#to_int}: convert to +Integer+ if possible
+# - {#to_f}: convert to +Float+ if possible
+# - {#to_r}: convert to +Rational+ if possible
+# - {#to_d}: convert to +BigDecimal+ if possible
+# - {#to_c}: convert to +Complex+ if possible
+#
+# **Hash-like** **operations**
+# - {#each}/{#each_pair}: iterate through every pair of unit and coefficient
+# - {#[]}: get coefficient by unit
+# - {#unit?}/{#key?}: check if a unit has a non-zero coefficient
+# - {#units}/{#keys}: return an array of units
+# - {#coefficients}/#{values}: return an array of coefficients
+# - {#to_h}: convert to Hash
+#
+# **Miscellaneous** **methods**
+# - {.numeric_unit?}: check if a unit represents a numeric dimension
+# - {#size}: number of non-zero dimensions
+# - {#to_s}: return string representation suitable for printing
+# - {#inspect}: return string representation suitable for display
+# - {#dup}/{#+}: return self
+# - {#clone}: return self
+#
+# @since 0.1.0
 class VectorNumber
-  include Mathing
-  include MathConverting
-  include Converting
-  include Enumerating
-  include Comparing
-  include Querying
-  include Stringifying
+  require_relative "vector_number/comparing"
+  require_relative "vector_number/converting"
+  require_relative "vector_number/enumerating"
+  require_relative "vector_number/math_converting"
+  require_relative "vector_number/mathing"
+  require_relative "vector_number/querying"
+  require_relative "vector_number/stringifying"
+  require_relative "vector_number/version"
 
-  # Keys for possible options.
-  # Unknown options will be rejected when creating a vector.
-  #
-  # @return [Array<Symbol>]
-  #
-  # @since 0.2.0
-  KNOWN_OPTIONS = %i[mult].freeze
+  require_relative "vector_number/special_unit"
 
-  # Default values for options.
+  # List of special numeric unit constants.
   #
-  # @return [Hash{Symbol => Object}]
+  # @since 0.6.0
+  NUMERIC_UNITS = [SpecialUnit.new("1", "").freeze, SpecialUnit.new("i", "i").freeze].freeze
+  # Constant for real unit (1).
   #
-  # @since 0.2.0
-  DEFAULT_OPTIONS = { mult: :dot }.freeze
-
-  # Get a unit for +n+th numeric dimension, where 1 is real, 2 is imaginary.
+  # Its string representation is an empty string.
   #
-  # @since 0.2.0
-  UNIT = ->(n) { n }.freeze
-  # Constant for real unit.
+  # @since 0.6.0
+  R = NUMERIC_UNITS[0]
+  # Constant for imaginary unit (i).
   #
-  # @since 0.2.0
-  R = UNIT[1]
-  # Constant for imaginary unit.
+  # Its string representation is "i".
   #
-  # @since 0.1.0
-  I = UNIT[2]
+  # @since 0.6.0
+  I = NUMERIC_UNITS[1]
 
-  # Create new VectorNumber from a list of values, possibly specifying options.
+  # @group Creation
+  # Create new VectorNumber from a list of values.
   #
   # @example
   #   VectorNumber[1, 2, 3] # => (6)
   #   VectorNumber[[1, 2, 3]] # => (1⋅[1, 2, 3])
-  #   VectorNumber["b", VectorNumber::I, mult: :asterisk] # => (1*'b' + 1i)
   #   VectorNumber[] # => (0)
   #   VectorNumber["b", VectorNumber["b"]] # => (2⋅'b')
   #   VectorNumber["a", "b", "a"] # => (2⋅'a' + 1⋅'b')
   #
   # @param values [Array<Object>] values to put in the number
-  # @param options [Hash{Symbol => Object}] options for the number
-  # @option options [Symbol, String] :mult Multiplication symbol,
-  #   either a key from {MULT_STRINGS} or a literal string to use
-  # @return [VectorNumber]
+  def self.[](*values, **nil)
+    new(values)
+  end
+  # @endgroup
+
+  # Check if an object is a unit representing a numeric dimension
+  # (real or imaginary unit).
   #
-  # @since 0.1.0
-  def self.[](*values, **options)
-    new(values, options)
+  # @example
+  #   VectorNumber.numeric_unit?(VectorNumber::R) # => true
+  #   VectorNumber.numeric_unit?(VectorNumber::I) # => true
+  #   VectorNumber.numeric_unit?(:i) # => false
+  #
+  # @param unit [Object]
+  # @return [Boolean]
+  #
+  # @since 0.6.0
+  def self.numeric_unit?(unit)
+    NUMERIC_UNITS.include?(unit)
   end
 
   # Number of non-zero dimensions.
   #
   # @return [Integer]
-  #
-  # @since 0.1.0
   attr_reader :size
 
-  # Options used for this vector.
+  # @group Creation
+  # Create new VectorNumber from an array of +values+,
+  # possibly modifying coefficients with a block.
   #
-  # @see KNOWN_OPTIONS
+  # Using +VectorNumber.new([values...])+ directly is more efficient than +VectorNumber[values...]+.
   #
-  # @return [Hash{Symbol => Object}]
+  # +values+ can be:
+  # - an array of values (see {.[]});
+  # - a VectorNumber to copy;
+  # - a hash in the format returned by {#to_h};
+  # - +nil+ to specify a 0-sized vector (same as an empty array or hash).
   #
-  # @since 0.1.0
-  attr_reader :options
-
-  # Create new VectorNumber from +values+, possibly specifying +options+,
-  # possibly modifying coefficients with a block.
+  # Using a hash as +values+ is an advanced technique which allows to quickly
+  # construct a VectorNumber with desired units and coefficients,
+  # but it can also lead to unexpected results if care is not taken
+  # to provide only valid keys and values.
   #
   # @example
   #   VectorNumber.new(1, 2, 3) # ArgumentError
   #   VectorNumber.new([1, 2, 3]) # => (6)
-  #   VectorNumber.new(["b", VectorNumber::I], mult: :asterisk) # => (1*'b' + 1i)
+  #   VectorNumber.new(["b", VectorNumber::I]) # => (1⋅"b" + 1i)
   #   VectorNumber.new # => (0)
   # @example with a block
-  #   VectorNumber.new(["a", "b", "c", 3]) { _1 * 2 } # => (2⋅'a' + 2⋅'b' + 2⋅'c' + 6)
-  #   VectorNumber.new(["a", "b", "c", 3], &:-@) # => (-1⋅'a' - 1⋅'b' - 1⋅'c' - 3)
+  #   VectorNumber.new(["a", "b", "c", 3]) { _1 * 2 } # => (2⋅"a" + 2⋅"b" + 2⋅"c" + 6)
+  #   VectorNumber.new(["a", "b", "c", 3], &:-@) # => (-1⋅"a" - 1⋅"b" - 1⋅"c" - 3)
   #   VectorNumber.new(["a", "b", "c", 3], &:digits) # RangeError
-  #
-  # @param values [Array, VectorNumber, Hash{Object => Integer, Float, Rational, BigDecimal}, nil]
-  #   values for this number, hashes are treated like plain vector numbers
-  # @param options [Hash{Symbol => Object}, nil]
-  #   options for this number, if +values+ is a VectorNumber or contains it,
-  #   these will be merged with options from its +options+
-  # @option options [Symbol, String] :mult
-  #   text to use between unit and coefficient, see {Stringifying#to_s} for explanation
-  # @yieldparam coefficient [Integer, Float, Rational, BigDecimal]
-  # @yieldreturn [Integer, Float, Rational, BigDecimal] new coefficient
-  # @raise [RangeError] if any pesky non-reals get where they shouldn't
-  def initialize(values = nil, options = nil, &transform)
-    # @type var options: Hash[Symbol, Object]
+  # @example using hash for values
+  #   v = VectorNumber.new({1 => 15, "a" => 3.4, nil => -3}) # => (15 + 3.4⋅"a" - 3⋅)
+  #   v.to_h # => {1 => 15, "a" => 3.4, nil => -3}
+  #
+  # @param values [Array, VectorNumber, Hash{Object => Numeric}, nil] values for this vector
+  # @yieldparam coefficient [Numeric] a real number
+  # @yieldreturn [Numeric] new coefficient
+  # @raise [RangeError] if a block is used and it returns a non-number or non-real number
+  def initialize(values = nil, **nil, &transform)
     initialize_from(values)
     apply_transform(&transform)
     finalize_contents
-    save_options(options, values: values)
-    @options.freeze
     @data.freeze
     freeze
   end
 
+  # @group Miscellaneous methods
+
   # Return self.
   #
   # @return [VectorNumber]
@@ -149,11 +222,11 @@ class VectorNumber
   # Create new VectorNumber from a value or self, optionally applying a transform.
   #
   # @param from [Object] self if not specified
-  # @yieldparam coefficient [Integer, Float, Rational, BigDecimal]
-  # @yieldreturn [Integer, Float, Rational, BigDecimal] new coefficient
+  # @yieldparam coefficient [Numeric] a real number
+  # @yieldreturn [Numeric] new coefficient
   # @return [VectorNumber]
   def new(from = self, &transform)
-    self.class.new(from, options, &transform)
+    self.class.new(from, &transform)
   end
 
   # Check if +other+ is a real number.
@@ -162,16 +235,12 @@ class VectorNumber
   #
   # @param value [Object]
   # @return [Boolean]
-  #
-  # @since 0.1.0
   def real_number?(value)
     (value.is_a?(Numeric) && value.real?) || (value.is_a?(self.class) && value.numeric?(1))
   end
 
-  # @param values [Array, Hash{Object => Integer, Float, Rational, BigDecimal}, VectorNumber, nil]
+  # @param values [Array, Hash{Object => Numeric}, VectorNumber, nil]
   # @return [void]
-  #
-  # @since 0.1.0
   def initialize_from(values)
     @data = values.to_h and return if values.is_a?(VectorNumber)
 
@@ -190,8 +259,6 @@ class VectorNumber
 
   # @param value [VectorNumber, Numeric, Object]
   # @return [void]
-  #
-  # @since 0.1.0
   def add_value_to_data(value)
     case value
     when Numeric
@@ -205,8 +272,6 @@ class VectorNumber
 
   # @param value [Numeric]
   # @return [void]
-  #
-  # @since 0.1.0
   def add_numeric_value_to_data(value)
     @data[R] += value.real
     # Most numbers will be real, and this extra condition appreciably speeds up addition,
@@ -214,10 +279,8 @@ class VectorNumber
     @data[I] += value.imaginary unless value.real?
   end
 
-  # @param vector [VectorNumber, Hash{Object => Integer, Float, Rational, BigDecimal}]
+  # @param vector [VectorNumber, Hash{Object => Numeric}]
   # @return [void]
-  #
-  # @since 0.1.0
   def add_vector_to_data(vector)
     vector.each_pair do |unit, coefficient|
       raise RangeError, "#{coefficient} is not a real number" unless real_number?(coefficient)
@@ -226,12 +289,10 @@ class VectorNumber
     end
   end
 
-  # @yieldparam coefficient [Integer, Float, Rational, BigDecimal]
-  # @yieldreturn [Integer, Float, Rational, BigDecimal]
+  # @yieldparam coefficient [Numeric] a real number
+  # @yieldreturn [Numeric] new coefficient
   # @return [void]
   # @raise [RangeError]
-  #
-  # @since 0.1.0
   def apply_transform
     return unless block_given?
 
@@ -243,40 +304,8 @@ class VectorNumber
     end
   end
 
-  # @param options [Hash{Symbol => Object}, nil]
-  # @param values [Object] initializing object
-  # @return [void]
-  #
-  # @since 0.1.0
-  def save_options(options, values:)
-    @options =
-      case values
-      in VectorNumber
-        merge_options(values.options, options)
-      in Array[*, VectorNumber => vector, *]
-        merge_options(vector.options, options)
-      else
-        merge_options(DEFAULT_OPTIONS, options)
-      end
-  end
-
-  # @param base_options [Hash{Symbol => Object}]
-  # @param added_options [Hash{Symbol => Object}, nil]
-  # @return [Hash{Symbol => Object}]
-  #
-  # @since 0.3.0
-  def merge_options(base_options, added_options)
-    return base_options if !added_options || added_options.empty?
-    # Optimization for the common case of passing options through #new.
-    return base_options if added_options.equal?(base_options)
-
-    base_options.merge(added_options).slice(*KNOWN_OPTIONS)
-  end
-
   # Compact coefficients, calculate size and freeze data.
   # @return [void]
-  #
-  # @since 0.1.0
   def finalize_contents
     @data.delete_if { |_u, c| c.zero? }
     @data.freeze