Class: StringScanner

Class | StringScanner
In: | strscan/strscan.c
Parent: | 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

- getch
- getbyte
- scan
- scan_until
- skip
- skip_until

### Looking Ahead

- check
- check_until
- exist?
- match?
- peek

### Finding Where we Are

- bol?
- eos?
- rest?
- rest_size
- pos

### Setting Where we Are

- reset
- terminate
- pos=

### Match Data

- matched
- matched?
- matched_size
- []
- pre_match
- post_match

### Miscellaneous

- <<
- concat
- string
- string=
- unscan

There are aliases to several of the methods.

### Methods

<< [] beginning_of_line? bol? check check_until clear concat empty? eos? exist? get_byte getbyte getch inspect match? matched matched? matched_size matchedsize must_C_version new peek peep pointer pointer= pos pos= post_match pre_match reset rest rest? rest_size restsize scan scan_full scan_until search_full skip skip_until string string= terminate unscan

### Classes and Modules

Class StringScanner::Error

### Public Class methods

StringScanner.must_C_version

This method is defined for backward compatibility.

[Source]

    /*
     * call-seq: StringScanner.must_C_version
     *
     * This method is defined for backward compatibility.
     */
    static VALUE
    strscan_s_mustc(self)
        VALUE self;
    {
        return self;
    }

StringScanner.new(string, dup = false)

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

[Source]

    /*
     * call-seq: StringScanner.new(string, dup = false)
     *
     * Creates a new StringScanner object to scan over the given +string+.
     * +dup+ argument is obsolete and not used now.
     */
    static VALUE
    strscan_initialize(argc, argv, self)
        int argc;
        VALUE *argv;
        VALUE self;
    {
        struct strscanner *p;
        VALUE str, need_dup;

        Data_Get_Struct(self, struct strscanner, p);
        rb_scan_args(argc, argv, "11", &str, &need_dup);
        StringValue(str);
        p->str = str;

        return self;
    }

### Public Instance methods

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"

[Source]

    /*
     * call-seq:
     *   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"
     */
    static VALUE
    strscan_concat(self, str)
        VALUE self, str;
    {
        struct strscanner *p;

        GET_SCANNER(self, p);
        StringValue(str);
        rb_str_append(p->str, str);
        return self;
    }

[](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                        # -> ""

[Source]

    /*
     * call-seq: [](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                        # -> ""
     */
    static VALUE
    strscan_aref(self, idx)
        VALUE self, idx;
    {
        struct strscanner *p;
        long i;

        GET_SCANNER(self, p);
        if (! MATCHED_P(p))        return Qnil;

        i = NUM2LONG(idx);
        if (i < 0)
            i += p->regs.num_regs;
        if (i < 0)                 return Qnil;
        if (i >= p->regs.num_regs) return Qnil;
        if (p->regs.beg[i] == -1)  return Qnil;

        return extract_range(p, p->prev + p->regs.beg[i],
                                p->prev + p->regs.end[i]);
    }

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

[Source]

    /*
     * 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
     */
    static VALUE
    strscan_bol_p(self)
        VALUE self;
    {
        struct strscanner *p;

        GET_SCANNER(self, p);
        if (CURPTR(p) > S_PEND(p)) return Qnil;
        if (p->curr == 0) return Qtrue;
        return (*(CURPTR(p) - 1) == '\n') ? Qtrue : Qfalse;
    }

bol?()

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

[Source]

    /*
     * 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
     */
    static VALUE
    strscan_bol_p(self)
        VALUE self;
    {
        struct strscanner *p;

        GET_SCANNER(self, p);
        if (CURPTR(p) > S_PEND(p)) return Qnil;
        if (p->curr == 0) return Qtrue;
        return (*(CURPTR(p) - 1) == '\n') ? Qtrue : Qfalse;
    }

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.

[Source]

    /*
     * call-seq: 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.
     */
    static VALUE
    strscan_check(self, re)
        VALUE self, re;
    {
        return strscan_do_scan(self, re, 0, 1, 1);
    }

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.

[Source]

    /*
     * call-seq: 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.
     */
    static VALUE
    strscan_check_until(self, re)
        VALUE self, re;
    {
        return strscan_do_scan(self, re, 0, 1, 0);
    }

clear()

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

[Source]

    /*
     * Equivalent to #terminate.
     * This method is obsolete; use #terminate instead.
     */
    static VALUE
    strscan_clear(self)
        VALUE self;
    {
        rb_warning("StringScanner#clear is obsolete; use #terminate instead");
        return strscan_terminate(self);
    }

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"

[Source]

    /*
     * call-seq:
     *   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"
     */
    static VALUE
    strscan_concat(self, str)
        VALUE self, str;
    {
        struct strscanner *p;

        GET_SCANNER(self, p);
        StringValue(str);
        rb_str_append(p->str, str);
        return self;
    }

empty?()

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

[Source]

    /*
     * Equivalent to #eos?.
     * This method is obsolete, use #eos? instead.
     */
    static VALUE
    strscan_empty_p(self)
        VALUE self;
    {
        rb_warning("StringScanner#empty? is obsolete; use #eos? instead");
        return strscan_eos_p(self);
    }

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

[Source]

    /*
     * 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
     */
    static VALUE
    strscan_eos_p(self)
        VALUE self;
    {
        struct strscanner *p;

        GET_SCANNER(self, p);
        if (EOS_P(p))
            return Qtrue;
        else
            return Qfalse;
    }

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

[Source]

    /*
     * call-seq: 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
     */
    static VALUE
    strscan_exist_p(self, re)
        VALUE self, re;
    {
        return strscan_do_scan(self, re, 0, 0, 0);
    }

get_byte()

Scans one byte and returns it. Similar to, but not the same as, getch.

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

[Source]

    /*
     * Scans one byte and returns it.  Similar to, but not the same as, #getch.
     *
     *  s = StringScanner.new('ab')
     *  s.get_byte         # => "a"
     *  s.get_byte         # => "b"
     *  s.get_byte         # => nil
     */
    static VALUE
    strscan_get_byte(self)
        VALUE self;
    {
        struct strscanner *p;

        GET_SCANNER(self, p);
        CLEAR_MATCH_STATUS(p);
        if (EOS_P(p))
            return Qnil;

        p->prev = p->curr;
        p->curr++;
        MATCHED(p);
        adjust_registers_to_matched(p);
        return extract_range(p, p->prev + p->regs.beg[0],
                                p->prev + p->regs.end[0]);
    }

getbyte()

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

[Source]

    /*
     * Equivalent to #get_byte.
     * This method is obsolete; use #get_byte instead.
     */
    static VALUE
    strscan_getbyte(self)
        VALUE self;
    {
        rb_warning("StringScanner#getbyte is obsolete; use #get_byte instead");
        return strscan_get_byte(self);
    }

getch()

Scans one character and returns it.

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

[Source]

    /*
     * Scans one character and returns it.
     *
     *   s = StringScanner.new('ab')
     *   s.getch           # => "a"
     *   s.getch           # => "b"
     *   s.getch           # => nil
     */
    static VALUE
    strscan_getch(self)
        VALUE self;
    {
        struct strscanner *p;
        long len;

        GET_SCANNER(self, p);
        CLEAR_MATCH_STATUS(p);
        if (EOS_P(p))
            return Qnil;

        len = mbclen(*CURPTR(p));
        if (p->curr + len > S_LEN(p))
            len = S_LEN(p) - p->curr;
        p->prev = p->curr;
        p->curr += len;
        MATCHED(p);
        adjust_registers_to_matched(p);
        return extract_range(p, p->prev + p->regs.beg[0],
                                p->prev + p->regs.end[0]);
    }

inspect()

Returns a string that represents the StringScanner object, showing:

- the current position
- the size of the string
- the characters surrounding the scan pointer

  s = StringScanner.new("Fri Dec 12 1975 14:39") s.inspect # -> ’#<StringScanner 0/21 @ "Fri D…">’ s.scan_until /12/ # -> "Fri Dec 12" s.inspect # -> ’#<StringScanner 10/21 "…ec 12" @ " 1975…">’

[Source]

    /*
     * Returns a string that represents the StringScanner object, showing:
     * - the current position
     * - the size of the string
     * - the characters surrounding the scan pointer
     *
     *   s = StringScanner.new("Fri Dec 12 1975 14:39")
     *   s.inspect            # -> '#<StringScanner 0/21 @ "Fri D...">'
     *   s.scan_until /12/    # -> "Fri Dec 12"
     *   s.inspect            # -> '#<StringScanner 10/21 "...ec 12" @ " 1975...">'
     */
    static VALUE
    strscan_inspect(self)
        VALUE self;
    {
        struct strscanner *p;
        char buf[BUFSIZE];
        long len;
        VALUE a, b;

        Data_Get_Struct(self, struct strscanner, p);
        if (NIL_P(p->str)) {
            len = snprintf(buf, BUFSIZE, "#<%s (uninitialized)>",
                           rb_class2name(CLASS_OF(self)));
            return infect(rb_str_new(buf, len), p);
        }
        if (EOS_P(p)) {
            len = snprintf(buf, BUFSIZE, "#<%s fin>",
                           rb_class2name(CLASS_OF(self)));
            return infect(rb_str_new(buf, len), p);
        }
        if (p->curr == 0) {
            b = inspect2(p);
            len = snprintf(buf, BUFSIZE, "#<%s %ld/%ld @ %s>",
                           rb_class2name(CLASS_OF(self)),
                           p->curr, S_LEN(p),
                           RSTRING(b)->ptr);
            return infect(rb_str_new(buf, len), p);
        }
        a = inspect1(p);
        b = inspect2(p);
        len = snprintf(buf, BUFSIZE, "#<%s %ld/%ld %s @ %s>",
                       rb_class2name(CLASS_OF(self)),
                       p->curr, S_LEN(p),
                       RSTRING(a)->ptr,
                       RSTRING(b)->ptr);
        return infect(rb_str_new(buf, len), p);
    }

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

[Source]

    /*
     * call-seq: 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
     */
    static VALUE
    strscan_match_p(self, re)
        VALUE self, re;
    {
        return strscan_do_scan(self, re, 0, 0, 1);
    }

matched()

Returns the last matched string.

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

[Source]

    /*
     * Returns the last matched string.
     *
     *   s = StringScanner.new('test string')
     *   s.match?(/\w+/)     # -> 4
     *   s.matched           # -> "test"
     */
    static VALUE
    strscan_matched(self)
        VALUE self;
    {
        struct strscanner *p;

        GET_SCANNER(self, p);
        if (! MATCHED_P(p)) return Qnil;

        return extract_range(p, p->prev + p->regs.beg[0],
                                p->prev + p->regs.end[0]);
    }

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

[Source]

    /*
     * 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
     */
    static VALUE
    strscan_matched_p(self)
        VALUE self;
    {
        struct strscanner *p;

        GET_SCANNER(self, p);
        if (MATCHED_P(p))
            return Qtrue;
        else
            return Qfalse;
    }

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

[Source]

    /*
     * 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
     */
    static VALUE
    strscan_matched_size(self)
        VALUE self;
    {
        struct strscanner *p;

        GET_SCANNER(self, p);
        if (! MATCHED_P(p)) return Qnil;

        return INT2NUM(p->regs.end[0] - p->regs.beg[0]);
    }

matchedsize()

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

[Source]

    /*
     * Equivalent to #matched_size.
     * This method is obsolete; use #matched_size instead.
     */
    static VALUE
    strscan_matchedsize(self)
        VALUE self;
    {
        rb_warning("StringScanner#matchedsize is obsolete; use #matched_size instead");
        return strscan_matched_size(self);
    }

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"

[Source]

    /*
     * call-seq: peek(len)
     *
     * Extracts a string corresponding to <tt>string[pos,len]</tt>, without
     * advancing the scan pointer.
     *
     *   s = StringScanner.new('test string')
     *   s.peek(7)          # => "test st"
     *   s.peek(7)          # => "test st"
     *
     */
    static VALUE
    strscan_peek(self, vlen)
        VALUE self, vlen;
    {
        struct strscanner *p;
        long len;

        GET_SCANNER(self, p);

        len = NUM2LONG(vlen);
        if (EOS_P(p))
            return infect(rb_str_new("", 0), p);

        if (p->curr + len > S_LEN(p))
            len = S_LEN(p) - p->curr;
        return extract_beg_len(p, p->curr, len);
    }

peep(p1)

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

[Source]

    /*
     * Equivalent to #peek.
     * This method is obsolete; use #peek instead.
     */
    static VALUE
    strscan_peep(self, vlen)
        VALUE self, vlen;
    {
        rb_warning("StringScanner#peep is obsolete; use #peek instead");
        return strscan_peek(self, vlen);
    }

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 1-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

[Source]

    /*
     * 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 1-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
     */
    static VALUE
    strscan_get_pos(self)
        VALUE self;
    {
        struct strscanner *p;

        GET_SCANNER(self, p);
        return INT2FIX(p->curr);
    }

pos=(n)

Modify the scan pointer.

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

[Source]

    /*
     * call-seq: pos=(n)
     *
     * Modify the scan pointer.
     *
     *   s = StringScanner.new('test string')
     *   s.pos = 7            # -> 7
     *   s.rest               # -> "ring"
     */
    static VALUE
    strscan_set_pos(self, v)
        VALUE self, v;
    {
        struct strscanner *p;
        long i;

        GET_SCANNER(self, p);
        i = NUM2INT(v);
        if (i < 0) i += S_LEN(p);
        if (i < 0) rb_raise(rb_eRangeError, "index out of range");
        if (i > S_LEN(p)) rb_raise(rb_eRangeError, "index out of range");
        p->curr = i;
        return INT2NUM(i);
    }

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 1-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

[Source]

    /*
     * 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 1-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
     */
    static VALUE
    strscan_get_pos(self)
        VALUE self;
    {
        struct strscanner *p;

        GET_SCANNER(self, p);
        return INT2FIX(p->curr);
    }

pos=(n)

Modify the scan pointer.

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

[Source]

    /*
     * call-seq: pos=(n)
     *
     * Modify the scan pointer.
     *
     *   s = StringScanner.new('test string')
     *   s.pos = 7            # -> 7
     *   s.rest               # -> "ring"
     */
    static VALUE
    strscan_set_pos(self, v)
        VALUE self, v;
    {
        struct strscanner *p;
        long i;

        GET_SCANNER(self, p);
        i = NUM2INT(v);
        if (i < 0) i += S_LEN(p);
        if (i < 0) rb_raise(rb_eRangeError, "index out of range");
        if (i > S_LEN(p)) rb_raise(rb_eRangeError, "index out of range");
        p->curr = i;
        return INT2NUM(i);
    }

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"

[Source]

    /*
     * Return the <i><b>post</b>-match</i> (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"
     */
    static VALUE
    strscan_post_match(self)
        VALUE self;
    {
        struct strscanner *p;

        GET_SCANNER(self, p);
        if (! MATCHED_P(p)) return Qnil;

        return extract_range(p, p->prev + p->regs.end[0], S_LEN(p));
    }

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"

[Source]

    /*
     * Return the <i><b>pre</b>-match</i> (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"
     */
    static VALUE
    strscan_pre_match(self)
        VALUE self;
    {
        struct strscanner *p;

        GET_SCANNER(self, p);
        if (! MATCHED_P(p)) return Qnil;

        return extract_range(p, 0, p->prev + p->regs.beg[0]);
    }

reset()

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

[Source]

    /*
     * Reset the scan pointer (index 0) and clear matching data.
     */
    static VALUE
    strscan_reset(self)
        VALUE self;
    {
        struct strscanner *p;

        GET_SCANNER(self, p);
        p->curr = 0;
        CLEAR_MATCH_STATUS(p);
        return self;
    }

rest()

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

[Source]

    /*
     * Returns the "rest" of the string (i.e. everything after the scan pointer).
     * If there is no more data (eos? = true), it returns <tt>""</tt>.
     */
    static VALUE
    strscan_rest(self)
        VALUE self;
    {
        struct strscanner *p;

        GET_SCANNER(self, p);
        if (EOS_P(p)) {
            return infect(rb_str_new("", 0), p);
        }
        return extract_range(p, p->curr, S_LEN(p));
    }

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.

[Source]

    /*
     * 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.
     */
    static VALUE
    strscan_rest_p(self)
        VALUE self;
    {
        struct strscanner *p;

        GET_SCANNER(self, p);
        if (EOS_P(p))
            return Qfalse;
        else
            return Qtrue;
    }

rest_size()

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

[Source]

    /*
     * <tt>s.rest_size</tt> is equivalent to <tt>s.rest.size</tt>.
     */
    static VALUE
    strscan_rest_size(self)
        VALUE self;
    {
        struct strscanner *p;
        long i;

        GET_SCANNER(self, p);
        if (EOS_P(p)) {
            return INT2FIX(0);
        }

        i = S_LEN(p) - p->curr;
        return INT2FIX(i);
    }

restsize()

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

[Source]

    /*
     * <tt>s.restsize</tt> is equivalent to <tt>s.rest_size</tt>.
     * This method is obsolete; use #rest_size instead.
     */
    static VALUE
    strscan_restsize(self)
        VALUE self;
    {
        rb_warning("StringScanner#restsize is obsolete; use #rest_size instead");
        return strscan_rest_size(self);
    }

scan(pattern)

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

[Source]

    /*
     * call-seq: scan(pattern)
     *
     * 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
     *
     */
    static VALUE
    strscan_scan(self, re)
        VALUE self, re;
    {
        return strscan_do_scan(self, re, 1, 1, 1);
    }

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".

[Source]

    /*
     * call-seq: 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".
     */
    static VALUE
    strscan_scan_full(self, re, s, f)
        VALUE self, re, s, f;
    {
        return strscan_do_scan(self, re, RTEST(s), RTEST(f), 1);
    }

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

[Source]

    /*
     * call-seq: 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
     */
    static VALUE
    strscan_scan_until(self, re)
        VALUE self, re;
    {
        return strscan_do_scan(self, re, 1, 1, 0);
    }

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.

[Source]

    /*
     * call-seq: 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.
     */
    static VALUE
    strscan_search_full(self, re, s, f)
        VALUE self, re, s, f;
    {
        return strscan_do_scan(self, re, RTEST(s), RTEST(f), 0);
    }

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

[Source]

    /*
     * call-seq: 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
     *
     */
    static VALUE
    strscan_skip(self, re)
        VALUE self, re;
    {
        return strscan_do_scan(self, re, 1, 0, 1);
    }

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                           #

[Source]

    /*
     * call-seq: 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                           #
     */
    static VALUE
    strscan_skip_until(self, re)
        VALUE self, re;
    {
        return strscan_do_scan(self, re, 1, 0, 0);
    }

string()

Returns the string being scanned.

[Source]

    /*
     * Returns the string being scanned.
     */
    static VALUE
    strscan_get_string(self)
        VALUE self;
    {
        struct strscanner *p;

        GET_SCANNER(self, p);
        return p->str;
    }

string=(str)

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

[Source]

    /*
     * call-seq: string=(str)
     *
     * Changes the string being scanned to +str+ and resets the scanner.
     * Returns +str+.
     */
    static VALUE
    strscan_set_string(self, str)
        VALUE self, str;
    {
        struct strscanner *p;

        Data_Get_Struct(self, struct strscanner, p);
        StringValue(str);
        p->str = rb_str_dup(str);
        rb_obj_freeze(p->str);
        p->curr = 0;
        CLEAR_MATCH_STATUS(p);
        return str;
    }

terminate
clear

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

[Source]

    /*
     * call-seq:
     *   terminate
     *   clear
     *
     * Set the scan pointer to the end of the string and clear matching data.
     */
    static VALUE
    strscan_terminate(self)
        VALUE self;
    {
        struct strscanner *p;

        GET_SCANNER(self, p);
        p->curr = S_LEN(p);
        CLEAR_MATCH_STATUS(p);
        return self;
    }

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: can't unscan: prev match had failed

[Source]

    /*
     * 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: can't unscan: prev match had failed
     */
    static VALUE
    strscan_unscan(self)
        VALUE self;
    {
        struct strscanner *p;

        GET_SCANNER(self, p);
        if (! MATCHED_P(p))
            rb_raise(ScanError, "can't unscan: prev match had failed");

        p->curr = p->prev;
        CLEAR_MATCH_STATUS(p);
        return self;
    }

[Validate]