constants | attributes | methods
Class

StringScanner

Inheritance
< Object

StringScanner provides for lexical scanning operations on a String. Here is an example of its usage: 

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

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

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

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

Scanning a string means remembering the position of a scan pointer, which is just an index. The point of scanning is to move forward a bit at a time, so matches are sought after the scan pointer; usually immediately after it.

Given the string "test string", here are the pertinent scan pointer positions: 

    t e s t   s t r i n g
  0 1 2 ...             1
                        0

When you scan for a pattern (a regular expression), the match must occur at the character after the scan pointer. If you use scan_until, then the match can occur anywhere after the scan pointer. In both cases, the scan pointer moves just beyond the last character of the match, ready to scan again from the next character onwards. This is demonstrated by the example above.

Method Categories

There are other methods besides the plain scanners. You can look ahead in the string without actually scanning. You can access the most recent match. You can modify the string being scanned, reset or terminate the scanner, find out or change the position of the scan pointer, skip ahead, and so on.

Advancing the Scan Pointer

Looking Ahead

Finding Where we Are

Setting Where we Are

Match Data

Miscellaneous

There are aliases to several of the methods.

Classes & Modules

Methods

Class

Visibility Signature
public must_C_version ()
public new (...)

Instance

Visibility Signature
public << (p1)
public [] (p1)
public beginning_of_line? ()
public check (p1)
public check_until (p1)
public clear ()
public concat (p1)
public empty? ()
public eos? ()
public exist? (p1)
public get_byte ()
public getbyte ()
public getch ()
public initialize_copy (p1)
public inspect ()
public match? (p1)
public matched ()
public matched? ()
public matched_size ()
public matchedsize ()
public peek (p1)
public peep (p1)
public pointer ()
public pointer= (p1)
public pos ()
public pos= (p1)
public post_match ()
public pre_match ()
public reset ()
public rest ()
public rest? ()
public rest_size ()
public restsize ()
public scan (p1)
public scan_full (p1, p2, p3)
public scan_until (p1)
public search_full (p1, p2, p3)
public skip (p1)
public skip_until (p1)
public string ()
public string= (p1)
public terminate ()
public unscan ()

Class Method Detail

StringScanner.must_C_version

This method is defined for backward compatibility.

StringScanner.new(string, dup = false)

Creates a new StringScanner object to scan over the given string. dup argument is obsolete and not used now.

Instance Method Detail

concat(str)
<<(str)

Appends str to the string being scanned. This method does not affect scan pointer. 

  s = StringScanner.new("Fri Dec 12 1975 14:39")
  s.scan(/Fri /)
  s << " +1000 GMT"
  s.string            # -> "Fri Dec 12 1975 14:39 +1000 GMT"
  s.scan(/Dec/)       # -> "Dec"

[](n)

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

  s = StringScanner.new("Fri Dec 12 1975 14:39")
  s.scan(/(\w+) (\w+) (\d+) /)       # -> "Fri Dec 12 "
  s[0]                               # -> "Fri Dec 12 "
  s[1]                               # -> "Fri"
  s[2]                               # -> "Dec"
  s[3]                               # -> "12"
  s.post_match                       # -> "1975 14:39"
  s.pre_match                        # -> ""

beginning_of_line?()

Returns true iff the scan pointer is at the beginning of the line. 

  s = StringScanner.new("test\ntest\n")
  s.bol?           # => true
  s.scan(/te/)
  s.bol?           # => false
  s.scan(/st\n/)
  s.bol?           # => true
  s.terminate
  s.bol?           # => true

check(pattern)

This returns the value that scan would return, without advancing the scan pointer. The match register is affected, though. 

  s = StringScanner.new("Fri Dec 12 1975 14:39")
  s.check /Fri/               # -> "Fri"
  s.pos                       # -> 0
  s.matched                   # -> "Fri"
  s.check /12/                # -> nil
  s.matched                   # -> nil

Mnemonic: it "checks" to see whether a scan will return a value.

check_until(pattern)

This returns the value that scan_until would return, without advancing the scan pointer. The match register is affected, though. 

  s = StringScanner.new("Fri Dec 12 1975 14:39")
  s.check_until /12/          # -> "Fri Dec 12"
  s.pos                       # -> 0
  s.matched                   # -> 12

Mnemonic: it "checks" to see whether a scan_until will return a value.

clear()

Equivalent to terminate. This method is obsolete; use terminate instead.

concat(str)
<<(str)

Appends str to the string being scanned. This method does not affect scan pointer. 

  s = StringScanner.new("Fri Dec 12 1975 14:39")
  s.scan(/Fri /)
  s << " +1000 GMT"
  s.string            # -> "Fri Dec 12 1975 14:39 +1000 GMT"
  s.scan(/Dec/)       # -> "Dec"

empty?()

Equivalent to eos?. This method is obsolete, use eos? instead.

eos?()

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

  s = StringScanner.new('test string')
  p s.eos?          # => false
  s.scan(/test/)
  p s.eos?          # => false
  s.terminate
  p s.eos?          # => true

exist?(pattern)

Looks ahead to see if the pattern exists anywhere in the string, without advancing the scan pointer. This predicates whether a scan_until will return a value. 

  s = StringScanner.new('test string')
  s.exist? /s/            # -> 3
  s.scan /test/           # -> "test"
  s.exist? /s/            # -> 6
  s.exist? /e/            # -> nil

get_byte()

Scans one byte and returns it. This method is NOT multi-byte character sensitive. See also getch. 

  s = StringScanner.new('ab')
  s.get_byte         # => "a"
  s.get_byte         # => "b"
  s.get_byte         # => nil

  s = StringScanner.new("\244\242")
  s.get_byte         # => "\244"
  s.get_byte         # => "\242"
  s.get_byte         # => nil

getbyte()

Equivalent to get_byte. This method is obsolete; use get_byte instead.

getch()

Scans one character and returns it. This method is multi-byte character sensitive. See also get_byte. 

  s = StringScanner.new('ab')
  s.getch           # => "a"
  s.getch           # => "b"
  s.getch           # => nil

  $KCODE = 'EUC'
  s = StringScanner.new("\244\242")
  s.getch           # => "\244\242"   # Japanese hira-kana "A" in EUC-JP
  s.getch           # => nil

dup
clone

Duplicates a StringScanner object.

inspect()

Returns a string that represents the StringScanner object, showing:

match?(pattern)

Tests whether the given pattern is matched from the current scan pointer. Returns the length of the match, or nil. The scan pointer is not advanced. 

  s = StringScanner.new('test string')
  p s.match?(/\w+/)   # -> 4
  p s.match?(/\w+/)   # -> 4
  p s.match?(/\s+/)   # -> nil

matched()

Returns the last matched string. 

  s = StringScanner.new('test string')
  s.match?(/\w+/)     # -> 4
  s.matched           # -> "test"

matched?()

Returns true iff the last match was successful. 

  s = StringScanner.new('test string')
  s.match?(/\w+/)     # => 4
  s.matched?          # => true
  s.match?(/\d+/)     # => nil
  s.matched?          # => false

matched_size()

Returns the size of the most recent match (see matched), or nil if there was no recent match. 

  s = StringScanner.new('test string')
  s.check /\w+/           # -> "test"
  s.matched_size          # -> 4
  s.check /\d+/           # -> nil
  s.matched_size          # -> nil

matchedsize()

Equivalent to matched_size. This method is obsolete; use matched_size instead.

peek(len)

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

  s = StringScanner.new('test string')
  s.peek(7)          # => "test st"
  s.peek(7)          # => "test st"

peep(p1)

Equivalent to peek. This method is obsolete; use peek instead.

pointer()

Returns the position of the scan pointer. In the ‘reset’ position, this value is zero. In the ‘terminated’ position (i.e. the string is exhausted), this value is the length of the string.

In short, it‘s a 0-based index into the string. 

  s = StringScanner.new('test string')
  s.pos               # -> 0
  s.scan_until /str/  # -> "test str"
  s.pos               # -> 8
  s.terminate         # -> #<StringScanner fin>
  s.pos               # -> 11

pos=(n)

Modify the scan pointer. 

  s = StringScanner.new('test string')
  s.pos = 7            # -> 7
  s.rest               # -> "ring"

pos()

Returns the position of the scan pointer. In the ‘reset’ position, this value is zero. In the ‘terminated’ position (i.e. the string is exhausted), this value is the length of the string.

In short, it‘s a 0-based index into the string. 

  s = StringScanner.new('test string')
  s.pos               # -> 0
  s.scan_until /str/  # -> "test str"
  s.pos               # -> 8
  s.terminate         # -> #<StringScanner fin>
  s.pos               # -> 11

pos=(n)

Modify the scan pointer. 

  s = StringScanner.new('test string')
  s.pos = 7            # -> 7
  s.rest               # -> "ring"

post_match()

Return the post-match (in the regular expression sense) of the last scan. 

  s = StringScanner.new('test string')
  s.scan(/\w+/)           # -> "test"
  s.scan(/\s+/)           # -> " "
  s.pre_match             # -> "test"
  s.post_match            # -> "string"

pre_match()

Return the pre-match (in the regular expression sense) of the last scan. 

  s = StringScanner.new('test string')
  s.scan(/\w+/)           # -> "test"
  s.scan(/\s+/)           # -> " "
  s.pre_match             # -> "test"
  s.post_match            # -> "string"

reset()

Reset the scan pointer (index 0) and clear matching data.

rest()

Returns the "rest" of the string (i.e. everything after the scan pointer). If there is no more data (eos? = true), it returns "".

rest?()

Returns true iff there is more data in the string. See eos?. This method is obsolete; use eos? instead. 

  s = StringScanner.new('test string')
  s.eos?              # These two
  s.rest?             # are opposites.

rest_size()

s.rest_size is equivalent to s.rest.size.

restsize()

s.restsize is equivalent to s.rest_size. This method is obsolete; use rest_size instead.

scan(pattern) => String

Tries to match with pattern at the current position. If there‘s a match, the scanner advances the "scan pointer" and returns the matched string. Otherwise, the scanner returns nil. 

  s = StringScanner.new('test string')
  p s.scan(/\w+/)   # -> "test"
  p s.scan(/\w+/)   # -> nil
  p s.scan(/\s+/)   # -> " "
  p s.scan(/\w+/)   # -> "string"
  p s.scan(/./)     # -> nil

scan_full(pattern, return_string_p, advance_pointer_p)

Tests whether the given pattern is matched from the current scan pointer. Returns the matched string if return_string_p is true. Advances the scan pointer if advance_pointer_p is true. The match register is affected.

"full" means "scan with full parameters".

scan_until(pattern)

Scans the string until the pattern is matched. Returns the substring up to and including the end of the match, advancing the scan pointer to that location. If there is no match, nil is returned. 

  s = StringScanner.new("Fri Dec 12 1975 14:39")
  s.scan_until(/1/)        # -> "Fri Dec 1"
  s.pre_match              # -> "Fri Dec "
  s.scan_until(/XYZ/)      # -> nil

search_full(pattern, return_string_p, advance_pointer_p)

Scans the string until the pattern is matched. Returns the matched string if return_string_p is true, otherwise returns the number of bytes advanced. Advances the scan pointer if advance_pointer_p, otherwise not. This method does affect the match register.

skip(pattern)

Attempts to skip over the given pattern beginning with the scan pointer. If it matches, the scan pointer is advanced to the end of the match, and the length of the match is returned. Otherwise, nil is returned.

It‘s similar to scan, but without returning the matched string. 

  s = StringScanner.new('test string')
  p s.skip(/\w+/)   # -> 4
  p s.skip(/\w+/)   # -> nil
  p s.skip(/\s+/)   # -> 1
  p s.skip(/\w+/)   # -> 6
  p s.skip(/./)     # -> nil

skip_until(pattern)

Advances the scan pointer until pattern is matched and consumed. Returns the number of bytes advanced, or nil if no match was found.

Look ahead to match pattern, and advance the scan pointer to the end of the match. Return the number of characters advanced, or nil if the match was unsuccessful.

It‘s similar to scan_until, but without returning the intervening string. 

  s = StringScanner.new("Fri Dec 12 1975 14:39")
  s.skip_until /12/           # -> 10
  s                           #

string()

Returns the string being scanned.

string=(str)

Changes the string being scanned to str and resets the scanner. Returns str.

terminate
clear

Set the scan pointer to the end of the string and clear matching data.

unscan()

Set the scan pointer to the previous position. Only one previous position is remembered, and it changes with each scanning operation. 

  s = StringScanner.new('test string')
  s.scan(/\w+/)        # => "test"
  s.unscan
  s.scan(/../)         # => "te"
  s.scan(/\d/)         # => nil
  s.unscan             # ScanError: unscan failed: previous match had failed