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' Creates a reader with the specified string positioned at byte index pos.
Creates a reader that will be positioned at the last char of the given string.
Returns the current character, or '\0' if the reader is at the end of the string.
Returns the current character.
Returns the size of the #current_char (in bytes) as if it were encoded in UTF-8.
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 true if the reader is not at the end of the string.
Returns true if the reader is not at the beginning of the string.
Reads the next character in the string.
Tries to read the next character in the string.
Returns the byte position of the current character.
Sets #pos to pos.
Reads the previous character in the string.
Tries to read the previous character in the string.
Returns the reader's String.
Enumerable(Char)
Enumerable(Char)
Struct
Struct
Value
Object
Object
Object
Creates a reader with the specified string positioned at byte index pos.
Creates a reader that will be positioned at the last char of the given string.
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' Returns the current character.
Returns nil if the reader is at the end of the string.
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 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.
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 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 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' 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' Returns the byte position of the current character.
reader = Char::Reader.new("ab")
reader.pos # => 0
reader.next_char
reader.pos # => 1 Sets #pos to pos.
reader = Char::Reader.new("abc")
reader.next_char
reader.next_char
reader.pos = 0
reader.current_char # => 'a' 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
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
© 2012–2026 Manas Technology Solutions.
Licensed under the Apache License, Version 2.0.
https://crystal-lang.org/api/1.19.0/Char/Reader.html