1#@!#!123s

: / opt / alt / ruby34 / share / ri / system / StringScanner /
Filename : cdesc-StringScanner.ri
back
U:RDoc::NormalClass[iI"StringScanner:ET@I"Object;To:RDoc::Markup::Document:@parts[o;;[to:RDoc::Markup::Paragraph;[I"�\Class <code>StringScanner</code> supports processing a stored string as a stream;
this code creates a new <code>StringScanner</code> object with string <code>'foobarbaz'</code>:;To:RDoc::Markup::Verbatim;[I"@require 'strscan'
scanner = StringScanner.new('foobarbaz')
;T:@format:rbS:RDoc::Markup::Heading:
leveli:	textI"About the Examples;To;	;[I"PAll examples here assume that <code>StringScanner</code> has been required:;To;
;[I"require 'strscan'
;T;;o;	;[I"@Some examples here assume that these constants are defined:;To;
;[I"�MULTILINE_TEXT = <<~EOT
Go placidly amid the noise and haste,
and remember what peace there may be in silence.
EOT

HIRAGANA_TEXT = 'こんにちは'

ENGLISH_TEXT = 'Hello'
;T;;o;	;[I"GSome examples here assume that certain helper methods are defined:;To:RDoc::Markup::List:
@type:BULLET:@items[o:RDoc::Markup::ListItem:@label0;[o;	;[I"<code>put_situation(scanner)</code>:
 Displays the values of the scanner's
 methods #pos, #charpos, #rest, and #rest_size.;To;;0;[o;	;[I"y<code>put_match_values(scanner)</code>:
 Displays the scanner's {match values}[rdoc-ref:StringScanner@Match+Values].;To;;0;[o;	;[I"�<code>match_values_cleared?(scanner)</code>:
 Returns whether the scanner's {match values}[rdoc-ref:StringScanner@Match+Values] are cleared.;To;	;[I"=See examples [here][ext/strscan/helper_methods_md.html].;TS;
;i;I"+The <code>StringScanner</code> \Object;To;	;[I"�This code creates a <code>StringScanner</code> object
(we'll call it simply a _scanner_),
and shows some of its basic properties:;To;
;[I"�scanner = StringScanner.new('foobarbaz')
scanner.string # => "foobarbaz"
put_situation(scanner)
# Situation:
#   pos:       0
#   charpos:   0
#   rest:      "foobarbaz"
#   rest_size: 9
;T;;o;	;[I"The scanner has:;To;;;;[o;;0;[o;	;[I"&A <i>stored string</i>, which is:;Fo;;;;[o;;0;[o;	;[I"}Initially set by StringScanner.new(string) to the given <code>string</code>
 (<code>'foobarbaz'</code> in the example above).;Fo;;0;[o;	;[I"IModifiable by methods #string=(new_string) and #concat(more_string).;Fo;;0;[o;	;[I" Returned by method #string.;Fo;	;[I"IMore at {Stored String}[rdoc-ref:StringScanner@Stored+String] below.;Fo;;0;[o;	;[I"gA _position_;
 a zero-based index into the bytes of the stored string (_not_ into its characters):;Fo;;;;[	o;;0;[o;	;[I":Initially set by StringScanner.new to <code>0</code>.;Fo;;0;[o;	;[I"Returned by method #pos.;Fo;;0;[o;	;[I"MModifiable explicitly by methods #reset, #terminate, and #pos=(new_pos).;Fo;;0;[o;	;[I"FModifiable implicitly (various traversing methods, among others).;Fo;	;[I"XMore at {Byte Position}[rdoc-ref:StringScanner@Byte+Position+-28Position-29] below.;Fo;;0;[	o;	;[I"�A <i>target substring</i>,
 which is a trailing substring of the stored string;
 it extends from the current position to the end of the stored string:;Fo;;;;[o;;0;[o;	;[I"}Initially set by StringScanner.new(string) to the given <code>string</code>
 (<code>'foobarbaz'</code> in the example above).;Fo;;0;[o;	;[I"Returned by method #rest.;Fo;;0;[o;	;[I"NModified by any modification to either the stored string or the position.;Fo;	;[I"�<b>Most importantly</b>:
the searching and traversing methods operate on the target substring,
which may be (and often is) less than the entire stored string.;Fo;	;[I"OMore at {Target Substring}[rdoc-ref:StringScanner@Target+Substring] below.;FS;
;i;I"Stored \String;To;	;[I"\The <i>stored string</i> is the string stored in the <code>StringScanner</code> object.;To;	;[I"HEach of these methods sets, modifies, or returns the stored string:;To:RDoc::Markup::Table:@header[I"Method;TI"Effect;T:@align[00:
@body[	[I"::new(string);TI"0Creates a new scanner for the given string.;T[I"#string=(new_string);TI")Replaces the existing stored string.;T[I"#concat(more_string);TI"4Appends a string to the existing stored string.;T[I"#string;TI"Returns the stored string.;TS;
;i;I"Positions;To;	;[I"{A <code>StringScanner</code> object maintains a zero-based <i>byte position</i>
and a zero-based <i>character position</i>.;To;	;[I"5Each of these methods explicitly sets positions:;To;;[I"Method;TI"Effect;T;[00;[[I"#reset;TI"=Sets both positions to zero (begining of stored string).;T[I"#terminate;TI"9Sets both positions to the end of the stored string.;T[I"#pos=(new_byte_position);TI"4Sets byte position; adjusts character position.;TS;
;i;I"Byte Position (Position);To;	;[I"�The byte position (or simply _position_)
is a zero-based index into the bytes in the scanner's stored string;
for a new <code>StringScanner</code> object, the byte position is zero.;To;	;[I"When the byte position is:;To;;;;[o;;0;[o;	;[I"OZero (at the beginning), the target substring is the entire stored string.;To;;0;[o;	;[I"tEqual to the size of the stored string (at the end),
 the target substring is the empty string <code>''</code>.;To;	;[I"%To get or set the byte position:;To;;;;[o;;0;[o;	;[I"%#pos: returns the byte position.;To;;0;[o;	;[I",#pos=(new_pos): sets the byte position.;To;	;[I"�Many methods use the byte position as the basis for finding matches;
many others set, increment, or decrement the byte position:;To;
;[I"scanner = StringScanner.new('foobar')
scanner.pos # => 0
scanner.scan(/foo/) # => "foo" # Match found.
scanner.pos         # => 3     # Byte position incremented.
scanner.scan(/foo/) # => nil   # Match not found.
scanner.pos # => 3             # Byte position not changed.
;T;;o;	;[I";Some methods implicitly modify the byte position;
see:;To;;;;[o;;0;[o;	;[I"Y{Setting the Target Substring}[rdoc-ref:StringScanner@Setting+the+Target+Substring].;To;;0;[o;	;[I"_{Traversing the Target Substring}[rdoc-ref:StringScanner@Traversing+the+Target+Substring].;To;	;[I"ZThe values of these methods are derived directly from the values of #pos and #string:;To;;;;[o;;0;[o;	;[I"S#charpos: the {character position}[rdoc-ref:StringScanner@Character+Position].;To;;0;[o;	;[I"L#rest: the {target substring}[rdoc-ref:StringScanner@Target+Substring].;To;;0;[o;	;[I"(#rest_size: <code>rest.size</code>.;TS;
;i;I"Character Position;To;	;[I"�The character position is a zero-based index into the _characters_
in the stored string;
for a new <code>StringScanner</code> object, the character position is zero.;To;	;[I"\\Method #charpos returns the character position;
its value may not be reset explicitly.;To;	;[I"JSome methods change (increment or reset) the character position;
see:;To;;;;[o;;0;[o;	;[I"Y{Setting the Target Substring}[rdoc-ref:StringScanner@Setting+the+Target+Substring].;To;;0;[o;	;[I"_{Traversing the Target Substring}[rdoc-ref:StringScanner@Traversing+the+Target+Substring].;To;	;[I"5Example (string includes multi-byte characters):;To;
;[I"�scanner = StringScanner.new(ENGLISH_TEXT) # Five 1-byte characters.
scanner.concat(HIRAGANA_TEXT)             # Five 3-byte characters
scanner.string # => "Helloこんにちは"       # Twenty bytes in all.
put_situation(scanner)
# Situation:
#   pos:       0
#   charpos:   0
#   rest:      "Helloこんにちは"
#   rest_size: 20
scanner.scan(/Hello/) # => "Hello" # Five 1-byte characters.
put_situation(scanner)
# Situation:
#   pos:       5
#   charpos:   5
#   rest:      "こんにちは"
#   rest_size: 15
scanner.getch         # => "こ"    # One 3-byte character.
put_situation(scanner)
# Situation:
#   pos:       8
#   charpos:   6
#   rest:      "んにちは"
#   rest_size: 12
;T;;S;
;i;I"Target Substring;To;	;[I"�The target substring is the the part of the {stored string}[rdoc-ref:StringScanner@Stored+String]
that extends from the current {byte position}[rdoc-ref:StringScanner@Byte+Position+-28Position-29] to the end of the stored string;
it is always either:;To;;;;[o;;0;[o;	;[I"6The entire stored string (byte position is zero).;To;;0;[o;	;[I"HA trailing substring of the stored string (byte position positive).;To;	;[I"eThe target substring is returned by method #rest,
and its size is returned by method #rest_size.;To;	;[I"Examples:;To;
;[I"�scanner = StringScanner.new('foobarbaz')
put_situation(scanner)
# Situation:
#   pos:       0
#   charpos:   0
#   rest:      "foobarbaz"
#   rest_size: 9
scanner.pos = 3
put_situation(scanner)
# Situation:
#   pos:       3
#   charpos:   3
#   rest:      "barbaz"
#   rest_size: 6
scanner.pos = 9
put_situation(scanner)
# Situation:
#   pos:       9
#   charpos:   9
#   rest:      ""
#   rest_size: 0
;T;;S;
;i;I"!Setting the Target Substring;To;	;[I"*The target substring is set whenever:;To;;;;[o;;0;[o;	;[I"�The {stored string}[rdoc-ref:StringScanner@Stored+String] is set (position reset to zero; target substring set to stored string).;To;;0;[o;	;[I"}The {byte position}[rdoc-ref:StringScanner@Byte+Position+-28Position-29] is set (target substring adjusted accordingly).;TS;
;i;I""Querying the Target Substring;To;	;[I"?This table summarizes (details and examples at the links):;To;;[I"Method;TI"Returns;T;[00;[[I"
#rest;TI"Target substring.;T[I"#rest_size;TI"&Size (bytes) of target substring.;TS;
;i;I"#Searching the Target Substring;To;	;[I"�A _search_ method examines the target substring,
but does not advance the {positions}[rdoc-ref:StringScanner@Positions]
or (by implication) shorten the target substring.;To;	;[I"?This table summarizes (details and examples at the links):;To;;[I"Method;TI"Returns;TI"Sets Match Values?;T;[000;[[I"#check(pattern);TI"(Matched leading substring or +nil+.;TI"	Yes.;T[I"#check_until(pattern);TI"+Matched substring (anywhere) or +nil+.;TI"	Yes.;T[I"#exist?(pattern);TI",Matched substring (anywhere) end index.;TI"	Yes.;T[I"#match?(pattern);TI"0Size of matched leading substring or +nil+.;TI"	Yes.;T[I"#peek(size);TI"/Leading substring of given length (bytes).;TI"No.;T[I"#peek_byte;TI"#Integer leading byte or +nil+.;TI"No.;T[I"
#rest;TI"2Target substring (from byte position to end).;TI"No.;TS;
;i;I"$Traversing the Target Substring;To;	;[I"LA _traversal_ method examines the target substring,
and, if successful:;To;;;;[o;;0;[o;	;[I"@Advances the {positions}[rdoc-ref:StringScanner@Positions].;To;;0;[o;	;[I"#Shortens the target substring.;To;	;[I";This table summarizes (details and examples at links):;To;;[I"Method;TI"Returns;TI"Sets Match Values?;T;[000;[
[I"#get_byte;TI"Leading byte or +nil+.;TI"No.;T[I"#getch;TI" Leading character or +nil+.;TI"No.;T[I"#scan(pattern);TI"(Matched leading substring or +nil+.;TI"	Yes.;T[I"#scan_byte;TI"#Integer leading byte or +nil+.;TI"No.;T[I"#scan_until(pattern);TI"+Matched substring (anywhere) or +nil+.;TI"	Yes.;T[I"#skip(pattern);TI"-Matched leading substring size or +nil+.;TI"	Yes.;T[I"#skip_until(pattern);TI"9Position delta to end-of-matched-substring or +nil+.;TI"	Yes.;T[I"#unscan;TI"+self+.;TI"No.;TS;
;i;I"Querying the Scanner;To;	;[I"jEach of these methods queries the scanner object
without modifying it (details and examples at links);To;;[I"Method;TI"Returns;T;[00;[[I"#beginning_of_line?;TI"+true+ or +false+.;T[I"
#charpos;TI"Character position.;T[I"
#eos?;TI"+true+ or +false+.;T[I"#fixed_anchor?;TI"+true+ or +false+.;T[I"
#inspect;TI"%String representation of +self+.;T[I"	#pos;TI"Byte position.;T[I"
#rest;TI"Target substring.;T[I"#rest_size;TI"Size of target substring.;T[I"#string;TI"Stored string.;TS;
;i;I"
Matching;To;	;[I"	<code>StringScanner</code> implements pattern matching via Ruby class {Regexp}[https://docs.ruby-lang.org/en/master/Regexp.html],
and its matching behaviors are the same as Ruby's
except for the {fixed-anchor property}[rdoc-ref:StringScanner@Fixed-Anchor+Property].;TS;
;i;I"Matcher Methods;To;	;[I"�Each <i>matcher method</i> takes a single argument <code>pattern</code>,
and attempts to find a matching substring in the {target substring}[rdoc-ref:StringScanner@Target+Substring].;To;;[
I"Method;TI"Pattern Type;TI"Matches Target Substring;TI"Success Return;TI"May Update Positions?;T;[
00000;[
[
I"#check;TI"Regexp or String.;TI"At beginning.;TI"Matched substring.;TI"No.;T[
I"#check_until;TI"Regexp or String.;TI"Anywhere.;TI"Substring.;TI"No.;T[
I"#match?;TI"Regexp or String.;TI"At beginning.;TI"Match size.;TI"No.;T[
I"#exist?;TI"Regexp or String.;TI"Anywhere.;TI"Substring size.;TI"No.;T[
I"
#scan;TI"Regexp or String.;TI"At beginning.;TI"Matched substring.;TI"	Yes.;T[
I"#scan_until;TI"Regexp or String.;TI"Anywhere.;TI"Substring.;TI"	Yes.;T[
I"
#skip;TI"Regexp or String.;TI"At beginning.;TI"Match size.;TI"	Yes.;T[
I"#skip_until;TI"Regexp or String.;TI"Anywhere.;TI"Substring size.;TI"	Yes.;To;	;[I"	<br>;To;	;[I"-Which matcher you choose will depend on:;To;;;;[o;;0;[o;	;[I"$Where you want to find a match:;Fo;;;;[o;;0;[o;	;[I"SOnly at the beginning of the target substring:
 #check, #match?, #scan, #skip.;Fo;;0;[o;	;[I"XAnywhere in the target substring:
 #check_until, #exist?, #scan_until, #skip_until.;Fo;;0;[o;	;[I"Whether you want to:;Fo;;;;[o;;0;[o;	;[I"STraverse, by advancing the positions:
 #scan, #scan_until, #skip, #skip_until.;Fo;;0;[o;	;[I"KKeep the positions unchanged:
 #check, #check_until, #match?, #exist?.;Fo;;0;[o;	;[I"(What you want for the return value:;Fo;;;;[	o;;0;[o;	;[I"*The matched substring: #check, #scan.;Fo;;0;[o;	;[I".The substring: #check_until, #scan_until.;Fo;;0;[o;	;[I"$The match size: #match?, #skip.;Fo;;0;[o;	;[I".The substring size: #exist?, #skip_until.;FS;
;i;I"Match Values;To;	;[I"�The <i>match values</i> in a <code>StringScanner</code> object
generally contain the results of the most recent attempted match.;To;	;[I"+Each match value may be thought of as:;To;;;;[o;;0;[o;	;[I"_Clear_: Initially, or after an unsuccessful match attempt:
 usually, <code>false</code>, <code>nil</code>, or <code>{}</code>.;To;;0;[o;	;[I"Y_Set_: After a successful match attempt:
 <code>true</code>, string, array, or hash.;To;	;[I"/Each of these methods clears match values:;To;;;;[o;;0;[o;	;[I"::new(string).;To;;0;[o;	;[I"#reset.;To;;0;[o;	;[I"#terminate.;To;	;[I"�Each of these methods attempts a match based on a pattern,
and either sets match values (if successful) or clears them (if not);;To;;;;[
o;;0;[o;	;[I"#check(pattern);To;;0;[o;	;[I"#check_until(pattern);To;;0;[o;	;[I"#exist?(pattern);To;;0;[o;	;[I"#match?(pattern);To;;0;[o;	;[I"#scan(pattern);To;;0;[o;	;[I"#scan_until(pattern);To;;0;[o;	;[I"#skip(pattern);To;;0;[o;	;[I"#skip_until(pattern);TS;
;i	;I"Basic Match Values;To;	;[I":Basic match values are those not related to captures.;To;	;[I"7Each of these methods returns a basic match value:;To;;[I"Method;TI"Return After Match;TI"Return After No Match;T;[000;[
[I"#matched?;TI"+true+.;TI"
+false+.;T[I"#matched_size;TI"Size of matched substring.;TI"+nil+.;T[I"
#matched;TI"Matched substring.;TI"+nil+.;T[I"#pre_match;TI"+Substring preceding matched substring.;TI"+nil+.;T[I"#post_match;TI"+Substring following matched substring.;TI"+nil+.;To;	;[I"	<br>;To;	;[I"See examples below.;TS;
;i	;I"Captured Match Values;To;	;[I"�Captured match values are those related to {captures}[https://docs.ruby-lang.org/en/master/Regexp.html#class-Regexp-label-Groups+and+Captures].;To;	;[I":Each of these methods returns a captured match value:;To;;[I"Method;TI"Return After Match;TI"Return After No Match;T;[000;[
[I"
#size;TI""Count of captured substrings.;TI"+nil+.;T[I"#[](n);TI"%<tt>n</tt>th captured substring.;TI"+nil+.;T[I"#captures;TI"&Array of all captured substrings.;TI"+nil+.;T[I"#values_at(*n);TI",Array of specified captured substrings.;TI"+nil+.;T[I"#named_captures;TI"Hash of named captures.;TI"<tt>{}</tt>.;To;	;[I"	<br>;To;	;[I"See examples below.;TS;
;i	;I"Match Values Examples;To;	;[I"2Successful basic match attempt (no captures):;To;
;[I"�scanner = StringScanner.new('foobarbaz')
scanner.exist?(/bar/)
put_match_values(scanner)
# Basic match values:
#   matched?:       true
#   matched_size:   3
#   pre_match:      "foo"
#   matched  :      "bar"
#   post_match:     "baz"
# Captured match values:
#   size:           1
#   captures:       []
#   named_captures: {}
#   values_at:      ["bar", nil]
#   []:
#     [0]:          "bar"
#     [1]:          nil
;T;;o;	;[I".Failed basic match attempt (no captures);;To;
;[I"nscanner = StringScanner.new('foobarbaz')
scanner.exist?(/nope/)
match_values_cleared?(scanner) # => true
;T;;o;	;[I".Successful unnamed capture match attempt:;To;
;[I"Qscanner = StringScanner.new('foobarbazbatbam')
scanner.exist?(/(foo)bar(baz)bat(bam)/)
put_match_values(scanner)
# Basic match values:
#   matched?:       true
#   matched_size:   15
#   pre_match:      ""
#   matched  :      "foobarbazbatbam"
#   post_match:     ""
# Captured match values:
#   size:           4
#   captures:       ["foo", "baz", "bam"]
#   named_captures: {}
#   values_at:      ["foobarbazbatbam", "foo", "baz", "bam", nil]
#   []:
#     [0]:          "foobarbazbatbam"
#     [1]:          "foo"
#     [2]:          "baz"
#     [3]:          "bam"
#     [4]:          nil
;T;;o;	;[I"_Successful named capture match attempt;
same as unnamed above, except for #named_captures:;To;
;[I"�scanner = StringScanner.new('foobarbazbatbam')
scanner.exist?(/(?<x>foo)bar(?<y>baz)bat(?<z>bam)/)
scanner.named_captures # => {"x"=>"foo", "y"=>"baz", "z"=>"bam"}
;T;;o;	;[I"*Failed unnamed capture match attempt:;To;
;[I"{scanner = StringScanner.new('somestring')
scanner.exist?(/(foo)bar(baz)bat(bam)/)
match_values_cleared?(scanner) # => true
;T;;o;	;[I"[Failed named capture match attempt;
same as unnamed above, except for #named_captures:;To;
;[I"�scanner = StringScanner.new('somestring')
scanner.exist?(/(?<x>foo)bar(?<y>baz)bat(?<z>bam)/)
match_values_cleared?(scanner) # => false
scanner.named_captures # => {"x"=>nil, "y"=>nil, "z"=>nil}
;T;;S;
;i;I"Fixed-Anchor Property;To;	;[I"�Pattern matching in <code>StringScanner</code> is the same as in Ruby's,
except for its fixed-anchor property,
which determines the meaning of <code>'\A'</code>:;To;;;;[o;;0;[o;	;[I"I<code>false</code> (the default): matches the current byte position.;To;
;[I"�scanner = StringScanner.new('foobar')
scanner.scan(/\A./) # => "f"
scanner.scan(/\A./) # => "o"
scanner.scan(/\A./) # => "o"
scanner.scan(/\A./) # => "b"
;F;;o;;0;[o;	;[I"w<code>true</code>: matches the beginning of the target substring;
 never matches unless the byte position is zero:;To;
;[I"�scanner = StringScanner.new('foobar', fixed_anchor: true)
scanner.scan(/\A./) # => "f"
scanner.scan(/\A./) # => nil
scanner.reset
scanner.scan(/\A./) # => "f"
;F;;o;	;[I"�The fixed-anchor property is set when the <code>StringScanner</code> object is created,
and may not be modified
(see StringScanner.new);
method #fixed_anchor? returns the setting.;T:
@fileI"ext/strscan/strscan.c;T:0@omit_headings_from_table_of_contents_below0;0;0[�[�[�[[I"
class;T[[:public[[I"new;TI"ext/strscan/strscan.c;T[:protected[�[:private[�[I"
instance;T[[;[.[I"<<;T@p[I"[];T@p[I"beginning_of_line?;T@p[I"
captures;T@p[I"charpos;T@p[I"
check;T@p[I"check_until;T@p[I"concat;T@p[I"	eos?;T@p[I"exist?;T@p[I"fixed_anchor?;T@p[I"
get_byte;T@p[I"
getch;T@p[I"inspect;T@p[I"match?;T@p[I"matched;T@p[I"
matched?;T@p[I"matched_size;T@p[I"named_captures;T@p[I"	peek;T@p[I"peek_byte;T@p[I"pointer;T@p[I"
pointer=;T@p[I"pos;T@p[I"	pos=;T@p[I"post_match;T@p[I"pre_match;T@p[I"
reset;T@p[I"	rest;T@p[I"rest_size;T@p[I"	scan;T@p[I"scan_byte;T@p[I"scan_until;T@p[I"	size;T@p[I"	skip;T@p[I"skip_until;T@p[I"string;T@p[I"string=;T@p[I"terminate;T@p[I"unscan;T@p[I"values_at;T@p[;[�[;[[I"initialize_copy;T@p[I"scan_base10_integer;T@p[I"scan_base16_integer;T@p[�[U:RDoc::Context::Section[i�0o;;[�;0;0[@d@dcRDoc::TopLevel