Class: Chars::CharSet

Inherits:
Set
  • Object
show all
Defined in:
lib/chars/char_set.rb

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(*arguments) ⇒ CharSet

Creates a new CharSet object.

Parameters:

  • arguments (Array<String, Integer, Enumerable>) —

    The chars for the CharSet.

Raises:

  • (TypeError) —

    One of the arguments was not a String, Integer or Enumerable.



17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
 
# File 'lib/chars/char_set.rb', line 17

def initialize(*arguments)
  super()

  @chars = Hash.new { |hash,key| hash[key] = key.chr(Encoding::UTF_8) }

  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

Class Method Details

.[](*arguments) ⇒ Object

Creates a new Chars::CharSet.

See Also:

Since:

  • 0.2.1



51
52
53
 
# File 'lib/chars/char_set.rb', line 51

def self.[](*arguments)
  new(*arguments)
end

Instance Method Details

#<<(other) ⇒ CharSet

Adds a character to the set.

Parameters:

Returns:

  • (CharSet) —

    The modified character set.

Raises:

Since:

  • 0.2.1



69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
 
# File 'lib/chars/char_set.rb', line 69

def <<(other)
  case other
  when String
    other.each_char do |char|
      byte = char.ord

      @chars[byte] = char
      super(byte)
    end

    return self
  when Integer
    super(other)
  else
    raise(TypeError,"can only append Strings and Integers")
  end
end

#===(other) ⇒ Boolean Also known as: =~

Compares the bytes within a given string with the bytes of the Chars::CharSet.

Examples:

Chars.alpha === "hello"
# => true

Parameters:

Returns:

  • (Boolean) —

    Specifies whether all of the bytes within the given string are included in the Chars::CharSet.



672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
 
# File 'lib/chars/char_set.rb', line 672

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
end

#chars ⇒ Array<String>

The characters within the Chars::CharSet.

Returns:



117
118
119
 
# File 'lib/chars/char_set.rb', line 117

def chars
  map { |byte| @chars[byte] }
end

#each_char {|char| ... } ⇒ Enumerator

Iterates over every character within the Chars::CharSet.

Yields:

  • (char) —

    If a block is given, it will be passed each character in the Chars::CharSet.

Yield Parameters:

Returns:

  • (Enumerator) —

    If no block is given, an enumerator object will be returned.



134
135
136
137
138
 
# File 'lib/chars/char_set.rb', line 134

def each_char
  return enum_for(__method__) unless block_given?

  each { |byte| yield @chars[byte] }
end

#each_random_byte(n, **kwargs) {|byte| ... } ⇒ Enumerator

Pass random bytes to a given block.

Parameters:

  • n (Integer) —

    Specifies how many times to pass a random byte to the block.

  • kwargs (Hash{Symbol => Object}) —

    Additional keyword arguments.

Options Hash (**kwargs):

  • :random (Random, SecureRandom) —

    The random number generator to use.

Yields:

  • (byte) —

    The block will receive the random bytes.

Yield Parameters:

Returns:

  • (Enumerator) —

    If no block is given, an enumerator object will be returned.



224
225
226
227
228
229
230
231
 
# File 'lib/chars/char_set.rb', line 224

def each_random_byte(n,**kwargs,&block)
  return enum_for(__method__,n,**kwargs) unless block_given?

  n.times do
    yield random_byte(**kwargs)
  end
  return nil
end

#each_random_char(n, **kwargs) {|char| ... } ⇒ Enumerator

Pass random characters to a given block.

Parameters:

  • n (Integer) —

    Specifies how many times to pass a random character to the block.

  • kwargs (Hash{Symbol => Object}) —

    Additional keyword arguments.

Options Hash (**kwargs):

  • :random (Random, SecureRandom) —

    The random number generator to use.

Yields:

  • (char) —

    The block will receive the random characters.

Yield Parameters:

Returns:

  • (Enumerator) —

    If no block is given, an enumerator object will be returned.



254
255
256
257
258
259
260
 
# File 'lib/chars/char_set.rb', line 254

def each_random_char(n,**kwargs,&block)
  return enum_for(__method__,n,**kwargs) unless block_given?

  each_random_byte(n,**kwargs) do |byte|
    yield @chars[byte]
  end
end

#each_string_of_length(length) {|string| ... } ⇒ Enumerator

Enumerates through every possible string belonging to the Chars::CharSet and of the given length.

Parameters:

  • length (Range, Array, Integer) —

    The desired length(s) of each string.

Yields:

  • (string) —

    The given block will be passed each sequential string.

Yield Parameters:

  • string (String) —

    A string belonging to #char_set and length long.

Returns:

  • (Enumerator) —

    If no block is given, an Enumerator will be returned.

Since:

  • 0.3.0



611
612
613
614
615
616
617
618
619
620
621
622
 
# File 'lib/chars/char_set.rb', line 611

def each_string_of_length(length,&block)
  return enum_for(__method__,length) unless block

  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

#each_substring(data, **kwargs) ⇒ Enumerator

Enumerates over all substrings within the given string, of minimum length and that are made up of characters from the Chars::CharSet.

Parameters:

Options Hash (**kwargs):

  • :min_length (Integer) —

    The minimum length of sub-strings found within the given data.

Returns:

  • (Enumerator) —

    If no block is given, an Enumerator object will be returned.

See Also:

Since:

  • 0.3.0



507
508
509
510
511
512
513
 
# File 'lib/chars/char_set.rb', line 507

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

#each_substring_with_index(data, min_length: 4) {|match, index| ... } ⇒ Enumerator

Enumerates over all substrings and their indices within the given string, of minimum length and that are made up of characters from the Chars::CharSet.

Parameters:

  • data (String) —

    The data to find sub-strings within.

  • min_length (Integer) (defaults to: 4) —

    The minimum length of sub-strings found within the given data.

Yields:

  • (match, index) —

    The given block will be passed every matched sub-string and it's index.

  • (String) —

    match A sub-string containing the characters from the Chars::CharSet.

  • (Integer) —

    index The index the sub-string was found at.

Returns:

  • (Enumerator) —

    If no block is given, an Enumerator object will be returned.

Since:

  • 0.3.0



421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
 
# File 'lib/chars/char_set.rb', line 421

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

#include_char?(char) ⇒ Boolean

Determines if a character is contained within the Chars::CharSet.

Parameters:

  • char (String) —

    The character to search for.

Returns:

  • (Boolean) —

    Specifies whether the character is contained within the Chars::CharSet.



103
104
105
106
107
108
109
 
# File 'lib/chars/char_set.rb', line 103

def include_char?(char)
  unless char.empty?
    @chars.has_value?(char) || include_byte?(char.ord)
  else
    false
  end
end

#initialize_copy(other) ⇒ Object

Initializes the copy of another Chars::CharSet object.

Parameters:



40
41
42
 
# File 'lib/chars/char_set.rb', line 40

def initialize_copy(other)
  @chars = other.instance_variable_get('@chars').dup
end

#inspect ⇒ String

Inspects the Chars::CharSet.

Returns:



698
699
700
701
702
703
704
705
706
707
708
709
710
711
 
# File 'lib/chars/char_set.rb', line 698

def inspect
  "#<#{self.class.name}: {" + map { |byte|
    case byte
    when (0x07..0x0d), (0x20..0x7e)
      @chars[byte].dump
    when 0x00
      # sly hack to make char-sets more friendly
      # to us C programmers
      '"\0"'
    else
      sprintf("0x%02x",byte)
    end
  }.join(', ') + "}>"
end

#map_chars {|char| ... } ⇒ Array<String>

Maps the characters of the Chars::CharSet.

Yields:

  • (char) —

    The given block will be used to transform the characters within the Chars::CharSet.

Yield Parameters:

Returns:



170
171
172
 
# File 'lib/chars/char_set.rb', line 170

def map_chars(&block)
  each_char.map(&block)
end

#random_byte(random: Random) ⇒ Integer

Returns a random byte from the Chars::CharSet.

Parameters:

  • random (Random, SecureRandom) (defaults to: Random) —

    The random number generator to use.

Returns:

  • (Integer) —

    A random byte value.



183
184
185
 
# File 'lib/chars/char_set.rb', line 183

def random_byte(random: Random)
  self.entries[random.rand(self.length)]
end

#random_bytes(length, random: Random) ⇒ Array<Integer>

Creates an Array of random bytes from the Chars::CharSet.

Parameters:

  • length (Integer, Array, Range) —

    The length of the Array of random bytes.

  • random (Random, SecureRandom) (defaults to: Random) —

    The random number generator to use.

Returns:

  • (Array<Integer>) —

    The randomly selected bytes.



274
275
276
277
278
279
280
281
282
283
284
285
286
287
 
# File 'lib/chars/char_set.rb', line 274

def random_bytes(length, random: Random)
  case length
  when Array
    Array.new(length.sample(random: random)) do
      random_byte(random: random)
    end
  when Range
    Array.new(random.rand(length)) do
      random_byte(random: random)
    end
  else
    Array.new(length) { random_byte(random: random) }
  end
end

#random_char(**kwargs) ⇒ String

Returns a random character from the Chars::CharSet.

Parameters:

  • kwargs (Hash{Symbol => Object}) —

    Additional keyword arguments.

Options Hash (**kwargs):

  • :random (Random, SecureRandom) —

    The random number generator to use.

Returns:

  • (String) —

    A random char value.



199
200
201
 
# File 'lib/chars/char_set.rb', line 199

def random_char(**kwargs)
  @chars[random_byte(**kwargs)]
end

#random_chars(length, **kwargs) ⇒ Array<String>

Creates an Array of random characters from the Chars::CharSet.

Parameters:

  • length (Integer, Array, Range) —

    The length of the Array of random characters.

  • kwargs (Hash{Symbol => Object}) —

    Additional keyword arguments.

Options Hash (**kwargs):

  • :random (Random, SecureRandom) —

    The random number generator to use.

Returns:

  • (Array<String>) —

    The randomly selected characters.



329
330
331
 
# File 'lib/chars/char_set.rb', line 329

def random_chars(length,**kwargs)
  random_bytes(length,**kwargs).map { |byte| @chars[byte] }
end

#random_distinct_bytes(length, random: Random) ⇒ Array<Integer>

Creates an Array of random non-repeating bytes from the Chars::CharSet.

Parameters:

  • length (Integer, Array, Range) —

    The length of the Array of random non-repeating bytes.

  • random (Random, SecureRandom) (defaults to: Random) —

    The random number generator to use.

Returns:

  • (Array<Integer>) —

    The randomly selected non-repeating bytes.



301
302
303
304
305
306
307
308
309
310
311
312
 
# File 'lib/chars/char_set.rb', line 301

def random_distinct_bytes(length, random: Random)
  shuffled_bytes = bytes.shuffle(random: random)

  case length
  when Array
    shuffled_bytes[0,length.sample(random: random)]
  when Range
    shuffled_bytes[0,random.rand(length)]
  else
    shuffled_bytes[0,length]
  end
end

#random_distinct_chars(length, **kwargs) ⇒ Array<Integer>

Creates an Array of random non-repeating characters from the Chars::CharSet.

Parameters:

  • length (Integer, Array, Range) —

    The length of the Array of random non-repeating characters.

  • kwargs (Hash{Symbol => Object}) —

    Additional keyword arguments.

Options Hash (**kwargs):

  • :random (Random, SecureRandom) —

    The random number generator to use.

Returns:

  • (Array<Integer>) —

    The randomly selected non-repeating characters.



371
372
373
 
# File 'lib/chars/char_set.rb', line 371

def random_distinct_chars(length,**kwargs)
  random_distinct_bytes(length,**kwargs).map { |byte| @chars[byte] }
end

#random_distinct_string(length, **kwargs) ⇒ String

Creates a String containing randomly selected non-repeating characters from the Chars::CharSet.

Parameters:

  • length (Integer, Array, Range) —

    The length of the String of random non-repeating characters.

  • kwargs (Hash{Symbol => Object}) —

    Additional keyword arguments.

Options Hash (**kwargs):

  • :random (Random, SecureRandom) —

    The random number generator to use.

Returns:

  • (String) —

    The String of randomly selected non-repeating characters.

See Also:



393
394
395
 
# File 'lib/chars/char_set.rb', line 393

def random_distinct_string(length,**kwargs)
  random_distinct_chars(length,**kwargs).join
end

#random_string(length, **kwargs) ⇒ String

Creates a String containing randomly selected characters from the Chars::CharSet.

Parameters:

  • length (Integer, Array, Range) —

    The length of the String of random characters.

  • kwargs (Hash{Symbol => Object}) —

    Additional keyword arguments.

Options Hash (**kwargs):

  • :random (Random, SecureRandom) —

    The random number generator to use.

Returns:

  • (String) —

    The String of randomly selected characters.

See Also:



351
352
353
 
# File 'lib/chars/char_set.rb', line 351

def random_string(length,**kwargs)
  random_chars(length,**kwargs).join
end

#select_chars {|char| ... } ⇒ Array<String>

Selects characters from the Chars::CharSet.

Yields:

  • (char) —

    If a block is given, it will be used to select the characters from the Chars::CharSet.

Yield Parameters:

  • char (String) —

    The character to select or reject.

Returns:



153
154
155
 
# File 'lib/chars/char_set.rb', line 153

def select_chars(&block)
  each_char.select(&block)
end

#strings_in(data, options = {}) {|match, (index)| ... } ⇒ Array, Hash

Deprecated.

Use #each_substring_with_index, #substrings_with_index, #each_substring, or #substrings instead.

Finds sub-strings within given data that are made of characters within the Chars::CharSet.

Parameters:

  • data (String) —

    The data to find sub-strings within.

  • options (Hash) (defaults to: {}) —

    Additional options.

Options Hash (options):

  • :length (Integer) — default: 4 —

    The minimum length of sub-strings found within the given data.

  • :offsets (Boolean) — default: 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.

Yields:

  • (match, (index)) —

    The given block will be passed every matched sub-string, and the optional index.

  • (String) —

    match A sub-string containing the characters from the Chars::CharSet.

  • (Integer) —

    index The index the sub-string was found at.

Returns:

  • (Array, Hash) —

    If no block is given, an Array or Hash of sub-strings is returned.



574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
 
# File 'lib/chars/char_set.rb', line 574

def strings_in(data,options={},&block)
  kwargs = {min_length: options.fetch(:length,4)}

  unless block
    if options[:offsets]
      return Hash[substrings_with_indexes(data,**kwargs)]
    else
      return substrings(data,**kwargs)
    end
  end

  case block.arity
  when 2
    each_substring_with_index(data,**kwargs,&block)
  else
    each_substring(data,**kwargs,&block)
  end
end

#strings_of_length(length) ⇒ Enumerator

Returns an Enumerator that enumerates through every possible string belonging to the CharSEt and of the given length.

Parameters:

  • length (Range, Array, Integer) —

    The desired length(s) of each string.

Returns:

  • (Enumerator)

See Also:

  • #each_string


635
636
637
 
# File 'lib/chars/char_set.rb', line 635

def strings_of_length(length)
  each_string_of_length(length)
end

#substrings(data, **kwargs) ⇒ Array<String>

Returns an Array of all substrings within the given string, of minimum length and that are made up of characters from the Chars::CharSet.

Parameters:

Options Hash (**kwargs):

  • :min_length (Integer) —

    The minimum length of sub-strings found within the given data.

Returns:

  • (Array<String>) —

    Tthe array of substrings within the given data.

See Also:

Since:

  • 0.3.0



535
536
537
 
# File 'lib/chars/char_set.rb', line 535

def substrings(data,**kwargs)
  each_substring(data,**kwargs).to_a
end

#substrings_with_indexes(data, **kwargs) ⇒ Array<(String, Integer)>

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 Chars::CharSet.

Parameters:

Options Hash (**kwargs):

  • :min_length (Integer) —

    The minimum length of sub-strings found within the given data.

Returns:

  • (Array<(String, Integer)>) —

    Tthe array of substrings and their indices within the given data.

See Also:

Since:

  • 0.3.0



483
484
485
 
# File 'lib/chars/char_set.rb', line 483

def substrings_with_indexes(data,**kwargs)
  each_substring_with_index(data,**kwargs).to_a
end

#|(set) ⇒ CharSet Also known as: +

Creates a new CharSet object by unioning the Chars::CharSet with another Chars::CharSet.

Parameters:

Returns:

  • (CharSet) —

    The unioned ChraSet.



649
650
651
652
653
 
# File 'lib/chars/char_set.rb', line 649

def |(set)
  set = CharSet.new(set) unless set.kind_of?(CharSet)

  return super(set)
end