vector_number 0.3.0 → 0.3.1

data/lib/vector_number.rb

@@ -1,13 +1,13 @@
 # frozen_string_literal: true
 
-require_relative "vector_number/version"
-require_relative "vector_number/mathing"
-require_relative "vector_number/math_converting"
+require_relative "vector_number/comparing"
 require_relative "vector_number/converting"
 require_relative "vector_number/enumerating"
-require_relative "vector_number/comparing"
+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.
 class VectorNumber
@@ -19,38 +19,84 @@ class VectorNumber
   include Querying
   include Stringifying
 
+  # 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
 
+  # Default values for options.
+  #
   # @return [Hash{Symbol => Object}]
+  #
+  # @since 0.2.0
   DEFAULT_OPTIONS = { mult: :dot }.freeze
 
   # Get a unit for +n+th numeric dimension, where 1 is real, 2 is imaginary.
+  #
+  # @since 0.2.0
   UNIT = ->(n) { (n - 1).i }.freeze
   # Constant for real unit.
+  #
+  # @since 0.2.0
   R = UNIT[1]
   # Constant for imaginary unit.
+  #
+  # @since 0.1.0
   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+.
+  # Create new VectorNumber from a list of values, possibly specifying options.
   #
   # @example
-  #   VectorNumber[1, 2, 3] #=> (6)
-  #   VectorNumber[[1, 2, 3]] #=> (1⋅[1, 2, 3])
-  #   VectorNumber['b', VectorNumber::I, mult: :asterisk] #=> (1*'b' + 1i)
+  #   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]
+  #
+  # @since 0.1.0
   def self.[](*values, **options)
     new(values, options)
   end
 
+  # Number of non-zero dimensions.
+  #
+  # @return [Integer]
+  #
+  # @since 0.1.0
+  attr_reader :size
+
+  # Options used for this vector.
+  #
+  # @see KNOWN_OPTIONS
+  #
+  # @return [Hash{Symbol => Object}]
+  #
+  # @since 0.1.0
+  attr_reader :options
+
+  # Create new VectorNumber from +values+, possibly specifying +options+,
+  # possibly modifying coefficients with a block.
+  #
+  # @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 # => (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], &:digits) # RangeError
+  #
   # @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}]
@@ -62,7 +108,7 @@ class VectorNumber
   # @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, &)
-    # @type var options: Hash[Symbol, Symbol]
+    # @type var options: Hash[Symbol, Object]
     initialize_from(values)
     apply_transform(&)
     finalize_contents
@@ -75,13 +121,18 @@ class VectorNumber
   # Return self.
   #
   # @return [VectorNumber]
-  alias dup itself
+  #
+  # @since 0.2.0
+  def +@ = self
+  # @since 0.2.4
+  alias dup +@
 
   # Return self.
   #
-  # Raises ArgumentError if +freeze+ is not +true+ or +nil+.
-  #
   # @return [VectorNumber]
+  # @raise [ArgumentError] if +freeze+ is not +true+ or +nil+.
+  #
+  # @since 0.2.4
   def clone(freeze: true)
     case freeze
     when true, nil
@@ -96,6 +147,7 @@ class VectorNumber
   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
@@ -104,14 +156,22 @@ class VectorNumber
     self.class.new(from, options, &)
   end
 
+  # Check if +other+ is a real number.
+  #
+  # Currently this is either a +real?+ Numeric or +numeric?(1)+ 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]
   # @return [void]
+  #
+  # @since 0.1.0
   def initialize_from(values)
     @data = Hash.new(0)
 
@@ -127,6 +187,8 @@ class VectorNumber
 
   # @param value [VectorNumber, Numeric, Object]
   # @return [void]
+  #
+  # @since 0.1.0
   def add_value_to_data(value)
     case value
     when Numeric
@@ -140,6 +202,8 @@ class VectorNumber
 
   # @param value [Numeric]
   # @return [void]
+  #
+  # @since 0.1.0
   def add_numeric_value_to_data(value)
     @data[R] += value.real
     @data[I] += value.imaginary
@@ -147,6 +211,8 @@ class VectorNumber
 
   # @param vector [VectorNumber, Hash{Object => Integer, Float, Rational, BigDecimal}]
   # @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)
@@ -159,6 +225,8 @@ class VectorNumber
   # @yieldreturn [Integer, Float, Rational, BigDecimal]
   # @return [void]
   # @raise [RangeError]
+  #
+  # @since 0.1.0
   def apply_transform
     return unless block_given?
 
@@ -173,6 +241,8 @@ class VectorNumber
   # @param options [Hash{Symbol => Object}, nil]
   # @param values [Object] initializing object
   # @return [void]
+  #
+  # @since 0.1.0
   def save_options(options, values:)
     @options =
       case [options, values]
@@ -191,6 +261,11 @@ class VectorNumber
       end
   end
 
+  # @param base_options [Hash{Symbol => Object}]
+  # @param added_options [Hash{Symbol => Object}]
+  # @return [Hash{Symbol => Object}]
+  #
+  # @since 0.3.0
   def merge_options(base_options, added_options)
     # Optimization for the common case of passing options through #new.
     return base_options if added_options.equal?(base_options)
@@ -200,16 +275,20 @@ 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
     @size = @data.size
   end
 
+  # @since 0.2.0
   def default_options
     DEFAULT_OPTIONS
   end
 
+  # @since 0.2.0
   def known_options
     KNOWN_OPTIONS
   end

data/sig/vector_number.rbs

@@ -55,7 +55,8 @@ class VectorNumber
     ?{ (coefficient_type coefficient) -> coefficient_type }
     -> void
 
-  def dup: () -> self
+  def +@: () -> self
+  alias dup +@
 
   def clone: (?freeze: bool?) -> self
 
@@ -76,6 +77,7 @@ class VectorNumber
   def apply_transform: () ?{ (coefficient_type value) -> coefficient_type } -> void
 
   def save_options: (options_type? options, values: in_value_type) -> void
+  def merge_options: (options_type base_options, options_type added_options) -> options_type
   def default_options: () -> options_type
   def known_options: () -> list[Symbol]
 
@@ -87,8 +89,6 @@ class VectorNumber
 
     def coerce: (in_value_type) -> [vector_type, self]
 
-    def +@: () -> self
-
     def -@: () -> vector_type
     alias neg -@
 

metadata

@@ -1,21 +1,23 @@
 --- !ruby/object:Gem::Specification
 name: vector_number
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.3.1
 platform: ruby
 authors:
 - Alexandr Bulancov
 bindir: exe
 cert_chain: []
-date: 2025-05-12 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
 executables: []
 extensions: []
 extra_rdoc_files:
-- README.md
 - CHANGELOG.md
+- LICENSE.txt
+- README.md
 files:
 - CHANGELOG.md
+- LICENSE.txt
 - README.md
 - lib/vector_number.rb
 - lib/vector_number/comparing.rb
@@ -33,12 +35,16 @@ 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
+  bug_tracker_uri: https://github.com/trinistr/vector_number/issues
+  documentation_uri: https://rubydoc.info/gems/vector_number/0.3.1
+  source_code_uri: https://github.com/trinistr/vector_number/tree/v0.3.1
+  changelog_uri: https://github.com/trinistr/vector_number/blob/v0.3.1/CHANGELOG.md
   rubygems_mfa_required: 'true'
 rdoc_options:
 - "--main"
 - README.md
+- "--files"
+- CHANGELOG.md,LICENSE.txt
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
@@ -52,7 +58,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.5
+rubygems_version: 3.6.8
 specification_version: 4
 summary: A library to add together anything.
 test_files: []