struct Char::Reader

Overview

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'

Defined in:

char/reader.cr

Constructors

Instance Method Summary

Instance methods inherited from struct Struct

==(other) : Bool ==, hash(hasher) hash, inspect(io : IO) : Nil inspect, pretty_print(pp) : Nil pretty_print, to_s(io : IO) : Nil to_s

Instance methods inherited from struct Value

==(other : JSON::Any)
==(other : YAML::Any)
==(other)
==
, dup dup

Instance methods inherited from class Object

! : Bool !, !=(other) !=, !~(other) !~, ==(other) ==, ===(other : JSON::Any)
===(other : YAML::Any)
===(other)
===
, =~(other) =~, as(type : Class) as, as?(type : Class) as?, class class, dup dup, hash(hasher)
hash
hash
, in?(collection : Object) : Bool
in?(*values : Object) : Bool
in?
, inspect(io : IO) : Nil
inspect : String
inspect
, is_a?(type : Class) : Bool is_a?, itself itself, nil? : Bool nil?, not_nil!(message)
not_nil!
not_nil!
, pretty_inspect(width = 79, newline = "\n", indent = 0) : String pretty_inspect, pretty_print(pp : PrettyPrint) : Nil pretty_print, responds_to?(name : Symbol) : Bool responds_to?, tap(&) tap, to_json(io : IO) : Nil
to_json : String
to_json
, to_pretty_json(indent : String = " ") : String
to_pretty_json(io : IO, indent : String = " ") : Nil
to_pretty_json
, to_s(io : IO) : Nil
to_s : String
to_s
, to_yaml(io : IO) : Nil
to_yaml : String
to_yaml
, try(&) try, unsafe_as(type : T.class) forall T unsafe_as

Class methods inherited from class Object

from_json(string_or_io, root : String)
from_json(string_or_io)
from_json
, from_yaml(string_or_io : String | IO) from_yaml

Macros inherited from class Object

class_getter(*names, &block) class_getter, class_getter!(*names) class_getter!, class_getter?(*names, &block) class_getter?, class_property(*names, &block) class_property, class_property!(*names) class_property!, class_property?(*names, &block) class_property?, class_setter(*names) class_setter, def_clone def_clone, def_equals(*fields) def_equals, def_equals_and_hash(*fields) def_equals_and_hash, def_hash(*fields) def_hash, delegate(*methods, to object) delegate, forward_missing_to(delegate) forward_missing_to, getter(*names, &block) getter, getter!(*names) getter!, getter?(*names, &block) getter?, property(*names, &block) property, property!(*names) property!, property?(*names, &block) property?, setter(*names) setter

Constructor Detail

def self.new(string : String, pos = 0) #

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


[View source]
def self.new(*, at_end string : String) #

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


[View source]

Instance Method Detail

def current_char : 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'

[View source]
def current_char? : Char | Nil #

Returns the current character.

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


[View source]
def current_char_width : Int32 #

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

[View source]
def each(&) : Nil #

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

[View source]
def error : UInt8 | Nil #

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.


[View source]
def has_next? : Bool #

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

[View source]
def has_previous? : Bool #

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


[View source]
def next_char : 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

[View source]
def next_char? : Char | Nil #

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'

[View source]
def peek_next_char : 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'

[View source]
def pos : Int32 #

Returns the byte position of the current character.

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

[View source]
def 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'

[View source]
def previous_char : 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

[View source]
def previous_char? : Char | Nil #

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

[View source]
def string : String #

Returns the reader's String.


[View source]