vector_number 0.4.3 → 0.6.0

data/lib/vector_number/numeric_refinements.rb

@@ -16,6 +16,10 @@ class VectorNumber
   #
   # @since 0.2.0
   module NumericRefinements
+    # CommutativeShuttle refinement works only on 3.1, so it almost never actually runs.
+    # There are tests for the correct behavior, however, so it's fine.
+    # :nocov:
+
     # Refinement module to provide a +#<=>+ method that can work backwards.
     #
     # @note Currently only applies to Complex on *3.1*,
@@ -49,6 +53,7 @@ class VectorNumber
         warn "Numeric refinements are not available on Ruby < 3.1"
       end
     end
+    # :nocov:
 
     # Refinement module to change Kernel#BigDecimal so it works with +#to_d+.
     #
@@ -79,6 +84,7 @@ class VectorNumber
       end
     end
 
+    # :nocov:
     if defined?(BigDecimal)
       refine(Kernel) do
         import_methods BigDecimalToD
@@ -86,5 +92,6 @@ class VectorNumber
         warn "Numeric refinements are not available on Ruby < 3.1"
       end
     end
+    # :nocov:
   end
 end

data/lib/vector_number/querying.rb

@@ -1,150 +1,150 @@
 # 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.
-    #
-    # @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
+  # @group Querying
+  #
+  # Mostly modelled after {::Complex}.
 
-      size <= dimensions && (1..dimensions).count { @data[UNIT[_1]].nonzero? } == size
-    end
+  # Returns +true+ if all non-zero dimensions in this VectorNumber are numeric (real or complex),
+  # and +false+ otherwise.
+  #
+  # This is exactly the opposite of {#nonnumeric?}.
+  #
+  # @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
+  # @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
 
-    # 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?)
-    #
-    # @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
+    size <= dimensions &&
+      (0...dimensions).count { (unit = NUMERIC_UNITS[_1]) && @data[unit].nonzero? } == size
+  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 this VectorNumber contains any non-zero dimensions with non-numeric units,
+  # and +false+ otherwise.
+  #
+  # This is exactly the opposite of {#numeric?}.
+  #
+  # @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?)
+  #
+  # @since 0.2.1
+  def nonnumeric?(dimensions = 2) = !numeric?(dimensions)
 
-    # Returns +true+ if there are no non-zero coefficients, and +false+ otherwise.
-    #
-    # @example
-    #   VectorNumber["c"].zero? # => false
-    #   VectorNumber[].zero? # => true
-    #
-    # @return [Boolean]
-    #
-    # @since 0.1.0
-    def zero? = size.zero?
+  # 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]
+  def finite?
+    all? { |_u, v| v.finite? }
+  end
 
-    # 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 +1+ if any coefficients are non-finite, +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]
+  def infinite?
+    finite? ? nil : 1 # 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 there are no non-zero coefficients, and +false+ otherwise.
+  #
+  # This is synonymous with +size+ being 0.
+  #
+  # @example
+  #   VectorNumber["c"].zero? # => false
+  #   VectorNumber[].zero? # => true
+  #
+  # @see #size
+  #
+  # @return [Boolean]
+  def zero? = size.zero?
 
-    # 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
+  # Returns +self+ if there are any non-zero coefficients, +nil+ otherwise.
+  #
+  # This is synonymous with +size+ not being equal to 0.
+  # Behavior of returning self or +nil+ is the same as +Numeric+'s.
+  #
+  # @example
+  #   VectorNumber["ab", "cd"].nonzero? # => (1⋅"ab" + 1⋅"cd")
+  #   VectorNumber[].nonzero? # => nil
+  #
+  # @see #size
+  #
+  # @return [VectorNumber, nil]
+  def nonzero?
+    zero? ? nil : self # rubocop:disable Style/ReturnNilInPredicateMethodDefinition
+  end
 
-    # Always returns +false+, as vectors are not real numbers.
-    #
-    # This behavior is the same as +Complex+'s.
-    #
-    # @see #numeric?
-    #
-    # @return [false]
-    #
-    # @since 0.1.0
-    def real? = false
+  # 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]
+  def positive?
+    !zero? && all? { |_u, c| c.positive? }
+  end
 
-    # Always returns +false+, as vectors are not +Integer+s.
-    #
-    # @return [false]
-    #
-    # @since 0.2.1
-    def integer? = false
+  # 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]
+  def negative?
+    !zero? && all? { |_u, c| c.negative? }
   end
+
+  # Always returns +false+, as vectors are not real numbers.
+  #
+  # This behavior is the same as +Complex+'s.
+  #
+  # @see #numeric?
+  #
+  # @return [false]
+  def real? = false
+
+  # Always returns +false+, as vectors are not +Integer+s.
+  #
+  # @return [false]
+  #
+  # @since 0.2.1
+  def integer? = false
 end

data/lib/vector_number/special_unit.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+class VectorNumber
+  # Class for representing special units.
+  #
+  # The public API consists of:
+  # - +#==+/+#eql?+/+#equal?+ (from +Object+)
+  # - +#hash+ (from +Object+)
+  # - {#to_s}
+  # - {#inspect}
+  #
+  # @since 0.6.0
+  class SpecialUnit
+    # @api private
+    # @param unit [#to_s] name for {#inspect}
+    # @param text [String] text for {#to_s}
+    def initialize(unit, text)
+      @unit = unit
+      @text = text
+    end
+
+    # Get predefined string representation of the unit.
+    #
+    # @return [String]
+    def to_s
+      @text
+    end
+
+    # Get string representation of the unit for debugging.
+    #
+    # @return [String]
+    def inspect
+      "unit/#{@unit}"
+    end
+  end
+end

data/lib/vector_number/stringifying.rb

@@ -1,96 +1,105 @@
 # 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}]
-    #
-    # @since 0.1.0
-    MULT_STRINGS = {
-      asterisk: "*", # U+002A
-      cross: "×", # U+00D7
-      dot: "⋅", # U+22C5
-      invisible: "⁢", # U+2062, zero-width multiplication operator
-      space: " ",
-      none: "",
-    }.freeze
+  # 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
 
-    # 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 a String and is not in {MULT_STRINGS}'s keys
-    #
-    # @since 0.1.0
-    def to_s(mult: options[:mult])
-      return "0" if zero?
+  # @group Miscellaneous methods
 
-      result = +""
-      each_with_index do |(unit, coefficient), index|
+  # Return string representation of the vector.
+  #
+  # An optional block can be supplied to provide customized substrings
+  # for each unit and coefficient pair.
+  # Care needs to be taken in handling +VectorNumber::R+ and +VectorNumber::I+ units.
+  # {.numeric_unit?} can be used to check if a particular unit needs special handling.
+  #
+  # @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"
+  #   (-VectorNumber[5, :s]).to_s(mult: "~~~") # => "-5 - 1~~~s"
+  # @example with a block
+  #   VectorNumber[5, :s].to_s { |k, v| "#{format("%+.0f", v)}%#{k}" } # => "+5%1+1%s"
+  #   VectorNumber[5, :s].to_s(mult: :cross) { |k, v, i, op|
+  #     "#{',' unless i.zero?}#{v}#{op+k.to_s unless k == VectorNumber::R}"
+  #   } # => "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
+  # @yieldparam unit [Object]
+  # @yieldparam coefficient [Numeric]
+  # @yieldparam index [Integer]
+  # @yieldparam operator [String]
+  # @yieldreturn [String] a string for this unit and coefficient
+  # @return [String]
+  # @raise [ArgumentError]
+  #   if +mult+ is not a String and is not in {MULT_STRINGS}'s keys
+  def to_s(mult: :dot, &block)
+    if !mult.is_a?(String) && !MULT_STRINGS.key?(mult)
+      raise ArgumentError, "unknown key #{mult.inspect}", caller
+    end
+    return "0" if zero?
+
+    operator = mult.is_a?(String) ? mult : MULT_STRINGS[mult]
+    build_string(operator, &block)
+  end
+
+  # Return 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
+  def inspect
+    "(#{self})"
+  end
+
+  private
+
+  # @param operator [String]
+  # @return [String]
+  def build_string(operator)
+    result = +""
+    each_with_index do |(unit, coefficient), index|
+      if block_given?
+        result << (yield unit, coefficient, index, operator).to_s
+      else
         if index.zero?
           result << "-" if coefficient.negative?
         else
           result << (coefficient.positive? ? " + " : " - ")
         end
-        result << value_to_s(unit, coefficient.abs, mult: mult)
+        result << value_to_s(unit, coefficient.abs, operator)
       end
-      result
     end
+    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
-
-    private
-
-    # @param unit [Object]
-    # @param coefficient [Numeric]
-    # @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
-      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
+  # @param unit [Object]
+  # @param coefficient [Numeric]
+  # @param operator [String]
+  # @return [String]
+  def value_to_s(unit, coefficient, operator)
+    if NUMERIC_UNITS.include?(unit)
+      "#{coefficient}#{unit}"
+    else
+      unit = unit.inspect if unit.is_a?(String)
+      "#{coefficient}#{operator}#{unit}"
     end
   end
 end

data/lib/vector_number/version.rb

@@ -2,5 +2,5 @@
 
 class VectorNumber
   # @return [String]
-  VERSION = "0.4.3"
+  VERSION = "0.6.0"
 end