vector_number 0.4.2 → 0.5.0

data/lib/vector_number.rb

@@ -1,23 +1,93 @@
 # 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**
+# - {#size}: number of non-zero coefficients
+# - {#options}: hash of options
+# - {#dup}/{#+}: return self
+# - {#clone}: return self
+# - {#to_s}: return string representation suitable for printing
+# - {#inspect}: return string representation suitable for display
 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.
@@ -47,6 +117,7 @@ class VectorNumber
   # @since 0.1.0
   I = UNIT[2]
 
+  # @group Creation
   # Create new VectorNumber from a list of values, possibly specifying options.
   #
   # @example
@@ -67,6 +138,7 @@ class VectorNumber
   def self.[](*values, **options)
     new(values, options)
   end
+  # @endgroup
 
   # Number of non-zero dimensions.
   #
@@ -84,9 +156,21 @@ class VectorNumber
   # @since 0.1.0
   attr_reader :options
 
+  # @group Creation
   # Create new VectorNumber from +values+, possibly specifying +options+,
   # possibly modifying coefficients with a block.
   #
+  # +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-dimensional vector (same as an empty array or hash).
+  #
+  # 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)
@@ -96,28 +180,32 @@ class VectorNumber
   #   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
+  # @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 => Integer, Float, Rational, BigDecimal}, nil]
-  #   values for this number, hashes are treated like plain vector numbers
+  # @param values [Array, VectorNumber, Hash{Object => Numeric}, nil] values for this vector
   # @param options [Hash{Symbol => Object}, nil]
-  #   options for this number, if +values+ is a VectorNumber or contains it,
+  #   options for this vector, 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, &)
+  # @option options [Symbol, String] :mult Multiplication symbol,
+  #   either a key from {MULT_STRINGS} or a literal string to use
+  # @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, options = nil, &transform)
     # @type var options: Hash[Symbol, Object]
     initialize_from(values)
-    apply_transform(&)
+    apply_transform(&transform)
     finalize_contents
-    save_options(options, values:)
+    save_options(options, values)
     @options.freeze
     @data.freeze
     freeze
   end
 
+  # @group Miscellaneous methods
+
   # Return self.
   #
   # @return [VectorNumber]
@@ -149,11 +237,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, &)
-    self.class.new(from, options, &)
+  def new(from = self, &transform)
+    self.class.new(from, options, &transform)
   end
 
   # Check if +other+ is a real number.
@@ -162,16 +250,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 +274,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 +287,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 +294,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 +304,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?
 
@@ -246,9 +322,7 @@ class VectorNumber
   # @param options [Hash{Symbol => Object}, nil]
   # @param values [Object] initializing object
   # @return [void]
-  #
-  # @since 0.1.0
-  def save_options(options, values:)
+  def save_options(options, values)
     @options =
       case values
       in VectorNumber
@@ -263,8 +337,6 @@ class VectorNumber
   # @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.
@@ -275,8 +347,6 @@ class VectorNumber
 
   # 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

data/sig/vector_number.rbs

@@ -1,43 +1,22 @@
-type vector_type = VectorNumber
-type real_number = Integer | Float | Rational | BigDecimal
+# A class to add together anything.
+class VectorNumber
+  # ---- Generic types ----
+  type real_number = Integer | Float | Rational | BigDecimal
 
-type in_value_type = untyped
-type unit_type = untyped
-type coefficient_type = real_number
+  type in_value_type = untyped
+  type unit_type = untyped
+  type coefficient_type = real_number
 
-type list[T] = Array[T]
+  type list[T] = Array[T]
 
-type plain_vector_type = Hash[unit_type, coefficient_type]
-type units_list_type = list[unit_type]
-type coefficients_list_type = list[coefficient_type]
-type each_value_type = [unit_type, coefficient_type]
+  type plain_instance = Hash[unit_type, coefficient_type]
+  type units_list_type = list[unit_type]
+  type coefficients_list_type = list[coefficient_type]
+  type each_value_type = [unit_type, coefficient_type]
 
-type options_type = Hash[Symbol, untyped]
+  type options_type = Hash[Symbol, untyped]
 
-interface _BaseMethods
-  def size: -> Integer
-  def options: -> options_type
-
-  # private
-  def new: () { (coefficient_type value) -> coefficient_type } -> vector_type
-         | (in_value_type) { (coefficient_type value) -> coefficient_type } -> vector_type
-         | () -> vector_type
-         | (in_value_type) -> vector_type
-  def real_number?: (real_number value) -> true
-                  | (vector_type) -> bool
-                  | (in_value_type value) -> false
-end
-
-# A class to add together anything.
-class VectorNumber
-  include _BaseMethods
-  include VectorNumber::Mathing
-  include VectorNumber::MathConverting
-  include VectorNumber::Converting
-  include VectorNumber::Enumerating
-  include VectorNumber::Comparing
-  include VectorNumber::Querying
-  include VectorNumber::Stringifying
+  # ---- Constants ----
 
   VERSION: String
 
@@ -48,10 +27,15 @@ class VectorNumber
   R: Complex
   I: Complex
 
-  def self.[]: (*unit_type values, **options_type options) -> vector_type
+  # ---- Public methods ----
+
+  def self.[]: (*unit_type values, **options_type options) -> instance
+
+  def size: -> Integer
+  def options: -> options_type
 
   def initialize:
-    (?(units_list_type | plain_vector_type | vector_type)? values, ?options_type? options)
+    (?(units_list_type | plain_instance | instance)? values, ?options_type? options)
     ?{ (coefficient_type coefficient) -> coefficient_type }
     -> void
 
@@ -64,196 +48,179 @@ class VectorNumber
 
   @size: Integer
   @options: options_type
-  @data: plain_vector_type
+  @data: plain_instance
 
-  def initialize_from: ((units_list_type | plain_vector_type | vector_type)? values) -> void
+  def new: () { (coefficient_type value) -> coefficient_type } -> instance
+         | (in_value_type) { (coefficient_type value) -> coefficient_type } -> instance
+         | () -> instance
+         | (in_value_type) -> instance
 
-  def add_value_to_data: ((vector_type | Numeric | unit_type) value) -> void
+  def real_number?: (real_number value) -> true
+                  | (instance) -> bool
+                  | (in_value_type value) -> false
+
+  def initialize_from: ((units_list_type | plain_instance | instance)? values) -> void
+
+  def add_value_to_data: ((instance | Numeric | unit_type) value) -> void
 
   def add_numeric_value_to_data: (Numeric value) -> void
 
-  def add_vector_to_data: ((vector_type | plain_vector_type) vector) -> void
+  def add_vector_to_data: ((instance | plain_instance) vector) -> void
 
   def apply_transform: () ?{ (coefficient_type value) -> coefficient_type } -> void
 
-  def save_options: (options_type? options, values: in_value_type) -> void
+  def save_options: (options_type? options, in_value_type values) -> void
   def merge_options: (options_type base_options, options_type added_options) -> options_type
-  def default_options: () -> options_type
-  def known_options: () -> list[Symbol]
 
   def finalize_contents: () -> void
+end
 
-  # Methods for performing actual math.
-  module Mathing
-    include _BaseMethods
-
-    def coerce: (in_value_type) -> [vector_type, self]
-
-    def -@: () -> vector_type
-    alias neg -@
-
-    def +: (in_value_type) -> vector_type
-    alias add +
-
-    def -: (in_value_type) -> vector_type
-    alias sub -
-
-    def *: (real_number | vector_type) -> vector_type
-    alias mult *
-
-    def /: (real_number | vector_type) -> vector_type
-    alias quo /
-
-    def fdiv: (real_number | vector_type) -> vector_type
+# Methods for performing actual math.
+class VectorNumber
+  def coerce: (in_value_type) -> [instance, self]
 
-    def div: (real_number | vector_type) -> vector_type
+  def -@: () -> instance
+  alias neg -@
 
-    def %: (real_number | vector_type) -> vector_type
-    alias modulo %
+  def +: (in_value_type) -> instance
+  alias add +
 
-    def divmod: (real_number | vector_type) -> [vector_type, vector_type]
+  def -: (in_value_type) -> instance
+  alias sub -
 
-    def remainder: (real_number | vector_type) -> vector_type
+  def *: (real_number | instance) -> instance
+  alias mult *
 
-    private
+  def /: (real_number | instance) -> instance
+  alias quo /
 
-    def check_divisibility: (real_number | vector_type) -> void
-  end
+  def fdiv: (real_number | instance) -> instance
 
-  # Various mathematical operations that are also conversions.
-  module MathConverting
-    include _BaseMethods
-    include Enumerating
+  def div: (real_number | instance) -> instance
 
-    def abs: () -> Float
+  def %: (real_number | instance) -> instance
+  alias modulo %
 
-    def abs2: () -> Float
+  def divmod: (real_number | instance) -> [instance, instance]
 
-    def truncate: (Integer) -> vector_type
+  def remainder: (real_number | instance) -> instance
 
-    def ceil: (Integer) -> vector_type
+  private
 
-    def floor: (Integer) -> vector_type
+  def check_divisibility: (real_number | instance) -> void
+end
 
-    def round: (Integer, ?half: (:up | :down | :even)) -> vector_type
-  end
+# Various mathematical operations that are also conversions.
+class VectorNumber
+  def abs: () -> Float
 
-  # Methods for converting to different number classes.
-  module Converting
-    include _BaseMethods
-    include Querying
+  def abs2: () -> Float
 
-    def real: () -> real_number
+  def truncate: (?Integer) -> instance
 
-    def imaginary: () -> real_number
-    alias imag imaginary
+  def ceil: (?Integer) -> instance
 
-    def to_i: () -> Integer
-            | () -> void
-    alias to_int to_i
+  def floor: (?Integer) -> instance
 
-    def to_f: () -> Float
-            | () -> void
+  def round: (?Integer, ?half: (:up | :down | :even)) -> instance
+end
 
-    def to_r: () -> Rational
-            | () -> void
+# Methods for converting to different number classes.
+class VectorNumber
+  def real: () -> real_number
 
-    def to_d: (?Integer?) -> BigDecimal
-            | (?Integer?) -> void
+  def imaginary: () -> real_number
+  alias imag imaginary
 
-    def to_c: () -> Complex
-            | () -> void
+  def to_i: () -> Integer
+  alias to_int to_i
 
-    def truncate: (?Integer digits) -> vector_type
+  def to_f: () -> Float
 
-    private
+  def to_r: () -> Rational
 
-    def raise_convert_error: (Class) -> void
-  end
+  def to_d: (?Integer?) -> BigDecimal
 
-  # Methods for enumerating values of the number.
-  module Enumerating
-    include _BaseMethods
-    include _Each[each_value_type]
-    include Enumerable[each_value_type]
+  def to_c: () -> Complex
 
-    def each: () { (unit_type unit, coefficient_type coefficient) -> void } -> self
-            | () -> Enumerator[each_value_type, Integer]
-            | ...
-    alias each_pair each
+  private
 
-    def units: () -> units_list_type
-    alias keys units
+  def raise_convert_error: (Class) -> void
+end
 
-    def coefficients: () -> coefficients_list_type
-    alias values coefficients
+class VectorNumber
+  include _Each[each_value_type]
+  include Enumerable[each_value_type]
 
-    def to_h: () -> plain_vector_type
-            | () { (unit_type, coefficient_type) -> each_value_type } -> plain_vector_type
+  def each: () { (unit_type unit, coefficient_type coefficient) -> void } -> self
+          | () -> Enumerator[each_value_type, Integer]
+          | ...
+  alias each_pair each
 
-    def []: (unit_type unit) -> coefficient_type
+  def units: () -> units_list_type
+  alias keys units
 
-    def unit?: (unit_type unit) -> bool
-    alias key? unit?
-  end
+  def coefficients: () -> coefficients_list_type
+  alias values coefficients
 
-  # Methods for comparing with other numbers.
-  module Comparing
-    include _BaseMethods
-    include Enumerating
-    include Converting
-    include Querying
+  def to_h: () -> plain_instance
+          | () { (unit_type, coefficient_type) -> each_value_type } -> plain_instance
 
-    def ==: (in_value_type other) -> bool
+  def []: (unit_type unit) -> coefficient_type
 
-    def eql?: (in_value_type other) -> bool
+  def unit?: (unit_type unit) -> bool
+  alias key? unit?
+end
 
-    def hash: () -> Integer
+# Methods for comparing with other numbers.
+class VectorNumber
+  def ==: (in_value_type other) -> bool
 
-    def <=>: (in_value_type other) -> Integer?
-  end
+  def eql?: (in_value_type other) -> bool
 
-  # Methods for querying state of the number.
-  # Mostly modeled after {::Complex}.
-  module Querying
-    include Enumerating
+  def hash: () -> Integer
 
-    def numeric?: (?Integer) -> bool
+  def <=>: (in_value_type other) -> Integer?
+end
 
-    def nonnumeric?: (?Integer) -> bool
+# Methods for querying state of the number.
+# Mostly modeled after {::Complex}.
+class VectorNumber
+  def numeric?: (?Integer) -> bool
 
-    def finite?: () -> bool
+  def nonnumeric?: (?Integer) -> bool
 
-    def infinite?: () -> Integer?
+  def finite?: () -> bool
 
-    def zero?: () -> bool
+  def infinite?: () -> Integer?
 
-    def nonzero?: () -> self?
+  def zero?: () -> bool
 
-    def positive?: () -> bool
+  def nonzero?: () -> self?
 
-    def negative?: () -> bool
+  def positive?: () -> bool
 
-    def real?: () -> false
+  def negative?: () -> bool
 
-    def integer?: () -> false
-  end
+  def real?: () -> false
 
-  # Methods and options for string representation.
-  module Stringifying
-    include Querying
+  def integer?: () -> false
+end
 
-    MULT_STRINGS: Hash[Symbol, String]
+# Methods and options for string representation.
+class VectorNumber
+  MULT_STRINGS: Hash[Symbol, String]
 
-    def to_s: (?mult: (Symbol | String)) -> String
+  def to_s: (?mult: (Symbol | String)) -> String
 
-    def inspect: () -> String
+  def inspect: () -> String
 
-    private
+  private
 
-    def value_to_s: (unit_type unit, coefficient_type coefficient, mult: (Symbol | String)) -> String
-  end
+  def value_to_s: (unit_type unit, coefficient_type coefficient, mult: (Symbol | String)) -> String
+end
 
+class VectorNumber
   # Refinements of Numeric classes to better work with VectorNumber and similar classes.
   module NumericRefinements
     module CommutativeShuttle