struct

Char::Reader

Inherits Enumerable / Struct / Value / Object

A Char::Reader allows iterating a String by Chars.

As soon as you instantiate a Char::Reader it will decode the first char in the String, which can be accessed by invoking current_char. At this point pos, the current position in the string, will equal zero. Successive calls to next_char return the next chars in the string, advancing pos.

NOTE: The null character '\0' will be returned in current_char when the end is reached (as well as when the string is empty). Thus, has_next? will return false only when pos is equal to the string's bytesize, in which case current_char will always be '\0'.

NOTE: For performance reasons, Char::Reader has value semantics, so care must be taken when a reader is declared as a local variable and passed to another method:

def lstrip(reader)
  until reader.current_char.whitespace?
    reader.next_char
  end
  reader
end

# caller's internal state is untouched
reader = Char::Reader.new("   abc")
lstrip(reader)
reader.current_char # => ' '

# to modify caller's internal state, the method must return a new reader
reader = lstrip(reader)
reader.current_char # => 'a'

Constructors

new(string : String, pos = 0)

Creates a reader with the specified string positioned at byte index pos.

Source
new(*, at_end string : String)

Creates a reader that will be positioned at the last char of the given string.

Source

Instance methods

current_char

Returns the current character, or '\0' if the reader is at the end of the string.

reader = Char::Reader.new("ab")
reader.current_char # => 'a'
reader.next_char
reader.current_char # => 'b'
reader.next_char
reader.current_char # => '\0'
Source
current_char?

Returns the current character.

Returns nil if the reader is at the end of the string.

Source
current_char_width

Returns the size of the #current_char (in bytes) as if it were encoded in UTF-8.

reader = Char::Reader.new("aé")
reader.current_char_width # => 1
reader.next_char
reader.current_char_width # => 2
Source
each

Yields successive characters from #string starting from #pos.

reader = Char::Reader.new("abc")
reader.next_char
reader.each do |c|
  puts c.upcase
end
B
C
Source
error

If there was an error decoding the current char because of an invalid UTF-8 byte sequence, returns the byte that produced the invalid encoding. Returns 0 if the char would've been out of bounds. Otherwise returns nil.

Source
has_next?

Returns true if the reader is not at the end of the string.

NOTE: This only means #next_char will successfully increment #pos; if the reader is already at the last character, #next_char will return the terminating null byte because there isn't really a next character.

reader = Char::Reader.new("ab")
reader.has_next? # => true
reader.next_char # => 'b'
reader.has_next? # => true
reader.next_char # => '\0'
reader.has_next? # => false
Source
has_previous?

Returns true if the reader is not at the beginning of the string.

Source
next_char

Reads the next character in the string.

If the reader is at the end of the string after incrementing #pos, returns '\0'. If the reader is already at the end beforehand, raises IndexError.

reader = Char::Reader.new("abc")
reader.next_char # => 'b'
reader.next_char # => 'c'
reader.next_char # => '\0'
reader.next_char # raise IndexError
Source
next_char?

Tries to read the next character in the string.

If the reader is at the end of the string before or after incrementing #pos, returns nil.

reader = Char::Reader.new("abc")
reader.next_char?   # => 'b'
reader.next_char?   # => 'c'
reader.next_char?   # => nil
reader.current_char # => '\0'
Source
peek_next_char

Returns the next character in the #string without incrementing #pos.

Returns '\0' if the reader is at the last character of the string. Raises IndexError if the reader is at the end.

reader = Char::Reader.new("ab")
reader.peek_next_char # => 'b'
reader.current_char   # => 'a'
Source
pos

Returns the byte position of the current character.

reader = Char::Reader.new("ab")
reader.pos # => 0
reader.next_char
reader.pos # => 1
Source
pos=(pos : Int32)

Sets #pos to pos.

reader = Char::Reader.new("abc")
reader.next_char
reader.next_char
reader.pos = 0
reader.current_char # => 'a'
Source
previous_char

Reads the previous character in the string.

Raises IndexError if the reader is already at the beginning of the string. Otherwise decrements #pos.

reader = Char::Reader.new(at_end: "abc")
reader.previous_char # => 'b'
reader.previous_char # => 'a'
reader.previous_char # raises IndexError
Source
previous_char?

Tries to read the previous character in the string.

Returns nil if the reader is already at the beginning of the string. Otherwise decrements #pos.

reader = Char::Reader.new(at_end: "abc")
reader.previous_char? # => 'b'
reader.previous_char? # => 'a'
reader.previous_char? # => nil
Source
string

Returns the reader's String.

Source