more_math 1.9.0 → 1.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bd844028040726f15a03d4260e794d2b6dd47edf0ddac071be3fc2d3e1742be5
-  data.tar.gz: 9fc2b5f24a5ffd586cfcd7f700dcb85510f799a8f1af356289233316d6f91966
+  metadata.gz: b375aa122041b022a2c6b6457cbd6ba9a87691e75a816696c004b57824a5c50e
+  data.tar.gz: ea3ae210dc593238418ea80b9d8c86b156b7fd53be2971349cbda9985e59aee1
 SHA512:
-  metadata.gz: ddd7116481e881af48ab5cd854f4ff6def832c30e491767bae3835f17bd2f12ba19d171c9b765d3ef41b1f50b33e6a5fa9ca73a7c6c9817379da13b0aa63e509
-  data.tar.gz: 0346e146c89234d85eb9ab38a69598f2dc879ea3335c23cddc36cc29ddfaf1cb0cd3e44fb7bc17a4634c3cfbb37a4ff2d0916d04f630b42dd1a7de7b2d8da341
+  metadata.gz: e28aaa3aaf79ab42eac1fbf4c4a678d7676279ebf326fed10e8c094d0040ad1d664b8a5e9b137a68c25077496886036c67fc377cfb0e1f4027d2c3abaf2ccbc8
+  data.tar.gz: 8f8f81bd9beb6c9b7f040d58ac6a90acb3fe4a9394896cd4822c148f7ee362e9c0ee5004785953a9f292b7fac2cf23177676cd46ed17f344e19337399b473cd8

data/CHANGES.md

@@ -1,5 +1,29 @@
 # Changes
 
+## 2026-01-19 v1.10.0
+
+- Added new `entropy_maximum` method to calculate theoretical maximum entropy
+  for a text given an alphabet size
+- Made `size` parameter required in `entropy_ratio` and `entropy_ratio_minimum`
+  methods instead of defaulting to `text.size`
+- Updated YARD documentation to clarify that `size` parameter represents
+  alphabet size
+- Modified examples to use explicit alphabet sizes for better clarity
+- All entropy methods now consistently return values in bits as expected for
+  Shannon entropy
+- Updated documentation examples to use simplified method calls without
+  `MoreMath::Entropy` prefix
+- Enhanced `entropy_maximum` method documentation to explain its use in
+  determining security strength for tokens
+- Added comprehensive tests for `entropy_maximum` function covering edge cases
+  and various alphabet sizes
+- Improved `entropy_maximum` method signature to return `0` for invalid
+  alphabet sizes (≤ 1) and use `Math.log2` for calculation
+- Updated existing entropy method documentation to clarify it calculates
+  entropy in bits
+- Simplified example code in documentation to use direct method calls instead
+  of module prefixes
+
 ## 2026-01-16 v1.9.0
 
 - Added support for array inputs in entropy calculation methods by checking

data/lib/more_math/entropy.rb

@@ -15,24 +15,24 @@ module MoreMath
   #
   # @example Basic usage
   #   require 'more_math'
-  #   include MoreMath
+  #   include MoreMath::Functions
   #
   #   text = "hello world"
   #   puts entropy(text)        # => 2.3219280948873626
   #   puts entropy_ratio(text)   # => 0.7428571428571429
   #
   # @example Using with different text samples
-  #   MoreMath::Entropy.entropy("aaaa")           # => 0.0 (no entropy)
-  #   MoreMath::Entropy.entropy("abcd")           # => 2.0 (maximum entropy)
+  #   entropy("aaaa")           # => 0.0 (no entropy)
+  #   entropy("abcd")           # => 2.0 (actual entropy)
   module Entropy
-    # Calculates the Shannon entropy of a text string.
+    # Calculates the Shannon entropy in bits of a text string.
     #
     # Shannon entropy measures the average amount of information (in bits) needed
     # to encode characters in the text based on their frequencies.
     #
     # @example
-    #   MoreMath::Entropy.entropy("hello") # => 2.3219280948873626
-    #   MoreMath::Entropy.entropy("aaaa")  # => 0.0
+    #   entropy("hello") # => 2.3219280948873626
+    #   entropy("aaaa")  # => 0.0
     #
     # @param text [String] The input text to calculate entropy for
     # @return [Float] The Shannon entropy in bits
@@ -58,8 +58,8 @@ module MoreMath
     # alphabet have equal probability of occurrence.
     #
     # @example
-    #   MoreMath::Entropy.entropy_ideal(2)  # => 1.0
-    #   MoreMath::Entropy.entropy_ideal(256) # => 8.0
+    #   entropy_ideal(2)  # => 1.0
+    #   entropy_ideal(256) # => 8.0
     #
     # @param size [Integer] The number of unique characters in the alphabet
     # @return [Float] The maximum possible entropy in bits
@@ -80,21 +80,18 @@ module MoreMath
     # theoretical maximum entropy for that character set.
     #
     # @example
-    #   MoreMath::Entropy.entropy_ratio("hello")     # => 0.6834
-    #   MoreMath::Entropy.entropy_ratio("aaaaa")     # => 0.0
-    #   MoreMath::Entropy.entropy_ratio("abcde")     # => 1.0
+    #   entropy_ratio("hello")     # => 0.6834
+    #   entropy_ratio("aaaaa")     # => 0.0
+    #   entropy_ratio("abcde")     # => 1.0
     #
     # @example With custom alphabet size
     #   # Normalizing against a 26-letter alphabet (English)
-    #   MoreMath::Entropy.entropy_ratio("hello", size: 26) # => 0.394...
+    #   entropy_ratio("hello", size: 26) # => 0.394...
     #
     # @param text [String] The input text to calculate entropy ratio for
-    # @param size [Integer] The size of the character set to normalize against.
-    #   Defaults to the total length of the text (`text.size`), which
-    #   normalizes the entropy relative to the text's own character space.
-    #   This allows comparison of texts with different lengths on the same scale.
+    # @param size [Integer] The size of the character set to normalize against (alphabet size).
     # @return [Float] Normalized entropy ratio between 0 and 1
-    def entropy_ratio(text, size: text.size)
+    def entropy_ratio(text, size:)
       size <= 1 and return 0.0
       entropy(text) / entropy_ideal(size)
     end
@@ -107,11 +104,12 @@ module MoreMath
     #
     # @param text [String] The input text to calculate entropy ratio for
     # @param size [Integer] The size of the character set to normalize against
+    #   (alphabet size).
     # @param alpha [Float] The significance level for the confidence interval (default: 0.05)
     # @return [Float] The adjusted entropy ratio within the confidence interval
     # @raise [ArgumentError] When alphabet size is less than 2
     # @raise [ArgumentError] When text is empty
-    def entropy_ratio_minimum(text, size: text.size, alpha: 0.05)
+    def entropy_ratio_minimum(text, size:, alpha: 0.05)
       raise ArgumentError, 'alphabet size must be ≥ 2' if size < 2
       raise ArgumentError, 'text must not be empty'    if text.empty?
 
@@ -129,5 +127,25 @@ module MoreMath
 
       (ratio - z * se).clamp(0, 1)
     end
+
+    # Calculates the maximum possible entropy for a given text and alphabet
+    # size.
+    #
+    # This represents the theoretical maximum entropy that could be achieved if
+    # all characters in the text were chosen uniformly at random from the
+    # alphabet. It's used to determine the upper bound of security strength for
+    # tokens.
+    #
+    # @example
+    #   entropy_maximum("hello", size: 26)  # => 23
+    #   entropy_maximum("abc123", size: 64) # => 36
+    #
+    # @param text [String] The input text to calculate maximum entropy for
+    # @param size [Integer] The size of the character set (alphabet size)
+    # @return [Integer] The maximum possible entropy in bits, or 0 if size <= 1
+    def entropy_maximum(text, size:)
+      size > 1 or return 0
+      (text.size * Math.log2(size)).floor
+    end
   end
 end

data/lib/more_math/version.rb

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

data/more_math.gemspec

@@ -1,9 +1,9 @@
 # -*- encoding: utf-8 -*-
-# stub: more_math 1.9.0 ruby lib
+# stub: more_math 1.10.0 ruby lib
 
 Gem::Specification.new do |s|
   s.name = "more_math".freeze
-  s.version = "1.9.0".freeze
+  s.version = "1.10.0".freeze
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0".freeze) if s.respond_to? :required_rubygems_version=
   s.require_paths = ["lib".freeze]

data/tests/entropy_test.rb

@@ -36,12 +36,22 @@ class EntropyTest < Test::Unit::TestCase
     assert_in_delta 4,     entropy_ideal(16), 1E-3
   end
 
+  def test_entropy_mamxium
+    text = 'A' * 64
+    assert_equal 0, entropy_maximum(text, size: -1)
+    assert_equal 0, entropy_maximum(text, size: 0)
+    assert_equal 0, entropy_maximum(text, size: 1)
+    assert_equal 64, entropy_maximum(text, size: 2)
+    assert_equal 256, entropy_maximum(text, size: 16)
+    assert_equal 128, entropy_maximum(text[0, 32], size: 16)
+  end
+
   def test_entropy_ratio
-    assert_equal 0,        entropy_ratio(@empty)
+    assert_equal 0,        entropy_ratio(@empty, size: 128)
     assert_equal 0,        entropy_ratio(@low, size: 128)
     assert_in_delta 0.564, entropy_ratio(@string, size: 128), 1E-3
     assert_in_delta 0.633, entropy_ratio(@high, size: 128), 1E-3
-    assert_in_delta 1.0,   entropy_ratio(@random), 1E-3
+    assert_in_delta 1.0,   entropy_ratio(@random, size: @random.size), 1E-3
     assert_in_delta 0.462, entropy_ratio(@random, size: 256), 1E-3
     assert_in_delta 0.253, entropy_ratio(@hi, size: 2_136), 1E-3
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: more_math
 version: !ruby/object:Gem::Version
-  version: 1.9.0
+  version: 1.10.0
 platform: ruby
 authors:
 - Florian Frank