more_math 1.5.0 → 1.6.0

data/lib/more_math/string_numeral.rb

@@ -1,7 +1,49 @@
 module MoreMath
+  # StringNumeral provides a way to treat strings as numbers using a base-N
+  # system where N is the size of the alphabet. This allows for arithmetic
+  # operations on strings, converting them to numeric representations and back.
+  #
+  # The implementation uses the Cantor pairing function approach for encoding
+  # strings into integers and vice versa, making it suitable for applications
+  # requiring ordered string enumeration or Gödel numbering.
+  #
+  # @example Basic usage
+  #   include MoreMath
+  #
+  #   # Convert a string to its numeric representation
+  #   str_num = "abc".to_string_numeral
+  #   puts str_num.number  # => 731  (assuming 'a'..'z' alphabet)
+  #
+  #   # Convert back to string
+  #   puts 731.to_string_numeral.string  # => "abc"
+  #
+  # @example Arithmetic operations
+  #   a = "hello".to_string_numeral
+  #   b = "world".to_string_numeral
+  #
+  #   # Addition
+  #   sum = a + b
+  #   puts sum.string  # => "hello" + "world" (in numeric sense)
+  #
+  # @example With custom alphabet
+  #   custom_alphabet = ['a', 'b', 'c']
+  #   str_num = StringNumeral.from("abc", custom_alphabet)
+  #   puts str_num.number  # => 18 (base-3 representation)
   class StringNumeral
     include ::MoreMath::NumberifyStringFunction
 
+    # Creates a StringNumeral instance from an object.
+    #
+    # This is the primary factory method that handles conversion from various
+    # input types:
+    # - Symbol: converts to string first
+    # - String: uses directly as string representation
+    # - Integer: converts to numeric representation
+    # - Other objects: calls to_str or to_int as appropriate
+    #
+    # @param object [Object] The input object to convert
+    # @param alphabet [Array<String>, Range<String>] The alphabet to use for conversion
+    # @return [StringNumeral] A new StringNumeral instance
     def self.from(object, alphabet = 'a'..'z')
       if Symbol === object
         StringNumeral.from_string(object.to_s, alphabet)
@@ -14,14 +56,33 @@ module MoreMath
       end
     end
 
+    # Creates a StringNumeral instance from a string.
+    #
+    # @param string [String] The string to convert
+    # @param alphabet [Array<String>, Range<String>] The alphabet to use
+    # @return [StringNumeral] A new StringNumeral instance
     def self.from_string(string, alphabet)
       new string, nil, alphabet
     end
 
+    # Creates a StringNumeral instance from a number.
+    #
+    # @param number [Integer] The number to convert
+    # @param alphabet [Array<String>, Range<String>] The alphabet to use
+    # @return [StringNumeral] A new StringNumeral instance
     def self.from_number(number, alphabet)
       new nil, number, alphabet
     end
 
+    # Initializes a StringNumeral instance.
+    #
+    # This private constructor handles the internal state setup for either
+    # string-to-number or number-to-string conversion.
+    #
+    # @param string [String, nil] The string representation (if converting from string)
+    # @param number [Integer, nil] The numeric representation (if converting from number)
+    # @param alphabet [Array<String>, Range<String>] The alphabet to use
+    # @raise [ArgumentError] If the string contains characters not in the alphabet
     def initialize(string, number, alphabet)
       @alphabet = NumberifyStringFunction.convert_alphabet(alphabet).freeze
       if string
@@ -36,96 +97,185 @@ module MoreMath
     end
     private_class_method :new
 
+    # Returns the numeric representation of this StringNumeral.
+    #
+    # This method converts the internal string representation to its numeric value
+    # using the specified alphabet. The conversion follows a positional numeral system
+    # where each character position represents a power of the alphabet size.
+    #
+    # @return [Integer] The numeric representation
     def number
       @number ||= numberify_string(@string, @alphabet)
     end
     alias to_i number
     alias to_int number
 
+    # Returns the string representation of this StringNumeral.
+    #
+    # This method converts the internal numeric representation back to its string form
+    # using the specified alphabet. It's the inverse operation of {#number}.
+    #
+    # @return [String] The string representation
     def string
       @string ||= stringify_number(@number, @alphabet).freeze
     end
     alias to_s string
     alias to_str string
 
+    # Returns a string representation for debugging.
+    #
+    # @return [String] A debug-friendly representation of this instance
     def inspect
       "#<#{self.class}: #{string.inspect} #{number.inspect}>"
     end
 
+    # Returns the alphabet used by this StringNumeral.
+    #
+    # @return [Array<String>] The alphabet array
     attr_reader :alphabet
 
+    # Converts another object to a numeric value for arithmetic operations.
+    #
+    # This method is used in Ruby's coercion protocol to enable mixed-type arithmetic.
+    #
+    # @param other [Object] The other operand
+    # @return [Array<Integer>] Array containing the naturalized values
     def coerce(other)
       [ naturalize(other), number ]
     end
 
-    def *(other)
-      self.class.from_number(number * naturalize(other), @alphabet)
-    end
-
+    # Performs addition with another StringNumeral or numeric value.
+    #
+    # @param other [StringNumeral, Integer] The value to add
+    # @return [StringNumeral] A new StringNumeral instance representing the sum
     def +(other)
       self.class.from_number(number + naturalize(other), @alphabet)
     end
 
+    # Performs multiplication with another StringNumeral or numeric value.
+    #
+    # @param other [StringNumeral, Integer] The value to multiply by
+    # @return [StringNumeral] A new StringNumeral instance representing the product
+    def *(other)
+      self.class.from_number(number * naturalize(other), @alphabet)
+    end
+
+    # Performs subtraction with another StringNumeral or numeric value.
+    #
+    # @param other [StringNumeral, Integer] The value to subtract
+    # @return [StringNumeral] A new StringNumeral instance representing the difference
     def -(other)
       self.class.from_number(naturalize(number - other), @alphabet)
     end
 
+    # Performs division with another StringNumeral or numeric value.
+    #
+    # @param other [StringNumeral, Integer] The divisor
+    # @return [StringNumeral] A new StringNumeral instance representing the quotient
     def /(other)
       self.class.from_number((number / naturalize(other)), @alphabet)
     end
 
+    # Performs modulo operation with another StringNumeral or numeric value.
+    #
+    # @param other [StringNumeral, Integer] The divisor for modulo
+    # @return [StringNumeral] A new StringNumeral instance representing the remainder
     def %(other)
       self.class.from_number((number % naturalize(other)), @alphabet)
     end
 
+    # Performs exponentiation with another StringNumeral or numeric value.
+    #
+    # @param other [StringNumeral, Integer] The exponent
+    # @return [StringNumeral] A new StringNumeral instance representing the power
     def **(other)
       self.class.from_number(number ** naturalize(other), @alphabet)
     end
 
+    # Performs left bit shift with another numeric value.
+    #
+    # @param other [Integer] The number of bits to shift
+    # @return [StringNumeral] A new StringNumeral instance representing the shifted value
     def <<(other)
       self.class.from_number(number << naturalize(other), @alphabet)
     end
 
+    # Performs right bit shift with another numeric value.
+    #
+    # @param other [Integer] The number of bits to shift
+    # @return [StringNumeral] A new StringNumeral instance representing the shifted value
     def >>(other)
       self.class.from_number(number >> naturalize(other), @alphabet)
     end
 
+    # Performs bitwise XOR with another numeric value.
+    #
+    # @param other [Integer] The value to XOR with
+    # @return [StringNumeral] A new StringNumeral instance representing the result
     def ^(other)
       self.class.from_number(number ^ naturalize(other), @alphabet)
     end
 
+    # Performs bitwise AND with another numeric value.
+    #
+    # @param other [Integer] The value to AND with
+    # @return [StringNumeral] A new StringNumeral instance representing the result
     def &(other)
       self.class.from_number(number & naturalize(other), @alphabet)
     end
 
+    # Performs bitwise OR with another numeric value.
+    #
+    # @param other [Integer] The value to OR with
+    # @return [StringNumeral] A new StringNumeral instance representing the result
     def |(other)
       self.class.from_number(number | naturalize(other), @alphabet)
     end
 
+    # Performs indexing operation on the numeric value.
+    #
+    # @param other [Integer] The index to access
+    # @return [StringNumeral] A new StringNumeral instance representing the indexed result
     def [](other)
       self.class.from_number(number[other.to_i], @alphabet)
     end
 
+    # Returns the successor of this StringNumeral.
+    #
+    # @return [StringNumeral] A new StringNumeral with number incremented by 1
     def succ
       self.class.from_number(number + 1, @alphabet)
     end
 
+    # Increments this StringNumeral in place.
+    #
+    # @return [self] Returns self after incrementing
     def succ!
       @number += 1
       @string = nil
       self
     end
 
+    # Returns the predecessor of this StringNumeral.
+    #
+    # @return [StringNumeral] A new StringNumeral with number decremented by 1
     def pred
       self.class.from_number(naturalize(number - 1), @alphabet)
     end
 
+    # Decrements this StringNumeral in place.
+    #
+    # @return [self] Returns self after decrementing
     def pred!
       @number = naturalize(@number - 1)
       @string = nil
       self
     end
 
+    # Checks equality with another object.
+    #
+    # @param other [Object] The object to compare with
+    # @return [Boolean] true if equal, false otherwise
     def eql?(other)
       if other.respond_to?(:to_int)
         to_int == other.to_int
@@ -136,28 +286,46 @@ module MoreMath
 
     alias == eql?
 
+    # Returns a hash value for this StringNumeral.
+    #
+    # @return [Integer] The hash value
     def hash
       number.hash
     end
 
     private
 
+    # Ensures a value is treated as a non-negative integer.
+    #
+    # @param number [Object] The number to normalize
+    # @return [Integer] The normalized non-negative integer
     def naturalize(number)
       number = number.to_i
       number < 0 ? 0 : number
     end
 
+    # Module containing convenience methods for StringNumeral conversion.
     module Functions
+      # Creates a StringNumeral from an object.
+      #
+      # @param other [Object] The object to convert
+      # @param alphabet [Array<String>, Range<String>] The alphabet to use
+      # @return [StringNumeral] A new StringNumeral instance
       def StringNumeral(other, alphabet = 'a'..'z')
         ::MoreMath::StringNumeral.from(other, alphabet)
       end
 
+      # Converts this object to a StringNumeral.
+      #
+      # @param alphabet [Array<String>, Range<String>] The alphabet to use
+      # @return [StringNumeral] A new StringNumeral instance
       def to_string_numeral(alphabet = 'a'..'z')
         StringNumeral(self, alphabet)
       end
     end
   end
 
+  # Extends the Object class with StringNumeral conversion methods.
   class ::Object
     include StringNumeral::Functions
   end

data/lib/more_math/subset.rb

@@ -1,18 +1,49 @@
 require 'more_math/ranking_common'
 
 module MoreMath
+  # A subset represents a selection of elements from a set, where each element
+  # can either be included (1) or excluded (0) from the subset. Subsets are
+  # ranked in lexicographic order, allowing efficient enumeration and indexing.
+  #
+  # @example Create a subset of size 3
+  #   subset = Subset.new(3)
+  #   # => #<Subset:0x6ae34 @last=7, @rank=0, @size=3>
+  #
+  # @example Create a subset with specific rank
+  #   subset = Subset.new(3, 5)
+  #   # => #<Subset:0x6ae34 @last=7, @rank=5, @size=3>
+  #
+  # @example Get the subset as an array of indices
+  #   subset = Subset.new(3, 5)
+  #   subset.value
+  #   # => [0, 2]
+  #
+  # @example Project onto actual data
+  #   subset = Subset.new(3, 5)
+  #   subset.project(['a', 'b', 'c'])
+  #   # => ['a', 'c']
   class Subset
     include Enumerable
     include RankingCommon
 
     # Returns a Subset instance for a collection of size +size+ with the rank
     # +rank+.
+    # Creates a new Subset instance of <code>size</code> (and ranked with
+    # <code>rank</code>).
+    #
+    # @param size [Integer] The size of the subset
+    # @param rank [Integer] The rank of the subset (default: 0)
     def initialize(size, rank = 0)
       @size, self.rank = size, rank
       @last = (1 << size) - 1
     end
 
-    # Returns the subset of the collection +collection+ for the rank +rank+.
+    # Creates a new Subset instance for a collection of size +size+ with the
+    # rank +rank+.
+    #
+    # @param collection [Object] collection to use for projection
+    # @param rank [Integer] the rank of this subset (default: 0)
+    # @return [Subset] new subset instance
     def self.for(collection, rank = 0)
       subset = new(collection.size, rank)
       subset.instance_variable_set(:@collection, collection)
@@ -20,30 +51,43 @@ module MoreMath
     end
 
     # Returns the power set of the collection +collection+.
+    #
+    # @param collection [Object] the collection to generate power set for
+    # @return [Array<Array>] array of all possible subsets
     def self.power_set(collection)
       self.for(collection).map(&:value)
     end
 
-    # Assigns <code>m</code> to the rank attribute of this object.
+    # Assigns <code>m</code> to the rank attribute of this Subset instance.
+    # That implies that the indices produced by a call to the Subset#value method
+    # of this instance is the subset ranked with this new <code>rank</code>.
+    #
+    # @param m [Integer] new rank value
+    # @return [Integer] assigned rank
     def rank=(m)
       @rank = m % (1 << size)
     end
 
     # Returns the subset for rank #rank and #collection. (If no collection was
     # set it applies to the array [ 0, 1, ..., size - 1 ] instead.)
+    #
+    # @return [Array<Integer>] array of indices representing this subset
     def value
       result = []
       c = @collection || (0...size).to_a
       r = @rank
-      0.upto(size) do |i|
+      size.times do |i|
         r[i] == 1 and result << c[i]
       end
       result
     end
 
-    # This method maps elements from a given dataset based on the
-    # subset's indices determined by its rank and returns the result, while
+    # This method maps elements from a given dataset based on the subset's
+    # indices determined by its rank and returns the result, while
     # ensuring the input data size matches the subset's size.
+    #
+    # @param data [Object] data to project onto (optional)
+    # @return [Array] projected result
     def project(data = nil)
       data ||= @collection || (0...size).to_a
       raise ArgumentError, "data size is != #{size}!" if data.size != size

data/lib/more_math/version.rb

@@ -1,6 +1,6 @@
 module MoreMath
   # MoreMath version
-  VERSION         = '1.5.0'
+  VERSION         = '1.6.0'
   VERSION_ARRAY   = VERSION.split('.').map(&:to_i) # :nodoc:
   VERSION_MAJOR   = VERSION_ARRAY[0] # :nodoc:
   VERSION_MINOR   = VERSION_ARRAY[1] # :nodoc:

data/lib/more_math.rb

@@ -1,3 +1,4 @@
+# Main namespace module for the MoreMath library.
 module MoreMath
   unless defined?(::MoreMath::Infinity) == 'constant'
     Infinity = 1.0 / 0      # Refers to floating point infinity.

data/more_math.gemspec

@@ -1,9 +1,9 @@
 # -*- encoding: utf-8 -*-
-# stub: more_math 1.5.0 ruby lib
+# stub: more_math 1.6.0 ruby lib
 
 Gem::Specification.new do |s|
   s.name = "more_math".freeze
-  s.version = "1.5.0".freeze
+  s.version = "1.6.0".freeze
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0".freeze) if s.respond_to? :required_rubygems_version=
   s.require_paths = ["lib".freeze]
@@ -23,12 +23,13 @@ Gem::Specification.new do |s|
 
   s.specification_version = 4
 
-  s.add_development_dependency(%q<gem_hadar>.freeze, ["~> 2.4".freeze])
+  s.add_development_dependency(%q<gem_hadar>.freeze, ["~> 2.7".freeze])
   s.add_development_dependency(%q<rake>.freeze, [">= 0".freeze])
   s.add_development_dependency(%q<simplecov>.freeze, [">= 0".freeze])
   s.add_development_dependency(%q<test-unit>.freeze, [">= 0".freeze])
   s.add_development_dependency(%q<debug>.freeze, [">= 0".freeze])
   s.add_development_dependency(%q<all_images>.freeze, [">= 0".freeze])
+  s.add_development_dependency(%q<context_spook>.freeze, [">= 0".freeze])
   s.add_runtime_dependency(%q<tins>.freeze, ["~> 1".freeze])
   s.add_runtime_dependency(%q<mize>.freeze, [">= 0".freeze])
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: more_math
 version: !ruby/object:Gem::Version
-  version: 1.5.0
+  version: 1.6.0
 platform: ruby
 authors:
 - Florian Frank
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.4'
+        version: '2.7'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.4'
+        version: '2.7'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -93,6 +93,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: context_spook
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: tins
   requirement: !ruby/object:Gem::Requirement