vector_number 0.2.6 → 0.3.1

data/lib/vector_number/querying.rb

@@ -5,12 +5,21 @@ class VectorNumber
   # Mostly modeled after {::Complex}.
   module Querying
     # Whether this VectorNumber can be considered strictly numeric, e.g. real or complex.
+    #
+    # @example
+    #   VectorNumber[2].numeric? # => true
+    #   VectorNumber[2, 3i].numeric? # => true
+    #   VectorNumber[2, "a"].numeric? # => false
+    #   VectorNumber[2, 3i].numeric?(1) # => false
+    #
     # @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
+    #
+    # @since 0.2.0
     def numeric?(dimensions = 2)
       raise ArgumentError, "`dimensions` must be non-negative" unless dimensions >= 0
 
@@ -18,64 +27,124 @@ class VectorNumber
     end
 
     # Whether this VectorNumber contains any non-numeric parts.
+    #
+    # @example
+    #   VectorNumber[2].nonnumeric? # => false
+    #   VectorNumber[2, 3i].nonnumeric? # => false
+    #   VectorNumber[2, "a"].nonnumeric? # => true
+    #   VectorNumber[2, 3i].nonnumeric?(1) # => true
+    #
     # @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
+    #
+    # @since 0.2.1
+    def nonnumeric?(dimensions = 2) = !numeric?(dimensions)
 
     # Returns +true+ if all coefficients are finite, +false+ otherwise.
+    #
+    # @example
+    #   VectorNumber[2].finite? # => true
+    #   VectorNumber[Float::NAN].finite? # => false
+    #   VectorNumber["a"].mult(Float::INFINITY).finite? # => false
+    #
     # @return [Boolean]
+    #
+    # @since 0.1.0
     def finite?
       all? { |_u, v| v.finite? }
     end
 
     # Returns +1+ if any coefficients are infinite, +nil+ otherwise.
+    #
+    # This behavior is the same as +Complex+'s.
+    #
+    # @example
+    #   VectorNumber[2].infinite? # => nil
+    #   VectorNumber[Float::NAN].infinite? # => 1
+    #   VectorNumber["a"].mult(-Float::INFINITY).infinite? # => 1
+    #
     # @return [1, nil]
+    #
+    # @since 0.1.0
     def infinite?
       finite? ? nil : 1 # rubocop:disable Style/ReturnNilInPredicateMethodDefinition
     end
 
     # Returns +true+ if there are no non-zero coefficients, and +false+ otherwise.
+    #
+    # @example
+    #   VectorNumber["c"].zero? # => false
+    #   VectorNumber[].zero? # => true
+    #
     # @return [Boolean]
-    def zero?
-      size.zero?
-    end
+    #
+    # @since 0.1.0
+    def zero? = size.zero?
 
     # Returns +self+ if there are any non-zero coefficients, +nil+ otherwise.
+    #
+    # This behavior is the same as +Numeric+'s.
+    #
+    # @example
+    #   VectorNumber["ab", "cd"].nonzero? # => (1⋅'ab' + 1⋅'cd')
+    #   VectorNumber[].nonzero? # => nil
+    #
     # @return [VectorNumber, nil]
+    #
+    # @since 0.1.0
     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.
+    #
+    # @example
+    #   VectorNumber["a"].positive? # => true
+    #   VectorNumber[2].neg.positive? # => false
+    #   (VectorNumber["1"] - VectorNumber[1]).positive? # => false
+    #   VectorNumber[0].positive? # => false
+    #
     # @return [Boolean]
+    #
+    # @since 0.1.0
     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.
+    #
+    # @example
+    #   VectorNumber["a"].neg.negative? # => true
+    #   VectorNumber[-2].neg.negative? # => false
+    #   (VectorNumber["1"] - VectorNumber[1]).negative? # => false
+    #   VectorNumber[0].negative? # => false
+    #
     # @return [Boolean]
+    #
+    # @since 0.1.0
     def negative?
       !zero? && all? { |_u, c| c.negative? }
     end
 
-    # Always returns +false+, as vectors are never real numbers.
+    # Always returns +false+, as vectors are not real numbers.
+    #
+    # This behavior is the same as +Complex+'s.
+    #
     # @see #numeric?
+    #
     # @return [false]
-    def real?
-      false
-    end
+    #
+    # @since 0.1.0
+    def real? = false
 
     # Always returns +false+, as vectors are not +Integer+s.
+    #
     # @return [false]
-    def integer?
-      false
-    end
+    #
+    # @since 0.2.1
+    def integer? = false
   end
 end

data/lib/vector_number/stringifying.rb

@@ -4,21 +4,37 @@ class VectorNumber
   # Methods and options for string representation.
   module Stringifying
     # Predefined symbols for multiplication to display between unit and coefficient.
+    #
     # @return [Hash{Symbol => String}]
+    #
+    # @since 0.1.0
     MULT_STRINGS = {
       asterisk: "*", # U+002A
       cross: "×", # U+00D7
       dot: "⋅", # U+22C5
       invisible: "⁢", # U+2062, zero-width multiplication operator
       space: " ",
-      none: ""
+      none: "",
     }.freeze
 
+    # Get a string representation of the vector.
+    #
+    # @example
+    #   VectorNumber[5, "s"].to_s # => "5 + 1⋅'s'"
+    #   VectorNumber["s", 5].to_s # => "1⋅'s' + 5"
+    # @example with :mult argument
+    #   VectorNumber[5, "s"].to_s(mult: :asterisk) # => "5 + 1*'s'"
+    # @example :mult option specified for the vector
+    #   VectorNumber[5, "s", mult: :none].to_s # => "5 + 1's'"
+    #
     # @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
+    # @raise [ArgumentError]
+    #   if +mult+ is not a String and is not in {MULT_STRINGS}'s keys
+    #
+    # @since 0.1.0
     def to_s(mult: options[:mult])
       return "0" if zero?
 
@@ -34,8 +50,20 @@ class VectorNumber
       result
     end
 
+    # Get a string representation of the vector.
+    #
+    # This is similar to +Complex#inspect+: it returns result of {#to_s} in round brackets.
+    #
+    # @example
+    #   VectorNumber[5, "s"].inspect # => "(5 + 1⋅'s')"
+    #
     # @return [String]
+    #
+    # @see to_s
+    #
+    # @since 0.1.0
     def inspect
+      # TODO: Probably make this independent of options.
       "(#{self})"
     end
 
@@ -46,6 +74,8 @@ class VectorNumber
     # @param mult [Symbol, String]
     # @return [String]
     # @raise [ArgumentError] if +mult+ is not in {MULT_STRINGS}'s keys
+    #
+    # @since 0.1.0
     def value_to_s(unit, coefficient, mult:)
       if !mult.is_a?(String) && !MULT_STRINGS.key?(mult)
         raise ArgumentError, "unknown key #{mult.inspect}", caller

data/lib/vector_number/version.rb

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

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,53 +19,96 @@ 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}]
-  #   options for this number, if +values+ is a VectorNumber,
-  #   these will be merged with options from +values.options+
+  #   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 = {}.freeze, &)
-    # TODO: propagate options properly.
-    #   > (VectorNumber[1, 'a', mult: :invisible] + 2).options
-    #   => {:mult=>:dot}
-    super()
+  def initialize(values = nil, options = nil, &)
+    # @type var options: Hash[Symbol, Object]
     initialize_from(values)
     apply_transform(&)
     finalize_contents
@@ -78,15 +121,18 @@ class VectorNumber
   # Return self.
   #
   # @return [VectorNumber]
-  def dup
-    self
-  end
+  #
+  # @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
@@ -101,22 +147,31 @@ 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
   # @return [VectorNumber]
   def new(from = self, &)
-    self.class.new(from, &)
+    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)
 
@@ -132,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
@@ -145,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
@@ -152,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)
@@ -164,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?
 
@@ -178,32 +241,54 @@ 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]
       in [{} | nil, VectorNumber]
         values.options
+      in [{} | nil, [*, VectorNumber => vector, *]]
+        vector.options
       in Hash, VectorNumber
-        values.options.merge(options).slice(*known_options)
+        merge_options(values.options, options)
+      in Hash, [*, VectorNumber => vector, *]
+        merge_options(vector.options, options)
       in Hash, _ unless options.empty?
-        default_options.merge(options).slice(*known_options)
+        merge_options(default_options, options)
       else
         default_options
       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)
+
+    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
     @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

@@ -51,11 +51,12 @@ class VectorNumber
   def self.[]: (*unit_type values, **options_type options) -> vector_type
 
   def initialize:
-    (?(units_list_type | plain_vector_type | vector_type)? values, ?options_type options)
+    (?(units_list_type | plain_vector_type | vector_type)? values, ?options_type? options)
     ?{ (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,15 +89,17 @@ class VectorNumber
 
     def coerce: (in_value_type) -> [vector_type, self]
 
-    def +@: () -> 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 /
@@ -130,6 +134,8 @@ class VectorNumber
     def ceil: (Integer) -> vector_type
 
     def floor: (Integer) -> vector_type
+
+    def round: (Integer, ?half: (:up | :down | :even)) -> vector_type
   end
 
   # Methods for converting to different number classes.

metadata

@@ -1,21 +1,23 @@
 --- !ruby/object:Gem::Specification
 name: vector_number
 version: !ruby/object:Gem::Version
-  version: 0.2.6
+  version: 0.3.1
 platform: ruby
 authors:
 - Alexandr Bulancov
 bindir: exe
 cert_chain: []
-date: 2025-04-30 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: []