Skip to content

class StringScanner
inherits Reference

StringScanner provides for lexical scanning operations on a String.

Example

require "string_scanner"

s = StringScanner.new("This is an example string")
s.eos? # => false

s.scan(/\w+/) # => "This"
s.scan(/\w+/) # => nil
s.scan(/\s+/) # => " "
s.scan(/\s+/) # => nil
s.scan(/\w+/) # => "is"
s.eos?        # => false

s.scan(/\s+/) # => " "
s.scan(/\w+/) # => "an"
s.scan(/\s+/) # => " "
s.scan(/\w+/) # => "example"
s.scan(/\s+/) # => " "
s.scan(/\w+/) # => "string"
s.eos?        # => true

s.scan(/\s+/) # => nil
s.scan(/\w+/) # => nil

Scanning a string means remembering the position of a scan offset, which is just an index. Scanning moves the offset forward, and matches are sought after the offset; usually immediately after it.

Method Categories

Methods that advance the scan offset: * #scan * #scan_until * #skip * #skip_until

Methods that look ahead: * #peek * #check * #check_until

Methods that deal with the position of the offset: * #offset * #offset= * #eos? * #reset * #terminate

Methods that deal with the last match: * #[] * #[]?

Miscellaneous methods: * #inspect * #string

Class methods

.new(str : String)

View source

Methods

#[](n)

Returns the n-th subgroup in the most recent match.

Raises an exception if there was no last match or if there is no subgroup.

require "string_scanner"

s = StringScanner.new("Fri Dec 12 1975 14:39")
regex = /(?<wday>\w+) (?<month>\w+) (?<day>\d+)/
s.scan(regex) # => "Fri Dec 12"
s[0]          # => "Fri Dec 12"
s[1]          # => "Fri"
s[2]          # => "Dec"
s[3]          # => "12"
s["wday"]     # => "Fri"
s["month"]    # => "Dec"
s["day"]      # => "12"
View source

#[]?(n)

Returns the nilable n-th subgroup in the most recent match.

Returns nil if there was no last match or if there is no subgroup.

require "string_scanner"

s = StringScanner.new("Fri Dec 12 1975 14:39")
regex = /(?<wday>\w+) (?<month>\w+) (?<day>\d+)/
s.scan(regex)  # => "Fri Dec 12"
s[0]?          # => "Fri Dec 12"
s[1]?          # => "Fri"
s[2]?          # => "Dec"
s[3]?          # => "12"
s[4]?          # => nil
s["wday"]?     # => "Fri"
s["month"]?    # => "Dec"
s["day"]?      # => "12"
s["year"]?     # => nil
s.scan(/more/) # => nil
s[0]?          # => nil
View source

#check(pattern)

Returns the value that #scan would return, without advancing the scan offset. The last match is still saved, however.

require "string_scanner"

s = StringScanner.new("this is a string")
s.offset = 5
s.check(/\w+/) # => "is"
s.check(/\w+/) # => "is"
View source

#check_until(pattern)

Returns the value that #scan_until would return, without advancing the scan offset. The last match is still saved, however.

require "string_scanner"

s = StringScanner.new("test string")
s.check_until(/tr/) # => "test str"
s.check_until(/g/)  # => "test string"
View source

#eos?

Returns true if the scan offset is at the end of the string.

require "string_scanner"

s = StringScanner.new("this is a string")
s.eos?                # => false
s.scan(/(\w+\s?){4}/) # => "this is a string"
s.eos?                # => true
View source

#inspect(io : IO) : Nil

Writes a representation of the scanner.

Includes the current position of the offset, the total size of the string, and five characters near the current position.

View source

#offset

Returns the current position of the scan offset.

View source

#offset=(position : Int)

Sets the position of the scan offset.

View source

#peek(len)

Extracts a string corresponding to string[offset,len], without advancing the scan offset.

View source

#reset

Resets the scan offset to the beginning and clears the last match.

View source

#rest

Returns the remainder of the string after the scan offset.

require "string_scanner"

s = StringScanner.new("this is a string")
s.scan(/(\w+\s?){2}/) # => "this is "
s.rest                # => "a string"
View source

#scan(pattern)

Tries to match with pattern at the current position. If there's a match, the scanner advances the scan offset, the last match is saved, and it returns the matched string. Otherwise, the scanner returns nil.

require "string_scanner"

s = StringScanner.new("test string")
s.scan(/\w+/)   # => "test"
s.scan(/\w+/)   # => nil
s.scan(/\s\w+/) # => " string"
s.scan(/.*/)    # => ""
View source

#scan_until(pattern)

Scans the string until the pattern is matched. Returns the substring up to and including the end of the match, the last match is saved, and advances the scan offset. Returns nil if no match.

require "string_scanner"

s = StringScanner.new("test string")
s.scan_until(/tr/) # => "test str"
s.scan_until(/tr/) # => nil
s.scan_until(/g/)  # => "ing"
View source

#skip(pattern)

Attempts to skip over the given pattern beginning with the scan offset. In other words, the pattern is not anchored to the current scan offset.

If there's a match, the scanner advances the scan offset, the last match is saved, and it returns the size of the skipped match. Otherwise it returns nil and does not advance the offset.

This method is the same as #scan, but without returning the matched string.

View source

#skip_until(pattern)

Attempts to skip until the given pattern is found after the scan offset. In other words, the pattern is not anchored to the current scan offset.

If there's a match, the scanner advances the scan offset, the last match is saved, and it returns the size of the skip. Otherwise it returns nil and does not advance the offset.

This method is the same as #scan_until, but without returning the matched string.

View source

#string : String

Returns the string being scanned.

View source

#terminate

Moves the scan offset to the end of the string and clears the last match.

View source