chars 0.1.1 → 0.2.3

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a22fd4d88e24c4f378880de5e324ac4acc4ff197c541baa1b840a8852d420afa
+  data.tar.gz: ad9c7a38b080490366aaf4142eb642224d551da165ddeedfb4fc1fd0e6bf0728
+SHA512:
+  metadata.gz: 5886283079f3bfcf060facf0b0520a51f75066b0301a87750d262e1e4326fad164e541c9580aad1a3f86810430732b2e1933b2ccee26eda6667d0da2aaf2bf00
+  data.tar.gz: 0313dcedc0872cc15f84804bdea985bf726040b48d48018084800c8e07f4224267b5802df4da9d68c5ce79ff0239e4af7138db522fa8523647251524d51e6ba1

data/.document

@@ -0,0 +1,4 @@
+lib/**/*.rb
+- 
+ChangeLog.md
+LICENSE.txt

data/.github/workflows/ruby.yml

@@ -0,0 +1,28 @@
+name: CI
+
+on: [ push, pull_request ]
+
+jobs:
+  tests:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby:
+          - 2.4
+          - 2.5
+          - 2.6
+          - 2.7
+          - 3.0
+          - jruby
+    name: Ruby ${{ matrix.ruby }}
+    steps:
+      - uses: actions/checkout@v2
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+      - name: Install dependencies
+        run: bundle install --jobs 4 --retry 3
+      - name: Run tests
+        run: bundle exec rake test

data/.gitignore

@@ -0,0 +1,8 @@
+/Gemfile.lock
+/doc/
+/pkg/
+/vendor/bundle
+.DS_Store
+.yardoc
+*.swp
+*~

data/.rspec

@@ -0,0 +1 @@
+--colour --format documentation

data/.yardopts

@@ -0,0 +1 @@
+--markup markdown --title 'Chars Documentation' --protected --quiet

data/ChangeLog.md

@@ -0,0 +1,68 @@
+### 0.2.3 / 2020-12-25
+
+* Change {Chars::CharSet} to inherit from `Set`, instead of `SortedSet`.
+
+### 0.2.2 / 2012-05-28
+
+* {Chars::CharSet#initialize} now raises a TypeError when given arguments
+  that were neither a `String`, `Integer` or `Enumerable`.
+* Allow {Chars::CharSet#strings_in} to yield results as they are found.
+* Improved the performance of {Chars::CharSet#strings_in} when operating on
+  small Strings.
+* Replaced ore-tasks with
+  [rubygems-tasks](https://github.com/postmodern/rubygems-tasks#readme).
+
+### 0.2.1 / 2011-06-22
+
+* Added {Chars::CharSet.[]}
+* Added {Chars::CharSet#<<}.
+* Added {Chars::CharSet#byte_to_char}.
+* Added {Chars::CharSet#char_to_byte}.
+* Added a cache of characters of the bytes within {Chars::CharSet}.
+* Use `String#each_char` to distinguish Unicode from ASCII.
+
+### 0.2.0 / 2010-10-27
+
+* Make sure all enumerable methods in {Chars::CharSet} return an
+  `Enumerator` object if no block is given.
+
+### 0.1.2 / 2009-09-21
+
+* Require Hoe >= 2.3.3.
+* Require YARD >= 0.2.3.5.
+* Require RSpec >= 1.2.8.
+* Added Chars.visibile and Chars::VISIBLE (thanks flatline).
+* Added CharSet#random_distinct_bytes, CharSet#random_distinct_chars,
+  and CharSet#random_distinct_string (thanks flatline).
+* Use 'hoe/signing' for signed RubyGems.
+* Moved to YARD based documentation.
+* All specs now pass on JRuby 1.3.1.
+
+### 0.1.1 / 2009-04-01
+
+* Renamed CharSet#=~ to CharSet#===.
+* Added an alias from CharSet#=~ to CharSet#===.
+
+### 0.1.0 / 2009-03-16
+
+* Initial release.
+* Provides character sets for:
+  * Numeric
+  * Octal
+  * Uppercase Hexadecimal
+  * Lowercase Hexadecimal
+  * Hexadecimal
+  * Uppercase Alpha
+  * Lowercase Alpha
+  * Alpha
+  * Alpha-numeric
+  * Punctuation
+  * Symbols
+  * Space
+  * Printable
+  * Control
+  * ASCII
+* Provides convenience methods for testing wether a String or Integer
+  belongs to a certain character set.
+* Supports random text generation using specific character sets.
+

data/Gemfile

@@ -0,0 +1,11 @@
+source 'https://rubygems.org'
+
+gemspec
+
+group :development do
+  gem 'rake'
+  gem 'rubygems-tasks', '~> 0.2'
+  gem 'rspec',          '~> 3.0'
+  gem 'kramdown'
+  gem 'yard',           '~> 0.9'
+end

data/LICENSE.txt

@@ -0,0 +1,22 @@
+(The MIT License)
+
+Copyright (c) 2009-2012 Hal Brodigan
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,98 @@
+# Chars
+
+* [Source](https://github.com/postmodern/chars#readme)
+* [Issues](https://github.com/postmodern/chars/issues)
+* [Documentation](http://rubydoc.info/gems/chars)
+* [Email](mailto:postmodern.mod3 at gmail.com)
+
+## Description
+
+Chars is a Ruby library for working with various character sets,
+recognizing text and generating random text from specific character sets.
+
+## Features
+
+* Provides character sets for:
+  * Numeric ('0' - '9')
+  * Octal ('0' - '7')
+  * Uppercase Hexadecimal ('0' - '9', 'A' - 'F')
+  * Lowercase Hexadecimal ('0' - '9', 'a' - 'f')
+  * Hexadecimal ('0' - '9', 'a' - 'f', 'A' - 'F')
+  * Uppercase Alpha ('A' - 'Z')
+  * Lowercase Alpha ('a' - 'z')
+  * Alpha ('a' - 'z', 'A' - 'Z')
+  * Alpha-numeric ('0' - '9', 'a' - 'z', 'A' - 'Z')
+  * Punctuation (' ', '\'', '"', '`', ',', ';', ':', '~', '-', '(', ')',
+    '[', ']', '{', '}', '.', '?', '!')
+  * Symbols (' ', '\'', '"', '`', ',', ';', ':', '~', '-', '(', ')',
+    '[', ']', '{', '}', '.', '?', '!', '@', '#', '$', '%', '^', '&', '*',
+    '_', '+', '=', '|', '\\', '<', '>', '/')
+  * Space (' ', '\f', '\n', '\r', '\t', '\v')
+  * Visible ('0' - '9', 'a' - 'z', 'A' - 'Z', '\'', '"', '`', ',',
+    ';', ':', '~', '-', '(', ')', '[', ']', '{', '}', '.', '?', '!', '@',
+    '#', '$', '%', '^', '&', '*', '_', '+', '=', '|', '\\', '<', '>', '/',)
+  * Printable ('0' - '9', 'a' - 'z', 'A' - 'Z', ' ', '\'', '"', '`', ',',
+    ';', ':', '~', '-', '(', ')', '[', ']', '{', '}', '.', '?', '!', '@',
+    '#', '$', '%', '^', '&', '*', '_', '+', '=', '|', '\\', '<', '>', '/',
+    '\f', '\n', '\r', '\t', '\v')
+  * Control ('\x00' - '\x1f', '\x7f')
+  * Signed ASCII ('\x00' - '\x7f')
+  * ASCII ('\x00' - '\xff')
+
+## Examples
+
+Determine whether a byte belongs to a character set:
+
+    0x41.alpha?
+    # => true
+
+Determine whether a String belongs to a character set:
+
+    "22e1c0".hex?
+    # => true
+
+Find all sub-strings that belong to a character set within a String:
+
+    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:
+
+    Chars.all.random_char
+    # => "\x94"
+
+Return a random Array of characters from the alpha-numeric character set:
+
+    Chars.alpha_numeric.random_chars(10)
+    # => ["Q", "N", "S", "4", "x", "z", "3", "M", "F", "F"]
+
+Return a random Array of a random length of unique characters from the
+visible character set:
+
+    Chars.visible.random_distinct_chars(1..10)
+    # => ["S", "l", "o", "8", "'", "q"]
+
+Return a random String from the set of all characters:
+
+    Chars.all.random_string(10)
+    # => "\xc2h\xad\xccm7\x1e6J\x13"
+
+Return a random String with a random length between 5 and 10, from the
+set of space characters:
+
+    Chars.space.random_string(5..10)
+    # => "\r\v\n\t\n\f"
+
+## Requirements
+
+* [ruby](http://www.ruby-lang.org/) >= 1.8.7
+
+## Install
+
+    $ sudo gem install chars
+
+## License
+
+See {file:LICENSE.txt} for license information.
+

data/Rakefile

@@ -1,14 +1,12 @@
-# -*- ruby -*-
-
 require 'rubygems'
-require 'hoe'
-require './tasks/spec.rb'
-require './lib/chars/version.rb'
 
-Hoe.new('chars', Chars::VERSION) do |p|
-  p.rubyforge_name = 'chars'
-  p.developer('Postmodern','postmodern.mod3@gmail.com')
-  p.remote_rdoc_dir = '/'
-end
+require 'rubygems/tasks'
+Gem::Tasks.new
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new
+task :test => :spec
+task :default => :spec
 
-# vim: syntax=Ruby
+require 'yard'
+YARD::Rake::YardocTask.new  

data/benchmarks/compare.rb

@@ -0,0 +1,16 @@
+#!/usr/bin/env ruby
+
+$LOAD_PATH << File.expand_path(File.join(File.dirname(__FILE__),'..','lib'))
+
+require 'chars'
+require 'benchmark'
+
+CHARSET = Chars::ALPHA_NUMERIC
+N       = 1_000_000
+STRING  = ('A' * N) + '!'
+ENUM    = (['A', 0x42] * (N / 2)) << '!'
+
+Benchmark.bm(12) do |b|
+  b.report('String')     { CHARSET === STRING }
+  b.report('Enumerable') { CHARSET === ENUM }
+end

data/benchmarks/strings_in.rb

@@ -0,0 +1,23 @@
+#!/usr/bin/env ruby
+
+$LOAD_PATH << File.expand_path(File.join(File.dirname(__FILE__),'..','lib'))
+
+require 'chars'
+require 'benchmark'
+
+CHARSET = Chars::ALPHA_NUMERIC
+STRING  = File.open('/usr/bin/openssl','rb') do |file|
+            file.read
+          end
+
+Benchmark.bm(24) do |b|
+  b.report('strings_in') do
+    CHARSET.strings_in(STRING) { |offset,string| }
+  end
+
+  (5..20).step(5) do |n|
+    b.report("strings_in (length=#{n})") do
+      CHARSET.strings_in(STRING, :length => n) { |offset,string| }
+    end
+  end
+end

data/chars.gemspec

@@ -0,0 +1,60 @@
+# encoding: utf-8
+
+require 'yaml'
+
+Gem::Specification.new do |gem|
+  gemspec = YAML.load_file('gemspec.yml')
+
+  gem.name    = gemspec.fetch('name')
+  gem.version = gemspec.fetch('version') do
+                  lib_dir = File.join(File.dirname(__FILE__),'lib')
+                  $LOAD_PATH << lib_dir unless $LOAD_PATH.include?(lib_dir)
+
+                  require 'chars/version'
+                  Chars::VERSION
+                end
+
+  gem.summary     = gemspec['summary']
+  gem.description = gemspec['description']
+  gem.licenses    = Array(gemspec['license'])
+  gem.authors     = Array(gemspec['authors'])
+  gem.email       = gemspec['email']
+  gem.homepage    = gemspec['homepage']
+
+  glob = lambda { |patterns| gem.files & Dir[*patterns] }
+
+  gem.files = `git ls-files`.split($/)
+  gem.files = glob[gemspec['files']] if gemspec['files']
+
+  gem.executables = gemspec.fetch('executables') do
+    glob['bin/*'].map { |path| File.basename(path) }
+  end
+  gem.default_executable = gem.executables.first if Gem::VERSION < '1.7.'
+
+  gem.extensions       = glob[gemspec['extensions'] || 'ext/**/extconf.rb']
+  gem.test_files       = glob[gemspec['test_files'] || '{test/{**/}*_test.rb']
+  gem.extra_rdoc_files = glob[gemspec['extra_doc_files'] || '*.{txt,md}']
+
+  gem.require_paths = Array(gemspec.fetch('require_paths') {
+    %w[ext lib].select { |dir| File.directory?(dir) }
+  })
+
+  gem.requirements              = gemspec['requirements']
+  gem.required_ruby_version     = gemspec['required_ruby_version']
+  gem.required_rubygems_version = gemspec['required_rubygems_version']
+  gem.post_install_message      = gemspec['post_install_message']
+
+  split = lambda { |string| string.split(/,\s*/) }
+
+  if gemspec['dependencies']
+    gemspec['dependencies'].each do |name,versions|
+      gem.add_dependency(name,split[versions])
+    end
+  end
+
+  if gemspec['development_dependencies']
+    gemspec['development_dependencies'].each do |name,versions|
+      gem.add_development_dependency(name,split[versions])
+    end
+  end
+end

data/gemspec.yml

@@ -0,0 +1,16 @@
+name: chars
+summary: A Ruby library for working with various character sets
+description:
+  Chars is a Ruby library for working with various character sets,
+  recognizing text and generating random text from specific character sets.
+
+license: MIT
+homepage: https://github.com/postmodern/chars#readme
+authors: Postmodern
+email: postmodern.mod3@gmail.com
+has_yard: true
+
+required_ruby_version: ">= 1.8.7"
+
+development_dependencies:
+  bundler: ~> 2.0

data/lib/chars/char_set.rb

@@ -1,25 +1,75 @@
 require 'set'
 
 module Chars
-  class CharSet < SortedSet
+  class CharSet < Set
 
     #
-    # Creates a new CharSet object with the given _chars_.
+    # Creates a new CharSet object.
     #
-    def initialize(*chars)
+    # @param [Array<String, Integer, Enumerable>] arguments
+    #   The chars for the CharSet.
+    #
+    # @raise [TypeError]
+    #   One of the arguments was not a {String}, {Integer} or `Enumerable`.
+    #
+    def initialize(*arguments)
       super()
 
-      merge_chars = lambda { |element|
-        if element.kind_of?(String)
-          element.each_byte(&merge_chars)
-        elsif element.kind_of?(Integer)
-          self << element
-        elsif element.kind_of?(Enumerable)
-          element.each(&merge_chars)
+      @chars = Hash.new { |hash,key| hash[key] = byte_to_char(key) }
+
+      arguments.each do |subset|
+        case subset
+        when String, Integer
+          self << subset
+        when Enumerable
+          subset.each { |char| self << char }
+        else
+          raise(TypeError,"arguments must be a String, Integer or Enumerable")
+        end
+      end
+    end
+    
+    #
+    # Creates a new character set.
+    #
+    # @see #initialize
+    #
+    # @since 0.2.1
+    #
+    def self.[](*arguments)
+      new(*arguments)
+    end
+
+    #
+    # Adds a character to the set.
+    #
+    # @param [String, Integer] other
+    #   The character(s) or byte to add.
+    #
+    # @return [CharSet]
+    #   The modified character set.
+    #
+    # @raise [TypeError]
+    #   The argument was not a {String} or {Integer}.
+    #
+    # @since 0.2.1
+    #
+    def <<(other)
+      case other
+      when String
+        other.each_char do |char|
+          byte = char_to_byte(char)
+
+          @chars[byte] = char
+          super(byte)
         end
-      }
 
-      merge_chars.call(chars)
+        return self
+      when Integer
+        super(other)
+      else
+        raise(TypeError,"can only append Strings and Integers")
+      end
     end
 
     alias include_byte? include?
@@ -29,181 +79,361 @@ module Chars
     alias map_bytes map
 
     #
-    # Returns +true+ if the character set includes the specified _char_,
-    # returns +false+ otherwise.
+    # Determines if a character is contained within the character set.
+    #
+    # @param [String] char
+    #   The character to search for.
+    #
+    # @return [Boolean]
+    #   Specifies whether the character is contained within the
+    #   character set.
     #
     def include_char?(char)
-      return false unless char.respond_to?(:each_byte)
-
-      char.each_byte do |b|
-        return include?(b)
+      unless char.empty?
+        @chars.has_value?(char) || include_byte?(char_to_byte(char))
+      else
+        false
       end
     end
 
     #
-    # Returns all the characters within the character set as Strings.
+    # The characters within the character set.
+    #
+    # @return [Array<String>]
+    #   All the characters within the character set.
     #
     def chars
-      map { |b| b.chr }
+      map { |byte| @chars[byte] }
     end
 
     #
-    # Iterates over every character within the character set, passing
-    # each to the given _block_.
+    # Iterates over every character within the character set.
+    #
+    # @yield [char]
+    #   If a block is given, it will be passed each character in the
+    #   character set.
     #
-    def each_char(&block)
-      each { |b| block.call(b.chr) } if block
+    # @yieldparam [String] char
+    #   Each character in the character set.
+    #
+    # @return [Enumerator]
+    #   If no block is given, an enumerator object will be returned.
+    #
+    def each_char
+      return enum_for(__method__) unless block_given?
+
+      each { |byte| yield @chars[byte] }
     end
 
     #
-    # Selects an Array of characters from the character set that match
-    # the given _block_.
+    # Selects characters from the character set.
+    #
+    # @yield [char]
+    #   If a block is given, it will be used to select the characters
+    #   from the character set.
+    #
+    # @yieldparam [String] char
+    #   The character to select or reject.
+    #
+    # @return [Array<String>]
+    #   The selected characters from the character set.
     #
     def select_chars(&block)
-      chars.select(&block)
+      each_char.select(&block)
     end
 
     #
-    # Maps the characters of the character set using the given _block_.
+    # Maps the characters of the character set.
+    #
+    # @yield [char]
+    #   The given block will be used to transform the characters within
+    #   the character set.
+    #
+    # @yieldparam [String] char
+    #   Each character in the character set.
+    #
+    # @return [Array<String>]
+    #   The mapped characters of the character set.
     #
     def map_chars(&block)
-      chars.map(&block)
+      each_char.map(&block)
     end
 
     #
-    # Returns a random byte from the character set.
+    # @return [Integer]
+    #   A random byte from the character set.
     #
     def random_byte
       self.entries[rand(self.length)]
     end
 
     #
-    # Returns a random char from the character set.
+    # @return [String]
+    #   A random char from the character set.
     #
     def random_char
-      random_byte.chr
+      @chars[random_byte]
     end
 
     #
-    # Pass a random byte to the specified _block_, _n_ times.
+    # Pass random bytes to a given block.
+    #
+    # @param [Integer] n
+    #   Specifies how many times to pass a random byte to the block.
+    #
+    # @yield [byte]
+    #   The block will receive the random bytes.
+    #
+    # @yieldparam [Integer] byte
+    #   The random byte from the character set.
+    #
+    # @return [Enumerator]
+    #   If no block is given, an enumerator object will be returned.
     #
     def each_random_byte(n,&block)
-      n.times { block.call(random_byte) }
+      return enum_for(__method__,n) unless block_given?
+
+      n.times { yield random_byte }
+      return nil
     end
 
     #
-    # Pass a random character to the specified _block_, _n_ times.
+    # Pass random characters to a given block.
+    #
+    # @param [Integer] n
+    #   Specifies how many times to pass a random character to the block.
+    #
+    # @yield [char]
+    #   The block will receive the random characters.
+    #
+    # @yieldparam [String] char
+    #   The random character from the character set.
+    #
+    # @return [Enumerator]
+    #   If no block is given, an enumerator object will be returned.
     #
     def each_random_char(n,&block)
-      each_random_byte(n) { |b| block.call(b.chr) }
+      return enum_for(__method__,n) unless block_given?
+
+      each_random_byte(n) { |byte| yield @chars[byte] }
     end
 
     #
-    # Returns an Array of the specified _length_ containing
-    # random bytes from the character set. The specified _length_ may
-    # be an Integer, Array or a Range of lengths.
+    # Creates an Array of random bytes from the character set.
+    #
+    # @param [Integer, Array, Range] length
+    #   The length of the Array of random bytes.
+    #
+    # @return [Array<Integer>]
+    #   The randomly selected bytes.
     #
     def random_bytes(length)
       if (length.kind_of?(Array) || length.kind_of?(Range))
-        return Array.new(length.sort_by { rand }.first) { random_byte }
+        Array.new(length.sort_by { rand }.first) { random_byte }
       else
-        return Array.new(length) { random_byte }
+        Array.new(length) { random_byte }
       end
     end
 
     #
-    # Returns an Array of the specified _length_ containing
-    # random characters from the character set. The specified _length_
-    # may be an Integer, Array or a Range of lengths.
+    # Creates an Array of random non-repeating bytes from the character set.
+    #
+    # @param [Integer, Array, Range] length
+    #   The length of the Array of random non-repeating bytes.
+    #
+    # @return [Array<Integer>]
+    #   The randomly selected non-repeating bytes.
+    #
+    def random_distinct_bytes(length)
+      if (length.kind_of?(Array) || length.kind_of?(Range))
+        self.entries.sort_by { rand }.slice(0...(length.sort_by { rand }.first))
+      else
+        self.entries.sort_by { rand }.slice(0...length) 
+      end
+    end
+
+    #
+    # Creates an Array of random characters from the character set.
+    #
+    # @param [Integer, Array, Range] length
+    #   The length of the Array of random characters.
+    #
+    # @return [Array<String>]
+    #   The randomly selected characters.
     #
     def random_chars(length)
-      random_bytes(length).map { |b| b.chr }
+      random_bytes(length).map { |byte| @chars[byte] }
     end
 
     #
-    # Returns a String of the specified _length_ containing
-    # random characters from the character set.
+    # Creates a String containing randomly selected characters from the
+    # character set.
+    #
+    # @param [Integer, Array, Range] length
+    #   The length of the String of random characters.
+    #
+    # @return [String]
+    #   The String of randomly selected characters.
+    #
+    # @see random_chars
     #
     def random_string(length)
       random_chars(length).join
     end
 
     #
-    # Finds sub-strings within the specified _data_ that are part of the
-    # character set, using the given _options_.
+    # Creates an Array of random non-repeating characters from the
+    # character set.
+    #
+    # @param [Integer, Array, Range] length
+    #   The length of the Array of random non-repeating characters.
     #
-    # _options_ may contain the following keys:
-    # <tt>:length</tt>:: The minimum length of matching sub-strings
-    #                    within the _data_. Defaults to 4, if not
-    #                    specified.
-    # <tt>:offsets</tt>:: Specifies wether to return a Hash of the
-    #                     offsets within the _data_ and the matched
-    #                     sub-strings. If not specified a simple
-    #                     Array will be returned of the matched
-    #                     sub-strings.
+    # @return [Array<Integer>]
+    #   The randomly selected non-repeating characters.
     #
-    def strings_in(data,options={})
-      min_length = (options[:length] || 4)
+    def random_distinct_chars(length)
+      random_distinct_bytes(length).map { |byte| @chars[byte] }
+    end
 
-      if options[:offsets]
-        found = {}
-        found_substring = lambda { |offset,substring|
-          found[offset] = substring
-        }
-      else
-        found = []
-        found_substring = lambda { |offset,substring|
-          found << substring
-        }
+    #
+    # Creates a String containing randomly selected non-repeating
+    # characters from the character set.
+    #
+    # @param [Integer, Array, Range] length
+    #   The length of the String of random non-repeating characters.
+    #
+    # @return [String]
+    #   The String of randomly selected non-repeating characters.
+    #
+    # @see random_distinct_chars
+    #
+    def random_distinct_string(length)
+      random_distinct_chars(length).join
+    end
+
+    #
+    # Finds sub-strings within given data that are made of characters within
+    # the character set.
+    #
+    # @param [String] data
+    #   The data to find sub-strings within.
+    #
+    # @param [Hash] options
+    #   Additional options.
+    #
+    # @option options [Integer] :length (4)
+    #   The minimum length of sub-strings found within the given data.
+    #
+    # @option options [Boolean] :offsets (false)
+    #   Specifies whether to return a Hash of offsets and matched
+    #   sub-strings within the data, or to just return the matched
+    #   sub-strings themselves.
+    #
+    # @yield [match,(index)]
+    #   The given block will be passed every matched sub-string, and the
+    #   optional index.
+    #
+    # @yield [String] match
+    #   A sub-string containing the characters from the character set.
+    #
+    # @yield [Integer] index
+    #   The index the sub-string was found at.
+    #
+    # @return [Array, Hash]
+    #   If no block is given, an Array or Hash of sub-strings is returned.
+    #
+    def strings_in(data,options={},&block)
+      unless block
+        if options[:offsets]
+          found = {}
+          block = lambda { |offset,substring| found[offset] = substring }
+        else
+          found = []
+          block = lambda { |substring| found << substring }
+        end
+
+        strings_in(data,options,&block)
+        return found
       end
 
-      return found if data.length < min_length
+      min_length = options.fetch(:length,4)
+      return if data.length < min_length
 
       index = 0
 
       while index <= (data.length - min_length)
-        if self === data[index...(index + min_length)]
+        if self === data[index,min_length]
           sub_index = (index + min_length)
 
-          while self.include_char?(data[sub_index..sub_index])
+          while self.include_char?(data[sub_index,1])
             sub_index += 1
           end
 
-          found_substring.call(index,data[index...sub_index])
+          match = data[index...sub_index]
+
+          case block.arity
+          when 2
+            yield match, index
+          else
+            yield match
+          end
+
           index = sub_index
         else
           index += 1
         end
       end
-
-      return found
     end
 
     #
-    # Creates a new CharSet object containing the both the characters
-    # of the character set and the specified _other_set_.
+    # Creates a new CharSet object by unioning the character set with
+    # another character set.
+    #
+    # @param [CharSet, Array, Range] set
+    #   The other character set to union with.
     #
-    def |(other_set)
-      super(CharSet.new(other_set))
+    # @return [CharSet]
+    #   The unioned character sets.
+    #
+    def |(set)
+      set = CharSet.new(set) unless set.kind_of?(CharSet)
+
+      return super(set)
     end
 
     alias + |
 
     #
-    # Returns +true+ if all of the bytes within the specified _string_
-    # are included in the character set, returns +false+ otherwise.
+    # Compares the bytes within a given string with the bytes of the
+    # character set.
     #
+    # @param [String, Enumerable] other
+    #   The string to compare with the character set.
+    #
+    # @return [Boolean]
+    #   Specifies whether all of the bytes within the given string are
+    #   included in the character set.
+    #
+    # @example
     #   Chars.alpha === "hello"
     #   # => true
     #
-    def ===(string)
-      return false unless string.respond_to?(:each_byte)
-
-      string.each_byte do |b|
-        return false unless include?(b)
+    def ===(other)
+      case other
+      when String
+        other.each_char.all? { |char| include_char?(char) }
+      when Enumerable
+        other.all? do |element|
+          case element
+          when String
+            include_char?(element)
+          when Integer
+            include_byte?(element)
+          end
+        end
+      else
+        false
       end
-
-      return true
     end
 
     alias =~ ===
@@ -211,20 +441,87 @@ module Chars
     #
     # Inspects the character set.
     #
+    # @return [String]
+    #   The inspected character set.
+    #
     def inspect
-      "#<#{self.class.name}: {" + map { |b|
-        case b
+      "#<#{self.class.name}: {" + map { |byte|
+        case byte
         when (0x07..0x0d), (0x20..0x7e)
-          b.chr.dump
+          @chars[byte].dump
         when 0x00
           # sly hack to make char-sets more friendly
           # to us C programmers
           '"\0"'
         else
-          "0x%02x" % b
+          "0x%02x" % byte
         end
       }.join(', ') + "}>"
     end
 
+    protected
+
+    if RUBY_VERSION > '1.9.'
+      #
+      # Converts a byte to a character.
+      #
+      # @param [Integer] byte
+      #   The byte to convert.
+      #
+      # @return [String]
+      #   The character.
+      #
+      # @since 0.2.1
+      #
+      def byte_to_char(byte)
+        byte.chr(Encoding::UTF_8)
+      end
+
+      #
+      # Converts a character to a byte.
+      #
+      # @param [String] char
+      #   The character to convert.
+      #
+      # @return [Integer]
+      #   The byte.
+      #
+      # @since 0.2.1
+      #
+      def char_to_byte(char)
+        char.ord
+      end
+    else
+      #
+      # Converts a byte to a character.
+      #
+      # @param [Integer] byte
+      #   The byte to convert.
+      #
+      # @return [String]
+      #   The character.
+      #
+      # @since 0.2.1
+      #
+      def byte_to_char(byte)
+        byte.chr
+      end
+
+      #
+      # Converts a character to a byte.
+      #
+      # @param [String] char
+      #   The character to convert.
+      #
+      # @return [Integer]
+      #   The byte.
+      #
+      # @since 0.2.1
+      #
+      def char_to_byte(char)
+        char[0]
+      end
+    end
+
   end
 end