chars 0.2.4 → 0.3.1

data/lib/chars/char_set.rb

@@ -1,3 +1,5 @@
+require 'chars/string_enumerator'
+
 require 'set'
 
 module Chars
@@ -42,6 +44,12 @@ module Chars
     #
     # Creates a new {CharSet}.
     #
+    # @param [Array<String, Integer, Enumerable>] arguments
+    #   The chars for the CharSet.
+    #
+    # @return [CharSet]
+    #   The new character set.
+    #
     # @see #initialize
     #
     # @since 0.2.1
@@ -172,21 +180,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 +212,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 +227,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 +242,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 +257,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 +271,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 +298,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 +323,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 +343,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 +365,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 +385,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 +573,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}.

data/lib/chars/chars.rb

@@ -6,6 +6,11 @@ module Chars
   # The numeric decimal character set
   NUMERIC = CharSet['0'..'9']
 
+  # @see NUMERIC
+  #
+  # @since 0.3.0
+  DIGITS = NUMERIC
+
   # The octal character set
   OCTAL = CharSet['0'..'7']
 
@@ -31,7 +36,7 @@ module Chars
   ALPHA_NUMERIC = ALPHA | NUMERIC
 
   # The punctuation character set
-  PUNCTUATION = CharSet[' ', '\'', '"', '`', ',', ';', ':', '~', '-',
+  PUNCTUATION = CharSet['\'', '"', '`', ',', ';', ':', '~', '-',
                         '(', ')', '[', ']', '{', '}', '.', '?', '!']
 
   # The symbolic character set
@@ -41,7 +46,11 @@ module Chars
   ]
 
   # The space character set
-  SPACE = CharSet[' ', "\f", "\n", "\r", "\t", "\v"]
+  #
+  # @since 0.3.0
+  WHITESPACE = CharSet[' ', "\f", "\n", "\r", "\t", "\v"]
+
+  SPACE = WHITESPACE
 
   # The set of printable characters (not including spaces)
   VISIBLE = ALPHA_NUMERIC | CharSet[
@@ -51,7 +60,7 @@ module Chars
   ]
   
   # The set of printable characters (including spaces)
-  PRINTABLE = ALPHA_NUMERIC | PUNCTUATION | SYMBOLS | SPACE
+  PRINTABLE = ALPHA_NUMERIC | PUNCTUATION | SYMBOLS | CharSet[' ']
 
   # The control-char character set
   CONTROL = CharSet[0..0x1f, 0x7f]
@@ -74,6 +83,20 @@ module Chars
     NUMERIC
   end
 
+  #
+  # Alias for {numeric}.
+  #
+  # @return [CharSet]
+  #   The decimal-digit character set.
+  #
+  # @see numeric
+  #
+  # @since 0.3.0
+  #
+  def self.digits
+    numeric
+  end
+
   #
   # The octal-digit character set.
   #
@@ -195,15 +218,28 @@ module Chars
   end
 
   #
-  # The white-space character set.
+  # The whitespace character set.
   #
   # @return [CharSet]
-  #   The white-space character set.
+  #   The whitespace character set.
   #
   # @see SPACE
   #
+  # @since 0.3.0
+  #
+  def self.whitespace
+    WHITESPACE
+  end
+
+  #
+  # The whitespace character set.
+  #
+  # @return [CharSet]
+  #
+  # @see #whitespace
+  #
   def self.space
-    SPACE
+    whitespace
   end
 
   #

data/lib/chars/string_enumerator.rb

@@ -0,0 +1,98 @@
+module Chars
+  #
+  # Enumerates through every possible string belonging to a character set and
+  # of a given length.
+  #
+  # @api private
+  #
+  # @since 0.3.0
+  #
+  class StringEnumerator
+
+    include Enumerable
+
+    # The character set to generate the strings from.
+    #
+    # @return [CharSet]
+    attr_reader :char_set
+
+    # The desired length of each string.
+    #
+    # @return [Integer]
+    attr_reader :length
+
+    #
+    # Initializes the string enumerator.
+    #
+    # @param [Chars::CharSet] char_set
+    #   The character set to generate the strings from.
+    #
+    # @param [Integer] length
+    #   The desired length of each string.
+    #
+    def initialize(char_set,length)
+      @char_set = char_set
+      @length   = length
+    end
+
+    #
+    # Enumerates through every possible string belonging to {#char_set} and 
+    # {#length} long.
+    #
+    # @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.
+    #
+    def each
+      return enum_for(__method__) unless block_given?
+
+      if @char_set.empty?
+        return
+      elsif @length == 0
+        yield ""
+        return
+      end
+
+      chars      = char_set.chars
+      first_char = chars.first
+      last_char  = chars.last
+
+      next_char = {}
+
+      chars.each_cons(2) do |c1,c2|
+        next_char[c1] = c2
+      end
+
+      string = String.new(first_char * @length)
+
+      last_index = @length - 1
+
+      loop do
+        chars.each do |c|
+          string[last_index] = c
+
+          yield string.dup
+        end
+
+        last_index.downto(0) do |i|
+          if string[i] == last_char
+            string[i] = first_char
+
+            if i == 0
+              return
+            end
+          else
+            string[i] = next_char[string[i]]
+            break
+          end
+        end
+      end
+    end
+
+  end
+end

data/lib/chars/version.rb

@@ -1,4 +1,4 @@
 module Chars
   # chars version
-  VERSION = '0.2.4'
+  VERSION = '0.3.1'
 end