chars 0.2.4 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6257e8d2fa2f62cc364fc2e0ba901d777963476968264dd7747bc4407e5ff54c
-  data.tar.gz: 16f5ecc2f44e8265869aac4946a64cacda2ae8dcdae3b669081a48d34f034f4e
+  metadata.gz: 744e39b682dc29231aafe96056415cc38c65e032df5c2a3aff6a5a846b38f67b
+  data.tar.gz: 47e309f42894f6d94ec2d15568d5d33df8a97600c1c227eb2366eb8fb8d56eb4
 SHA512:
-  metadata.gz: ebaf16c18de6b000b6219bf4afe7142926e24293b6b1e62214f937c51c5bdf7f5ffa7f46eecb151e1da044f7b49e1479b7d2cc947a6e20fa2a586f28b4a8a525
-  data.tar.gz: 4c9c98dcbab77b201b86fc32a628575e4b0ebc03608c50c7591b51a70821127778ced5122f57de846c7c863440fa0e9555fe7bfd2940a913e494a929c74a513e
+  metadata.gz: 20755db9457fda76ceed274d18919a43dbf3c850d0aaad6a38f077b0e89fcf15d7c0a79b3ac95fe158d5abef8db4e68bd0ccc6971f8989e0b4f7c918b9a282b8
+  data.tar.gz: 54bc4adfd93752f68454c475b57a1705428231f8decab3be8b8710d6c344c60715af7c466b21b7c398e7b2cc30801ff5fe77a4924e1ac34b4fa724c3f1a3adec

data/ChangeLog.md

@@ -1,3 +1,15 @@
+### 0.3.0 / 2021-10-23
+
+* Added {Chars::WHITESPACE}.
+* Added {Chars::DIGITS}.
+* Added {Chars::CharSet#each_substring_with_index}.
+* Added {Chars::CharSet#substrings_with_indexes}.
+* Added {Chars::CharSet#each_substring}.
+* Added {Chars::CharSet#substrings}.
+* Added {Chars::CharSet#each_string_of_length}.
+* Added {Chars::CharSet#strings_of_length}.
+* Added {Chars::StringEnumerator}.
+
 ### 0.2.4 / 2021-10-22
 
 * Require [ruby] >= 2.0.0.

data/README.md

@@ -48,14 +48,6 @@ Determine whether a String belongs to a character set:
 # => true
 ```
 
-Find all sub-strings that belong to a character set within a String:
-
-```ruby
-ls = File.read('/bin/ls')
-Chars.printable.strings_in(ls)
-# => ["/lib64/ld-linux-x86-64.so.2", "KIq/", "5J~!", "%L~!", ...]
-```
-
 Return a random character from the set of all characters:
 
 ```ruby
@@ -85,6 +77,14 @@ Chars.all.random_string(10)
 # => "\xc2h\xad\xccm7\x1e6J\x13"
 ```
 
+Generate a secure password:
+
+```ruby
+require 'securerandom'
+Chars.visible.random_string(10..14, random: SecureRandom)
+# => ".*$X=D*XK2h8gC"
+```
+
 Return a random String with a random length between 5 and 10, from the
 set of space characters:
 
@@ -93,6 +93,57 @@ Chars.space.random_string(5..10)
 # => "\r\v\n\t\n\f"
 ```
 
+Find all sub-strings that belong to a character set within a String:
+
+```ruby
+ls = File.binread('/bin/ls')
+Chars.printable.substrings(ls)
+# => 
+# ["/lib64/ld-linux-x86-64.so.2",
+#  "_ITM_deregisterTMCloneTable",
+#  "__gmon_start__",
+#  "_ITM_registerTMCloneTable",
+#  ...
+# ]
+```
+
+Find all sub-strings that belong to a character set within a String, with
+indexes:
+
+```ruby
+ls = File.binread('/bin/ls')
+Chars.printable.substrings_with_indexes(ls)
+# =>
+# [["/lib64/ld-linux-x86-64.so.2", 792],
+#  ["_ITM_deregisterTMCloneTable", 4009],
+#  ["__gmon_start__", 4037],
+#  ["_ITM_registerTMCloneTable", 4052],
+#  ...
+# ]
+```
+
+Enumerate over all strings from a character set of a given length:
+
+```ruby
+passwords = Chars.visible.strings_of_length(6)
+passwords.each { |password| puts password }
+# AAAAAA
+# AAAAAB
+# AAAAAC
+# ...
+```
+
+Enumerate over all strings from a character set of lengths between 4 and 8:
+
+```ruby
+passwords = Chars.visible.strings_of_length(4..8)
+passwords.each { |password| puts password }
+# AAAA
+# AAAB
+# AAAC
+# ...
+```
+
 ## Requirements
 
 * [ruby](https://www.ruby-lang.org/) >= 2.0.0
@@ -104,13 +155,13 @@ Chars.space.random_string(5..10)
 ### gemspec
 
 ```ruby
-gem.add_dependency 'chars', '~> 0.2'
+gem.add_dependency 'chars', '~> 0.3'
 ```
 
 ### Gemfile
 
 ```ruby
-gem 'chars', '~> 0.2'
+gem 'chars', '~> 0.3'
 ```
 
 ## Crystal

data/benchmarks/compare.rb

@@ -1,6 +1,6 @@
 #!/usr/bin/env ruby
 
-$LOAD_PATH << File.expand_path(File.join(File.dirname(__FILE__),'..','lib'))
+$LOAD_PATH.unshift(File.expand_path(File.join(__dir__,'..','lib')))
 
 require 'chars'
 require 'benchmark'

data/benchmarks/substrings.rb

@@ -0,0 +1,25 @@
+#!/usr/bin/env ruby
+
+$LOAD_PATH.unshift(File.expand_path(File.join(__dir__,'..','lib')))
+
+require 'chars'
+require 'benchmark'
+
+CHARSET = Chars::ALPHA_NUMERIC
+STRING  = File.binread('/usr/bin/openssl')
+
+Benchmark.bm(41) do |b|
+  b.report('Chars::CharSet#each_substring_with_index') do
+    CHARSET.each_substring_with_index(STRING) { |string,index| }
+  end
+
+  b.report('Chars::CharSet#each_substring') do
+    CHARSET.each_substring(STRING) { |string| }
+  end
+
+  (5..20).step(5) do |n|
+    b.report("Chars::CharSet#each_substring (length=#{n})") do
+      CHARSET.strings_in(STRING, :length => n) { |offset,string| }
+    end
+  end
+end

data/lib/chars/char_set.rb

@@ -1,3 +1,5 @@
+require 'chars/string_enumerator'
+
 require 'set'
 
 module Chars
@@ -172,21 +174,30 @@ module Chars
     #
     # Returns a random byte from the {CharSet}.
     #
+    # @param [Random, SecureRandom] random
+    #   The random number generator to use.
+    #
     # @return [Integer]
     #   A random byte value.
     #
-    def random_byte
-      self.entries[rand(self.length)]
+    def random_byte(random: Random)
+      self.entries[random.rand(self.length)]
     end
 
     #
     # Returns a random character from the {CharSet}.
     #
+    # @param [Hash{Symbol => Object}] kwargs
+    #   Additional keyword arguments.
+    #
+    # @option kwargs [Random, SecureRandom] :random
+    #   The random number generator to use.
+    #
     # @return [String]
     #   A random char value.
     #
-    def random_char
-      @chars[random_byte]
+    def random_char(**kwargs)
+      @chars[random_byte(**kwargs)]
     end
 
     #
@@ -195,6 +206,12 @@ module Chars
     # @param [Integer] n
     #   Specifies how many times to pass a random byte to the block.
     #
+    # @param [Hash{Symbol => Object}] kwargs
+    #   Additional keyword arguments.
+    #
+    # @option kwargs [Random, SecureRandom] :random
+    #   The random number generator to use.
+    #
     # @yield [byte]
     #   The block will receive the random bytes.
     #
@@ -204,10 +221,12 @@ module Chars
     # @return [Enumerator]
     #   If no block is given, an enumerator object will be returned.
     #
-    def each_random_byte(n,&block)
-      return enum_for(__method__,n) unless block_given?
+    def each_random_byte(n,**kwargs,&block)
+      return enum_for(__method__,n,**kwargs) unless block_given?
 
-      n.times { yield random_byte }
+      n.times do
+        yield random_byte(**kwargs)
+      end
       return nil
     end
 
@@ -217,6 +236,12 @@ module Chars
     # @param [Integer] n
     #   Specifies how many times to pass a random character to the block.
     #
+    # @param [Hash{Symbol => Object}] kwargs
+    #   Additional keyword arguments.
+    #
+    # @option kwargs [Random, SecureRandom] :random
+    #   The random number generator to use.
+    #
     # @yield [char]
     #   The block will receive the random characters.
     #
@@ -226,10 +251,12 @@ module Chars
     # @return [Enumerator]
     #   If no block is given, an enumerator object will be returned.
     #
-    def each_random_char(n,&block)
-      return enum_for(__method__,n) unless block_given?
+    def each_random_char(n,**kwargs,&block)
+      return enum_for(__method__,n,**kwargs) unless block_given?
 
-      each_random_byte(n) { |byte| yield @chars[byte] }
+      each_random_byte(n,**kwargs) do |byte|
+        yield @chars[byte]
+      end
     end
 
     #
@@ -238,17 +265,24 @@ module Chars
     # @param [Integer, Array, Range] length
     #   The length of the Array of random bytes.
     #
+    # @param [Random, SecureRandom] random
+    #   The random number generator to use.
+    #
     # @return [Array<Integer>]
     #   The randomly selected bytes.
     #
-    def random_bytes(length)
+    def random_bytes(length, random: Random)
       case length
       when Array
-        Array.new(length.sample) { random_byte }
+        Array.new(length.sample(random: random)) do
+          random_byte(random: random)
+        end
       when Range
-        Array.new(rand(length)) { random_byte }
+        Array.new(random.rand(length)) do
+          random_byte(random: random)
+        end
       else
-        Array.new(length) { random_byte }
+        Array.new(length) { random_byte(random: random) }
       end
     end
 
@@ -258,17 +292,20 @@ module Chars
     # @param [Integer, Array, Range] length
     #   The length of the Array of random non-repeating bytes.
     #
+    # @param [Random, SecureRandom] random
+    #   The random number generator to use.
+    #
     # @return [Array<Integer>]
     #   The randomly selected non-repeating bytes.
     #
-    def random_distinct_bytes(length)
-      shuffled_bytes = bytes.shuffle
+    def random_distinct_bytes(length, random: Random)
+      shuffled_bytes = bytes.shuffle(random: random)
 
       case length
       when Array
-        shuffled_bytes[0,length.sample]
+        shuffled_bytes[0,length.sample(random: random)]
       when Range
-        shuffled_bytes[0,rand(length)]
+        shuffled_bytes[0,random.rand(length)]
       else
         shuffled_bytes[0,length]
       end
@@ -280,11 +317,17 @@ module Chars
     # @param [Integer, Array, Range] length
     #   The length of the Array of random characters.
     #
+    # @param [Hash{Symbol => Object}] kwargs
+    #   Additional keyword arguments.
+    #
+    # @option kwargs [Random, SecureRandom] :random
+    #   The random number generator to use.
+    #
     # @return [Array<String>]
     #   The randomly selected characters.
     #
-    def random_chars(length)
-      random_bytes(length).map { |byte| @chars[byte] }
+    def random_chars(length,**kwargs)
+      random_bytes(length,**kwargs).map { |byte| @chars[byte] }
     end
 
     #
@@ -294,13 +337,19 @@ module Chars
     # @param [Integer, Array, Range] length
     #   The length of the String of random characters.
     #
+    # @param [Hash{Symbol => Object}] kwargs
+    #   Additional keyword arguments.
+    #
+    # @option kwargs [Random, SecureRandom] :random
+    #   The random number generator to use.
+    #
     # @return [String]
     #   The String of randomly selected characters.
     #
     # @see random_chars
     #
-    def random_string(length)
-      random_chars(length).join
+    def random_string(length,**kwargs)
+      random_chars(length,**kwargs).join
     end
 
     #
@@ -310,11 +359,17 @@ module Chars
     # @param [Integer, Array, Range] length
     #   The length of the Array of random non-repeating characters.
     #
+    # @param [Hash{Symbol => Object}] kwargs
+    #   Additional keyword arguments.
+    #
+    # @option kwargs [Random, SecureRandom] :random
+    #   The random number generator to use.
+    #
     # @return [Array<Integer>]
     #   The randomly selected non-repeating characters.
     #
-    def random_distinct_chars(length)
-      random_distinct_bytes(length).map { |byte| @chars[byte] }
+    def random_distinct_chars(length,**kwargs)
+      random_distinct_bytes(length,**kwargs).map { |byte| @chars[byte] }
     end
 
     #
@@ -324,13 +379,161 @@ module Chars
     # @param [Integer, Array, Range] length
     #   The length of the String of random non-repeating characters.
     #
+    # @param [Hash{Symbol => Object}] kwargs
+    #   Additional keyword arguments.
+    #
+    # @option kwargs [Random, SecureRandom] :random
+    #   The random number generator to use.
+    #
     # @return [String]
     #   The String of randomly selected non-repeating characters.
     #
     # @see random_distinct_chars
     #
-    def random_distinct_string(length)
-      random_distinct_chars(length).join
+    def random_distinct_string(length,**kwargs)
+      random_distinct_chars(length,**kwargs).join
+    end
+
+    #
+    # Enumerates over all substrings and their indices within the given string,
+    # of minimum length and that are made up of characters from the {CharSet}.
+    #
+    # @param [String] data
+    #   The data to find sub-strings within.
+    #
+    # @param [Integer] min_length
+    #   The minimum length of sub-strings found within the given data.
+    #
+    # @yield [match, index]
+    #   The given block will be passed every matched sub-string and it's index.
+    #
+    # @yield [String] match
+    #   A sub-string containing the characters from the {CharSet}.
+    #
+    # @yield [Integer] index
+    #   The index the sub-string was found at.
+    #
+    # @return [Enumerator]
+    #   If no block is given, an Enumerator object will be returned.
+    #
+    # @since 0.3.0
+    #
+    def each_substring_with_index(data, min_length: 4)
+      unless block_given?
+        return enum_for(__method__,data, min_length: min_length)
+      end
+
+      return if data.size < min_length
+
+      index = 0
+
+      match_start = nil
+      match_end   = nil
+
+      while index < data.size
+        unless match_start
+          if self.include_char?(data[index])
+            match_start = index
+          end
+        else
+          unless self.include_char?(data[index])
+            match_end    = index
+            match_length = (match_end - match_start)
+
+            if match_length >= min_length
+              match = data[match_start,match_length]
+
+              yield match, match_start
+            end
+
+            match_start = match_end = nil
+          end
+        end
+
+        index += 1
+      end
+
+      # yield the remaining match
+      if match_start
+        yield data[match_start, data.size - match_start], match_start
+      end
+    end
+
+    #
+    # Returns an Array of all substrings and their indices within the given
+    # string, of minimum length and that are made up of characters from the
+    # {CharSet}.
+    #
+    # @param [String] data
+    #   The data to find sub-strings within.
+    #
+    # @param [Hash{Symbol => Object}] kwargs
+    #   Keyword arguments for {#each_substring_with_index}.
+    #
+    # @option kwargs [Integer] :min_length
+    #   The minimum length of sub-strings found within the given data.
+    #
+    # @return [Array<(String, Integer)>]
+    #   Tthe array of substrings and their indices within the given `data`.
+    #
+    # @see #each_substring_with_index
+    #
+    # @since 0.3.0
+    #
+    def substrings_with_indexes(data,**kwargs)
+      each_substring_with_index(data,**kwargs).to_a
+    end
+
+    #
+    # Enumerates over all substrings within the given string, of minimum length
+    # and that are made up of characters from the {CharSet}.
+    #
+    # @param [String] data
+    #   The data to find sub-strings within.
+    #
+    # @param [Hash{Symbol => Object}] kwargs
+    #   Keyword arguments for {#each_substring_with_index}.
+    #
+    # @option kwargs [Integer] :min_length
+    #   The minimum length of sub-strings found within the given data.
+    #
+    # @return [Enumerator]
+    #   If no block is given, an Enumerator object will be returned.
+    #
+    # @see #each_substring_with_index
+    #
+    # @since 0.3.0
+    #
+    def each_substring(data,**kwargs)
+      return enum_for(__method__,data,**kwargs) unless block_given?
+
+      each_substring_with_index(data,**kwargs) do |substring,index|
+        yield substring
+      end
+    end
+
+    #
+    # Returns an Array of all substrings within the given string,
+    # of minimum length and that are made up of characters from the {CharSet}.
+    #
+    # @param [String] data
+    #   The data to find sub-strings within.
+    #
+    # @param [Hash{Symbol => Object}] kwargs
+    #   Keyword arguments for {#each_substring_with_index}.
+    #
+    # @option kwargs [Integer] :min_length
+    #   The minimum length of sub-strings found within the given data.
+    #
+    # @see #each_substring
+    #
+    # @return [Array<String>]
+    #   Tthe array of substrings within the given `data`.
+    #
+    # @since 0.3.0
+    #
+    def substrings(data,**kwargs)
+      each_substring(data,**kwargs).to_a
     end
 
     #
@@ -364,49 +567,75 @@ module Chars
     # @return [Array, Hash]
     #   If no block is given, an Array or Hash of sub-strings is returned.
     #
+    # @deprecated
+    #   Use {#each_substring_with_index}, {#substrings_with_index},
+    #   {#each_substring}, or {#substrings} instead.
+    #
     def strings_in(data,options={},&block)
+      kwargs = {min_length: options.fetch(:length,4)}
+
       unless block
         if options[:offsets]
-          found = {}
-          block = lambda { |offset,substring| found[offset] = substring }
+          return Hash[substrings_with_indexes(data,**kwargs)]
         else
-          found = []
-          block = lambda { |substring| found << substring }
+          return substrings(data,**kwargs)
         end
-
-        strings_in(data,options,&block)
-        return found
       end
 
-      min_length = options.fetch(:length,4)
-      return if data.length < min_length
-
-      index = 0
-
-      while index <= (data.length - min_length)
-        if self === data[index,min_length]
-          sub_index = (index + min_length)
-
-          while self.include_char?(data[sub_index,1])
-            sub_index += 1
-          end
-
-          match = data[index...sub_index]
+      case block.arity
+      when 2
+        each_substring_with_index(data,**kwargs,&block)
+      else
+        each_substring(data,**kwargs,&block)
+      end
+    end
 
-          case block.arity
-          when 2
-            yield match, index
-          else
-            yield match
-          end
+    #
+    # Enumerates through every possible string belonging to the {CharSet} and
+    # of the given length.
+    #
+    # @param [Range, Array, Integer] length
+    #   The desired length(s) of each string.
+    #
+    # @yield [string]
+    #   The given block will be passed each sequential string.
+    #
+    # @yieldparam [String] string
+    #   A string belonging to {#char_set} and `length` long.
+    #
+    # @return [Enumerator]
+    #   If no block is given, an Enumerator will be returned.
+    #
+    # @since 0.3.0
+    #
+    def each_string_of_length(length,&block)
+      return enum_for(__method__,length) unless block
 
-          index = sub_index
-        else
-          index += 1
+      case length
+      when Range, Array
+        length.each do |len|
+          StringEnumerator.new(self,len).each(&block)
         end
+      else
+        StringEnumerator.new(self,length).each(&block)
       end
     end
 
+    #
+    # Returns an Enumerator that enumerates through every possible string
+    # belonging to the {CharSEt} and of the given length.
+    #
+    # @param [Range, Array, Integer] length
+    #   The desired length(s) of each string.
+    #
+    # @return [Enumerator]
+    #
+    # @see #each_string
+    #
+    def strings_of_length(length)
+      each_string_of_length(length)
+    end
+
     #
     # Creates a new CharSet object by unioning the {CharSet} with another
     # {CharSet}.