vector_number 0.2.4

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d8a4ba56677fa1eab6fc6dba7e8a7cc9d4afd769d9d0a4186ee51b2f400f2bab
+  data.tar.gz: 57f4d03d9495c2f6e98afb25008f659f63cf5cf0723664f1a3e7633568a8a179
+SHA512:
+  metadata.gz: 020ae7c79a25d4d18b6c2798d1c903e5f3a9699f8a2822ad7617ef3ada0ed4e2ef158a324548dfdc68de1a2bd70789487929d8d68def9b47133e077a4654d277
+  data.tar.gz: d34fb46be17a6cec0916257afcaccb842cdd24b7aa055377c1dbd343e6ffd90295df2a9725bf549709f6997276f88e1c1766f079c4848dc002b645180678e912

data/CHANGELOG.md

@@ -0,0 +1,69 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Next]
+## [v0.2.4] — 2025-02-26
+
+**Added**
+- Add hash-like methods `#[]` and `#unit?` (aliased as `#key?`).
+
+**Changed**
+- [Breaking] Change `positive?` and `negative?` to no longer return `nil`,
+   those cases will now return `false`.
+- Make `VectorNumber.new` accept options when initializing from a VectorNumber
+   instead of only copying. Options will be merged.
+- Remove `Initializing` module, move its methods to the actual class.
+- Updated development gem versions.
+
+**Fixed**
+- `#dup` and `#clone` now behave exactly like Numeric versions, preventing unfreezing.
+
+## [v0.2.3] — 2024-10-15
+
+**Fixed**
+- BigDecimal tests are now properly skipped when BigDecimal is not available, instead of always.
+
+## [v0.2.2] — 2024-10-07
+
+**Added**
+- Add `#abs` (aliased as `#magnitude`) and `#abs2`.
+- Add `#ceil`, `#floor` and `#round`.
+
+**Changed**
+- Add ruby 3.1.0, covering the earliest supported version, and ruby-next (3.4) to CI.
+- Add JRuby and TruffleRuby to CI, without full support.
+- Make tests runnable even without available `bigdecimal` gem.
+
+**Fixed**
+- `Kernel#BigDecimal` refinement now correctly works without `ndigits` argument.
+
+## [v0.2.1] — 2024-08-24
+
+**Added**
+- Add back `#*` and `#/` for working with real numbers.
+- Add `#fdiv`, `#truncate`, `#nonnumeric?` and `#integer?`.
+
+**Changed**
+- Allow to use fully real VectorNumbers as real numbers.
+
+**Fixed**
+- Fix reversed result in refined `#<=>`.
+
+**Removed**
+- Remove `#to_str`, as VectorNumber is not a String-like object.
+- Due to the above, `Kernel.BigDecimal` no longer works without refinements.
+
+## [v0.2.0] — 2024-08-19
+
+**Added**
+- VectorNumbers can be created from any object or collection.
+- Addition and subtraction are supported.
+- VectorNumbers are mostly interoperable with core numbers.
+
+## [v0.1.0] — 2024-05-09
+
+- Initial work.

data/README.md

@@ -0,0 +1,74 @@
+# VectorNumber
+
+![CRuby validation](https://github.com/trinistr/vector_number/actions/workflows/cruby.yaml/badge.svg)
+<!--
+![TruffleRuby validation](https://github.com/trinistr/vector_number/actions/workflows/truffleruby.yaml/badge.svg)
+-->
+
+A library to add together anything: be it a number, string or random Object, it can be added together in an infinite-dimensional vector space, with math operations available on results.
+
+This is similar in a sense to hypercomplex numbers, such as quaternions, but with a focus on arbitrary dimensions.
+
+Similar projects:
+- [vector_space](https://github.com/tomstuart/vector_space) aims to provide typed vector spaces with limited dimensions and nice formatting.
+- [named_vector](https://rubygems.org/gems/named_vector) provides simple vectors with named dimensions.
+- Various quaternion libraries.
+
+## Installation
+
+Add gem to your Gemfile:
+```ruby
+gem "vector_number", git: "https://github.com/trinistr/vector_number.git"
+```
+
+Installation through `gem` is not currently supported.
+
+## Usage
+
+Usage is pretty simple and intuitive:
+```ruby
+require "vector_number"
+VectorNumber["string"] + "str" # => (1⋅'string' + 1⋅'str')
+VectorNumber[5] + VectorNumber["string"] - 0.5 # => (4.5 + 1⋅'string')
+VectorNumber["string", "string", "string", "str"] # => (3⋅'string' + 1⋅'str')
+VectorNumber[:s] * 2 + VectorNumber["string"] * 0.3 # => (2⋅s + 0.3⋅'string')
+VectorNumber[:s] / 3 # => (1/3⋅s)
+1/3r * VectorNumber[[]] # => (1/3⋅[])
+```
+
+VectorNumbers are mostly useful for summing up heterogeneous objects:
+```ruby
+sum = VectorNumber[]
+[4, "death", "death", 13, nil].each { sum = sum + _1 }
+sum # => (17 + 2⋅'death' + 1⋅)
+sum.to_a # => [[(0+0i), 17], ["death", 2], [nil, 1]]
+sum.to_h # => {(0+0i)=>17, "death"=>2, nil=>1}
+```
+
+Alternatively, the same result can be equivalently (and more efficiently) achieved by
+passing all values to a constructor:
+```ruby
+VectorNumber[4, "death", "death", 13, nil]
+VectorNumber.new([4, "death", "death", 13, nil])
+```
+
+## Ruby engine support status
+
+VectorNumber is developed on MRI (CRuby) but should work on other engines too.
+- JRuby: should work, but currently CI does not pass.
+- TruffleRuby: works as expected, but there are differences in core Ruby code, so some tests fail.
+- Other engines: untested, but should work.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests, `rake rubocop` to check code, `rake steep` to check typing or just `rake` to do everything. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, change Next version in `CHANGELOG.md`, commit changes and tag the commit. Alternatively, an appropriate `rake bump:` command can be used.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at [https://github.com/trinistr/vector_number]().
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/vector_number/comparing.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+class VectorNumber
+  # Methods for comparing with other numbers.
+  module Comparing
+    include ::Comparable
+
+    # Compare to +other+ for equality.
+    #
+    # Values are considered equal if
+    # - +other+ is a VectorNumber and it is +eql?+ to this one, or
+    # - +other+ is a Numeric equal in value to this number.
+    #
+    # @param other [Object]
+    # @return [Boolean]
+    def ==(other)
+      return true if eql?(other)
+
+      case other
+      when Numeric
+        numeric?(2) && other.real == real && other.imaginary == imaginary
+      else
+        # Can't compare a number-like value to a non-number.
+        false
+      end
+    end
+
+    # @param other [Object]
+    # @return [Boolean]
+    def eql?(other)
+      return true if equal?(other)
+
+      if other.is_a?(VectorNumber)
+        other.size == size && other.each_pair.all? { |u, c| @data[u] == c }
+      else
+        false
+      end
+    end
+
+    # @param other [Object]
+    # @return [Integer, nil]
+    def <=>(other)
+      return nil unless numeric?(1)
+
+      case other
+      when VectorNumber
+        other.numeric?(1) ? real <=> other.real : nil
+      when Numeric
+        other.imaginary.zero? ? real <=> other.real : nil
+      else
+        nil
+      end
+    end
+  end
+end

data/lib/vector_number/converting.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+class VectorNumber
+  # Methods for converting to different number classes.
+  module Converting
+    # Return real part of the number.
+    # @return [Integer, Float, Rational, BigDecimal]
+    def real
+      @data[R]
+    end
+
+    # Return imaginary part of the number.
+    # @return [Integer, Float, Rational, BigDecimal]
+    def imaginary
+      @data[I]
+    end
+
+    alias imag imaginary
+
+    # Return value as an Integer, truncating it, if only real part is non-zero.
+    # @return [Integer]
+    # @raise [RangeError] if any non-real part is non-zero
+    def to_i
+      numeric?(1) ? real.to_i : raise_convert_error(Integer)
+    end
+
+    alias to_int to_i
+
+    # Return value as a Float if only real part is non-zero.
+    # @return [Float]
+    # @raise [RangeError] if any non-real part is non-zero
+    def to_f
+      numeric?(1) ? real.to_f : raise_convert_error(Float)
+    end
+
+    # Return value as a Rational if only real part is non-zero.
+    # @return [Rational]
+    # @raise [RangeError] if any non-real part is non-zero
+    def to_r
+      numeric?(1) ? real.to_r : raise_convert_error(Rational)
+    end
+
+    # Return value as a BigDecimal if only real part is non-zero.
+    # @param ndigits [Integer] precision
+    # @return [BigDecimal]
+    # @raise [RangeError] if any non-real part is non-zero
+    # @raise [NameError] if BigDecimal is not defined
+    def to_d(ndigits = nil)
+      if numeric?(1)
+        return BigDecimal(real, ndigits) if ndigits
+        return BigDecimal(real, Float::DIG) if real.is_a?(Float)
+
+        BigDecimal(real)
+      else
+        raise_convert_error(BigDecimal)
+      end
+    end
+
+    # Return value as a Complex if only real and/or imaginary parts are non-zero.
+    # @return [Complex]
+    # @raise [RangeError] if any non-real, non-imaginary part is non-zero
+    def to_c
+      numeric?(2) ? Complex(real, imaginary) : raise_convert_error(Complex)
+    end
+
+    private
+
+    def raise_convert_error(klass)
+      raise RangeError, "can't convert #{self} into #{klass}", caller
+    end
+  end
+end

data/lib/vector_number/enumerating.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+class VectorNumber
+  # Methods for enumerating values of the number.
+  module Enumerating
+    include ::Enumerable
+
+    # Iterate through every pair of unit and coefficient.
+    # Returns {::Enumerator} if no block is given.
+    # @overload each
+    #   @yieldparam unit [Object]
+    #   @yieldparam coefficient [Integer, Float, Rational, BigDecimal]
+    #   @yieldreturn [void]
+    #   @return [VectorNumber] self
+    # @overload each
+    #   @return [Enumerator]
+    def each(&)
+      return to_enum { size } unless block_given?
+
+      @data.each(&)
+      self
+    end
+
+    alias each_pair each
+
+    # @return [Array<Object>]
+    def units
+      @data.keys
+    end
+
+    alias keys units
+
+    # @return [Array<Integer, Float, Rational, BigDecimal>]
+    def coefficients
+      @data.values
+    end
+
+    alias values coefficients
+
+    # @return [Hash{Object => Integer, Float, Rational, BigDecimal}]
+    def to_h(&)
+      if block_given?
+        @data.to_h(&)
+      else
+        @data.dup
+      end
+    end
+
+    # Get the coefficient for the unit.
+    #
+    # If the +unit?(unit)+ is false, 0 is returned.
+    # Note that units for real and imaginary parts are
+    # VectorNumber::R and VectorNumber::I respectively.
+    #
+    # @param unit [Object]
+    # @return [Integer, Float, Rational, BigDecimal]
+    def [](unit)
+      @data[unit] || 0
+    end
+
+    # Check if a unit has a non-zero coefficient.
+    #
+    # @param unit [Object]
+    # @return [Boolean]
+    def unit?(unit)
+      @data.key?(unit)
+    end
+
+    alias key? unit?
+  end
+end

data/lib/vector_number/math_converting.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+class VectorNumber
+  # Various mathematical operations that are also conversions.
+  module MathConverting
+    # Return the absolute value of a vector, i.e. its length.
+    # @return [Float]
+    def abs
+      Math.sqrt(coefficients.reduce(0.0) { |result, coefficient| result + coefficient.abs2 })
+    end
+
+    alias magnitude abs
+
+    # Return the square of absolute value.
+    # @return [Float]
+    def abs2 # rubocop:disable Naming/VariableNumber
+      abs**2
+    end
+
+    # Return a new vector with every coefficient truncated using their +#truncate+.
+    # @param digits [Integer]
+    # @return [VectorNumber]
+    def truncate(digits = 0)
+      new { _1.truncate(digits) }
+    end
+
+    # Return a new vector with every coefficient rounded using their +#ceil+.
+    # @param digits [Integer]
+    # @return [VectorNumber]
+    def ceil(digits = 0)
+      new { _1.ceil(digits) }
+    end
+
+    # Return a new vector with every coefficient rounded using their +#floor+.
+    # @param digits [Integer]
+    # @return [VectorNumber]
+    def floor(digits = 0)
+      new { _1.floor(digits) }
+    end
+
+    # Return a new vector with every coefficient rounded using their +#round+.
+    # @param digits [Integer]
+    # @param half [Symbol, nil] one of +:up+, +:down+ or +:even+, see +Float#round+ for meaning
+    # @return [VectorNumber]
+    def round(digits = 0, half: :up)
+      if defined?(BigDecimal)
+        bd_mode =
+          case half
+          when :down then :half_down
+          when :even then :half_even
+          else :half_up
+          end
+        new { _1.is_a?(BigDecimal) ? _1.round(digits, bd_mode) : _1.round(digits, half:) }
+      else
+        new { _1.round(digits, half:) }
+      end
+    end
+  end
+end

data/lib/vector_number/mathing.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+class VectorNumber
+  # Methods for performing actual math.
+  module Mathing
+    # The coerce method provides support for Ruby type coercion.
+    # Unlike most numeric types, VectorNumber can coerce *anything*.
+    # @param other [Object]
+    # @return [Array(VectorNumber, VectorNumber)]
+    def coerce(other)
+      case other
+      when VectorNumber
+        [other, self]
+      else
+        [new([other]), self]
+      end
+    end
+
+    # Return self.
+    # @return [VectorNumber]
+    def +@
+      self
+    end
+
+    # Return new vector with negated coefficients.
+    # This preserves order of units.
+    # @return [VectorNumber]
+    def -@
+      new(&:-@)
+    end
+
+    # Return new vector as a sum of this and other value.
+    # This is analogous to {VectorNumber.[]}.
+    # @param other [Object]
+    # @return [VectorNumber]
+    def +(other)
+      new([self, other])
+    end
+
+    # Return new vector as a sum of this and negative of the other value.
+    # This is analogous to {VectorNumber.[]}, but allows to negate anything.
+    # @param other [Object]
+    # @return [VectorNumber]
+    def -(other)
+      self + new([other], &:-@)
+    end
+
+    # Multiply all coefficients by a real number, returning new vector.
+    # This effectively multiplies magnitude by the specified factor.
+    # @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
+    def *(other)
+      if real_number?(other)
+        other = other.real
+        # @type var other: Float
+        new { _1 * other }
+      elsif real_number?(self) && other.is_a?(self.class)
+        # @type var other: untyped
+        other * self
+      else
+        raise RangeError, "can't multiply #{self} and #{other}"
+      end
+    end
+
+    # Divide all coefficients by a real number, returning new vector.
+    # This effectively multiplies magnitude by reciprocal of the specified factor.
+    # @param other [Integer, Float, Rational, BigDecimal, VectorNumber]
+    # @return [VectorNumber]
+    # @raise [RangeError] if +other+ is not a number or is not a real number
+    def /(other)
+      raise RangeError, "can't divide #{self} by #{other}" unless real_number?(other)
+
+      other = other.real
+      # Prevent integer division, but without loss of accuracy.
+      other = Rational(other) if other.is_a?(Integer)
+      # @type var other: Float
+      new { _1 / other }
+    end
+
+    # Divide all coefficients by a real number using +fdiv+, returning new vector
+    # with Float coefficients.
+    # @param other [Integer, Float, Rational, BigDecimal, VectorNumber]
+    # @return [VectorNumber]
+    # @raise [RangeError] if +other+ is not a number or is not a real number
+    def fdiv(other)
+      raise RangeError, "can't divide #{self} by #{other}" unless real_number?(other)
+
+      other = other.real
+      new { _1.fdiv(other) }
+    end
+  end
+end

data/lib/vector_number/numeric_refinements.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+class VectorNumber
+  # Refinements of Numeric classes to better work with VectorNumber and similar classes.
+  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+.
+    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
+      def <=>(other)
+        comparison = super
+        return comparison if comparison || !other.respond_to?(:<=>)
+
+        comparison = other <=> self
+        -comparison if comparison
+      end
+    end
+
+    if (Complex(1, 0) <=> VectorNumber[1]).nil?
+      refine(Complex) { import_methods CommutativeShuttle }
+    end
+
+    # Refinement module to change Kernel#BigDecimal so it works with +#to_d+.
+    # @note `BigDecimal` needs to be defined for this refinement to activate.
+    module BigDecimalToD
+      # BigDecimal() that first tries to use #to_d.
+      # @param value [Object]
+      # @param exception [Boolean]
+      # @overload BigDecimal(value, exception: true)
+      # @overload BigDecimal(value, ndigits, exception: true)
+      #   @param ndigits [Integer]
+      # @return [BigDecimal, nil]
+      # @raise [TypeError]
+      def BigDecimal(value, ndigits = nil, exception: true) # rubocop:disable Naming/MethodName
+        if value.respond_to?(:to_d)
+          ndigits.nil? ? value.to_d : value.to_d(ndigits)
+        else
+          ndigits.nil? ? super(value, exception:) : super
+        end
+      end
+    end
+
+    refine(Kernel) { import_methods BigDecimalToD } if defined?(BigDecimal)
+  end
+end

data/lib/vector_number/querying.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+class VectorNumber
+  # Methods for querying state of the number.
+  # Mostly modeled after {::Complex}.
+  module Querying
+    # Whether this VectorNumber can be considered strictly numeric, e.g. real or complex.
+    # @param dimensions [Integer] number of dimensions to consider "numeric"
+    #   - 0 — zero
+    #   - 1 — real number
+    #   - 2 — complex number, etc.
+    # @return [Boolean]
+    # @raise [ArgumentError] if +dimensions+ is negative
+    def numeric?(dimensions = 2)
+      raise ArgumentError, "`dimensions` must be non-negative" unless dimensions >= 0
+
+      size <= dimensions && (1..dimensions).count { @data[UNIT[_1]].nonzero? } == size
+    end
+
+    # Whether this VectorNumber contains any non-numeric parts.
+    # @param (see #numeric?)
+    # @return (see #numeric?)
+    # @raise (see #numeric?)
+    def nonnumeric?(dimensions = 2)
+      raise ArgumentError, "`dimensions` must be non-negative" unless dimensions >= 0
+
+      !numeric?(dimensions)
+    end
+
+    # Returns +true+ if all coefficients are finite, +false+ otherwise.
+    # @return [Boolean]
+    def finite?
+      all? { |_u, v| v.finite? }
+    end
+
+    # Returns +1+ if any coefficients are infinite, +nil+ otherwise.
+    # @return [1, nil]
+    def infinite?
+      finite? ? nil : 1 # rubocop:disable Style/ReturnNilInPredicateMethodDefinition
+    end
+
+    # Returns +true+ if there are no non-zero coefficients, and +false+ otherwise.
+    # @return [Boolean]
+    def zero?
+      size.zero?
+    end
+
+    # Returns +self+ if there are any non-zero coefficients, +nil+ otherwise.
+    # @return [VectorNumber, nil]
+    def nonzero?
+      zero? ? nil : self # rubocop:disable Style/ReturnNilInPredicateMethodDefinition
+    end
+
+    # Returns +true+ if number is non-zero and all non-zero coefficients are positive,
+    # and +false+ otherwise.
+    # @return [Boolean]
+    def positive?
+      !zero? && all? { |_u, c| c.positive? }
+    end
+
+    # Returns +true+ if number is non-zero and all non-zero coefficients are negative,
+    # and +false+ otherwise.
+    # @return [Boolean]
+    def negative?
+      !zero? && all? { |_u, c| c.negative? }
+    end
+
+    # Always returns +false+.
+    # @see #numeric?
+    # @return [false]
+    def real?
+      false
+    end
+
+    # Always returns +false+.
+    # @return [false]
+    def integer?
+      false
+    end
+  end
+end

data/lib/vector_number/stringifying.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+class VectorNumber
+  # Methods and options for string representation.
+  module Stringifying
+    # Predefined symbols for multiplication to display between unit and coefficient.
+    # @return [Hash{Symbol => String}]
+    MULT_STRINGS = {
+      asterisk: "*", # U+002A
+      cross: "×", # U+00D7
+      dot: "⋅", # U+22C5
+      invisible: "⁢", # U+2062, zero-width multiplication operator
+      space: " ",
+      none: ""
+    }.freeze
+
+    # @param mult [Symbol, String]
+    #   text to use between coefficient and unit,
+    #   can be one of the keys in {MULT_STRINGS} or an arbitrary string
+    # @return [String]
+    # @raise [ArgumentError] if +mult+ is not in {MULT_STRINGS}'s keys
+    def to_s(mult: options[:mult])
+      return "0" if zero?
+
+      result = +""
+      each_with_index do |(unit, coefficient), index|
+        if index.zero?
+          result << "-" if coefficient.negative?
+        else
+          result << (coefficient.positive? ? " + " : " - ")
+        end
+        result << value_to_s(unit, coefficient.abs, mult:)
+      end
+      result
+    end
+
+    # @return [String]
+    def inspect
+      "(#{self})"
+    end
+
+    private
+
+    # @param unit [Object]
+    # @param coefficient [Numeric]
+    # @param mult [Symbol, String]
+    # @return [String]
+    # @raise [ArgumentError] if +mult+ is not in {MULT_STRINGS}'s keys
+    def value_to_s(unit, coefficient, mult:)
+      if !mult.is_a?(String) && !MULT_STRINGS.key?(mult)
+        raise ArgumentError, "unknown key :#{mult}", caller
+      end
+
+      case unit
+      when R
+        coefficient.to_s
+      when I
+        "#{coefficient}i"
+      else
+        unit = "'#{unit}'" if unit.is_a?(String)
+        operator = mult.is_a?(String) ? mult : MULT_STRINGS[mult]
+        "#{coefficient}#{operator}#{unit}"
+      end
+    end
+  end
+end

data/lib/vector_number/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+class VectorNumber # rubocop:disable Style/StaticClass
+  # @return [String]
+  VERSION = "0.2.4"
+end

data/lib/vector_number.rb

@@ -0,0 +1,210 @@
+# frozen_string_literal: true
+
+require_relative "vector_number/version"
+require_relative "vector_number/mathing"
+require_relative "vector_number/math_converting"
+require_relative "vector_number/converting"
+require_relative "vector_number/enumerating"
+require_relative "vector_number/comparing"
+require_relative "vector_number/querying"
+require_relative "vector_number/stringifying"
+
+# A class to add together anything.
+class VectorNumber
+  include Mathing
+  include MathConverting
+  include Converting
+  include Enumerating
+  include Comparing
+  include Querying
+  include Stringifying
+
+  # @return [Array<Symbol>]
+  KNOWN_OPTIONS = %i[mult].freeze
+
+  # @return [Hash{Symbol => Object}]
+  DEFAULT_OPTIONS = { mult: :dot }.freeze
+
+  # Get a unit for +n+th numeric dimension, where 1 is real, 2 is imaginary.
+  UNIT = ->(n) { (n - 1).i }.freeze
+  # Constant for real unit.
+  R = UNIT[1]
+  # Constant for imaginary unit.
+  I = UNIT[2]
+
+  # Number of non-zero dimensions.
+  # @return [Integer]
+  attr_reader :size
+  # @return [Hash{Symbol => Object}]
+  attr_reader :options
+
+  # Create new VectorNumber from +values+.
+  #
+  # @example
+  #   VectorNumber[1, 2, 3] #=> (6)
+  #   VectorNumber[[1, 2, 3]] #=> (1⋅[1, 2, 3])
+  #   VectorNumber['b', VectorNumber::I, mult: :asterisk] #=> (1*'b' + 1i)
+  # @param values [Array<Object>] values to put in the number
+  # @param options [Hash{Symbol => Object}] options for the number
+  # @return [VectorNumber]
+  def self.[](*values, **options)
+    new(values, options)
+  end
+
+  # @param values [Array, Hash{Object => Integer, Float, Rational, BigDecimal}, VectorNumber]
+  #   values for this number, hashes are treated like plain vector numbers
+  # @param options [Hash{Symbol => Object}]
+  #   options for this number, if +values+ is a VectorNumber,
+  #   these will be merged with options from +values.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 = {}.freeze, &)
+    # TODO: propagate options properly.
+    #   > (VectorNumber[1, 'a', mult: :invisible] + 2).options
+    #   => {:mult=>:dot}
+    super()
+    initialize_from(values)
+    apply_transform(&)
+    finalize_contents
+    save_options(options, values:)
+    @options.freeze
+    @data.freeze
+    freeze
+  end
+
+  # Return self.
+  #
+  # @return [VectorNumber]
+  def dup
+    self
+  end
+
+  # Return self.
+  #
+  # Raises ArgumentError if +freeze+ is not +true+ or +nil+.
+  #
+  # @return [VectorNumber]
+  def clone(freeze: true)
+    case freeze
+    when true, nil
+      self
+    when false
+      raise ArgumentError, "can't unfreeze #{self.class}"
+    else
+      raise ArgumentError, "unexpected value for freeze: #{freeze.class}"
+    end
+  end
+
+  private
+
+  # 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
+  # @return [VectorNumber]
+  def new(from = self, &)
+    self.class.new(from, &)
+  end
+
+  # @param value [Object]
+  # @return [Boolean]
+  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]
+  # @return [void]
+  def initialize_from(values)
+    @data = Hash.new(0)
+
+    case values
+    when VectorNumber, Hash
+      add_vector_to_data(values)
+    when Array
+      values.each { |value| add_value_to_data(value) }
+    else
+      # Don't add anything.
+    end
+  end
+
+  # @param value [VectorNumber, Numeric, Object]
+  # @return [void]
+  def add_value_to_data(value)
+    case value
+    when Numeric
+      add_numeric_value_to_data(value)
+    when VectorNumber
+      add_vector_to_data(value)
+    else
+      @data[value] += 1
+    end
+  end
+
+  # @param value [Numeric]
+  # @return [void]
+  def add_numeric_value_to_data(value)
+    @data[R] += value.real
+    @data[I] += value.imaginary
+  end
+
+  # @param vector [VectorNumber, Hash{Object => Integer, Float, Rational, BigDecimal}]
+  # @return [void]
+  def add_vector_to_data(vector)
+    vector.each_pair do |unit, coefficient|
+      raise RangeError, "#{coefficient} is not a real number" unless real_number?(coefficient)
+
+      @data[unit] += coefficient.real
+    end
+  end
+
+  # @yieldparam coefficient [Integer, Float, Rational, BigDecimal]
+  # @yieldreturn [Integer, Float, Rational, BigDecimal]
+  # @return [void]
+  # @raise [RangeError]
+  def apply_transform
+    return unless block_given?
+
+    @data.transform_values! do |coefficient|
+      new_value = yield coefficient
+      next new_value.real if real_number?(new_value)
+
+      raise RangeError, "transform returned non-real value for #{coefficient}"
+    end
+  end
+
+  # @param options [Hash{Symbol => Object}, nil]
+  # @param values [Object] initializing object
+  # @return [void]
+  def save_options(options, values:)
+    @options =
+      case [options, values]
+      in [{} | nil, VectorNumber]
+        values.options
+      in Hash, VectorNumber
+        values.options.merge(options).slice(*known_options)
+      in Hash, _ unless options.empty?
+        default_options.merge(options).slice(*known_options)
+      else
+        default_options
+      end
+  end
+
+  # Compact coefficients, calculate size and freeze data.
+  # @return [void]
+  def finalize_contents
+    @data.delete_if { |_u, c| c.zero? }
+    @data.freeze
+    @size = @data.size
+  end
+
+  def default_options
+    DEFAULT_OPTIONS
+  end
+
+  def known_options
+    KNOWN_OPTIONS
+  end
+end

data/sig/definitions.rbs

@@ -0,0 +1,15 @@
+type vector_type = VectorNumber
+type real_number = Integer | Float | Rational | BigDecimal
+
+type in_value_type = untyped
+type unit_type = untyped
+type coefficient_type = real_number
+
+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 options_type = Hash[Symbol, untyped]

data/sig/vector_number.rbs

@@ -0,0 +1,230 @@
+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
+
+  VERSION: String
+
+  KNOWN_OPTIONS: list[Symbol]
+  DEFAULT_OPTIONS: options_type
+
+  UNIT: ^(Integer) -> Complex
+  R: Complex
+  I: Complex
+
+  def self.[]: (*unit_type values, **options_type options) -> vector_type
+
+  def initialize:
+    (?(units_list_type | plain_vector_type | vector_type)? values, ?options_type options)
+    ?{ (coefficient_type coefficient) -> coefficient_type }
+    -> void
+
+  def dup: () -> self
+
+  def clone: (?freeze: bool?) -> self
+
+  private
+
+  @size: Integer
+  @options: options_type
+  @data: plain_vector_type
+
+  def initialize_from: ((units_list_type | plain_vector_type | vector_type)? values) -> void
+
+  def add_value_to_data: ((vector_type | 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 apply_transform: () ?{ (coefficient_type value) -> coefficient_type } -> void
+
+  def save_options: (options_type? options, values: in_value_type) -> void
+  def default_options: () -> options_type
+  def known_options: () -> list[Symbol]
+
+  def finalize_contents: () -> void
+
+  # Methods for performing actual math.
+  module Mathing
+    include _BaseMethods
+
+    def coerce: (in_value_type) -> [vector_type, self]
+
+    def +@: () -> self
+
+    def -@: () -> vector_type
+
+    def +: (in_value_type) -> vector_type
+
+    def -: (in_value_type) -> vector_type
+
+    def *: (real_number | vector_type) -> vector_type
+
+    def /: (real_number | vector_type) -> vector_type
+
+    def fdiv: (real_number | vector_type) -> vector_type
+  end
+
+  # Various mathematical operations that are also conversions.
+  module MathConverting
+    include _BaseMethods
+    include Enumerating
+
+    def abs: () -> Float
+
+    def abs2: () -> Float
+
+    def truncate: (Integer) -> vector_type
+
+    def ceil: (Integer) -> vector_type
+
+    def floor: (Integer) -> vector_type
+  end
+
+  # Methods for converting to different number classes.
+  module Converting
+    include _BaseMethods
+    include Querying
+
+    def real: () -> real_number
+
+    def imaginary: () -> real_number
+    alias imag imaginary
+
+    def to_i: () -> Integer
+            | () -> void
+    alias to_int to_i
+
+    def to_f: () -> Float
+            | () -> void
+
+    def to_r: () -> Rational
+            | () -> void
+
+    def to_d: (?Integer?) -> BigDecimal
+            | (?Integer?) -> void
+
+    def to_c: () -> Complex
+            | () -> void
+
+    def truncate: (?Integer digits) -> vector_type
+
+    private
+
+    def raise_convert_error: (Class) -> void
+  end
+
+  # Methods for enumerating values of the number.
+  module Enumerating
+    include _BaseMethods
+    include _Each[each_value_type]
+    include Enumerable[each_value_type]
+
+    def each: () { (unit_type unit, coefficient_type coefficient) -> void } -> self
+            | () -> Enumerator[each_value_type, Integer]
+            | ...
+    alias each_pair each
+
+    def units: () -> units_list_type
+    alias keys units
+
+    def coefficients: () -> coefficients_list_type
+    alias values coefficients
+
+    def to_h: () -> plain_vector_type
+            | () { (unit_type, coefficient_type) -> each_value_type } -> plain_vector_type
+
+    def []: (unit_type unit) -> coefficient_type
+
+    def unit?: (unit_type unit) -> bool
+    alias key? unit?
+  end
+
+  # Methods for comparing with other numbers.
+  module Comparing
+    include _BaseMethods
+    include Enumerating
+    include Converting
+    include Querying
+
+    def ==: (in_value_type other) -> bool
+
+    def eql?: (in_value_type other) -> bool
+
+    def <=>: (in_value_type other) -> Integer?
+  end
+
+  # Methods for querying state of the number.
+  # Mostly modeled after {::Complex}.
+  module Querying
+    include Enumerating
+
+    def numeric?: (?Integer) -> bool
+
+    def nonnumeric?: (?Integer) -> bool
+
+    def finite?: () -> bool
+
+    def infinite?: () -> Integer?
+
+    def zero?: () -> bool
+
+    def nonzero?: () -> self?
+
+    def positive?: () -> bool
+
+    def negative?: () -> bool
+
+    def real?: () -> false
+
+    def integer?: () -> false
+  end
+
+  # Methods and options for string representation.
+  module Stringifying
+    include Querying
+
+    MULT_STRINGS: Hash[Symbol, String]
+
+    def to_s: (?mult: (Symbol | String)) -> String
+
+    def inspect: () -> String
+
+    private
+
+    def value_to_s: (unit_type unit, coefficient_type coefficient, mult: (Symbol | String)) -> String
+  end
+
+  # Refinements of Numeric classes to better work with VectorNumber and similar classes.
+  module NumericRefinements
+    module CommutativeShuttle
+      def <=>: (in_value_type other) -> Integer?
+    end
+
+    module BigDecimalToD
+      def BigDecimal: (untyped value, exception: bool) -> BigDecimal?
+                    | (untyped value, Integer ndigits, exception: bool) -> BigDecimal?
+    end
+  end
+end

metadata

@@ -0,0 +1,64 @@
+--- !ruby/object:Gem::Specification
+name: vector_number
+version: !ruby/object:Gem::Version
+  version: 0.2.4
+platform: ruby
+authors:
+- Alexandr Bulancov
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2025-02-25 00:00:00.000000000 Z
+dependencies: []
+description:
+email:
+executables: []
+extensions: []
+extra_rdoc_files:
+- README.md
+- CHANGELOG.md
+files:
+- CHANGELOG.md
+- README.md
+- lib/vector_number.rb
+- lib/vector_number/comparing.rb
+- lib/vector_number/converting.rb
+- lib/vector_number/enumerating.rb
+- lib/vector_number/math_converting.rb
+- lib/vector_number/mathing.rb
+- lib/vector_number/numeric_refinements.rb
+- lib/vector_number/querying.rb
+- lib/vector_number/stringifying.rb
+- lib/vector_number/version.rb
+- sig/definitions.rbs
+- sig/vector_number.rbs
+homepage: https://github.com/trinistr/vector_number
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/trinistr/vector_number
+  source_code_uri: https://github.com/trinistr/vector_number
+  changelog_uri: https://github.com/trinistr/vector_number/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options:
+- "--main"
+- README.md
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.21
+signing_key:
+specification_version: 4
+summary: A library to add together anything.
+test_files: []