Class: StringScanner
- Inherits:
-
Object
- Object
- StringScanner
- Defined in:
- ext/strscan/strscan.c,
ext/strscan/strscan.c
Overview
StringScanner provides for lexical scanning operations on a String. Here is an example of its usage:
require 'strscan'
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
-
#get_byte
-
#scan
-
#scan_until
-
#skip
-
#skip_until
Looking Ahead
-
#check
-
#check_until
-
#exist?
-
#match?
-
#peek
Finding Where we Are
-
#beginning_of_line? (
#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.
Defined Under Namespace
Classes: Error
Class Method Summary collapse
-
.must_C_version ⇒ Object
This method is defined for backward compatibility.
Instance Method Summary collapse
-
#<<(str) ⇒ Object
Appends
str
to the string being scanned. -
#[](n) ⇒ Object
Returns the n-th subgroup in the most recent match.
-
#beginning_of_line? ⇒ Boolean
Returns
true
if and only if the scan pointer is at the beginning of the line. -
#captures ⇒ Object
Returns the subgroups in the most recent match (not including the full match).
-
#charpos ⇒ Object
Returns the character position of the scan pointer.
-
#check(pattern) ⇒ Object
This returns the value that #scan would return, without advancing the scan pointer.
-
#check_until(pattern) ⇒ Object
This returns the value that #scan_until would return, without advancing the scan pointer.
-
#clear ⇒ Object
Equivalent to #terminate.
-
#concat(str) ⇒ Object
Appends
str
to the string being scanned. -
#empty? ⇒ Boolean
Equivalent to #eos?.
-
#eos? ⇒ Boolean
Returns
true
if the scan pointer is at the end of the string. -
#exist?(pattern) ⇒ Boolean
Looks ahead to see if the
pattern
exists anywhere in the string, without advancing the scan pointer. -
#fixed_anchor? ⇒ Boolean
Whether
scanner
uses fixed anchor mode or not. -
#get_byte ⇒ Object
Scans one byte and returns it.
-
#getbyte ⇒ Object
Equivalent to #get_byte.
-
#getch ⇒ Object
Scans one character and returns it.
-
#inspect ⇒ Object
Returns a string that represents the StringScanner object, showing: - the current position - the size of the string - the characters surrounding the scan pointer.
-
#match?(pattern) ⇒ Boolean
Tests whether the given
pattern
is matched from the current scan pointer. -
#matched ⇒ Object
Returns the last matched string.
-
#matched? ⇒ Boolean
Returns
true
if and only if the last match was successful. -
#matched_size ⇒ Object
Returns the size of the most recent match in bytes, or
nil
if there was no recent match. -
#named_captures ⇒ Hash
Returns a hash of string variables matching the regular expression.
-
#peek(len) ⇒ Object
Extracts a string corresponding to
string[pos,len]
, without advancing the scan pointer. -
#peep(vlen) ⇒ Object
Equivalent to #peek.
-
#pointer ⇒ Object
Returns the byte position of the scan pointer.
-
#pos=(n) ⇒ Object
Sets the byte position of the scan pointer.
-
#pos ⇒ Object
Returns the byte position of the scan pointer.
-
#pos=(n) ⇒ Object
Sets the byte position of the scan pointer.
-
#post_match ⇒ Object
Returns the post-match (in the regular expression sense) of the last scan.
-
#pre_match ⇒ Object
Returns the pre-match (in the regular expression sense) of the last scan.
-
#reset ⇒ Object
Reset the scan pointer (index 0) and clear matching data.
-
#rest ⇒ Object
Returns the “rest” of the string (i.e. everything after the scan pointer).
-
#rest? ⇒ Boolean
Returns true if and only if there is more data in the string.
-
#rest_size ⇒ Object
s.rest_size
is equivalent tos.rest.size
. -
#restsize ⇒ Object
s.restsize
is equivalent tos.rest_size
. -
#scan(pattern) ⇒ String
Tries to match with
pattern
at the current position. -
#scan_full(pattern, advance_pointer_p, return_string_p) ⇒ Object
Tests whether the given
pattern
is matched from the current scan pointer. -
#scan_until(pattern) ⇒ Object
Scans the string until the
pattern
is matched. -
#search_full(pattern, advance_pointer_p, return_string_p) ⇒ Object
Scans the string until the
pattern
is matched. -
#size ⇒ Object
Returns the amount of subgroups in the most recent match.
-
#skip(pattern) ⇒ Object
Attempts to skip over the given
pattern
beginning with the scan pointer. -
#skip_until(pattern) ⇒ Object
Advances the scan pointer until
pattern
is matched and consumed. -
#string ⇒ Object
Returns the string being scanned.
-
#string=(str) ⇒ Object
Changes the string being scanned to
str
and resets the scanner. -
#terminate ⇒ Object
Sets the scan pointer to the end of the string and clear matching data.
-
#unscan ⇒ Object
Sets the scan pointer to the previous position.
-
#values_at(i1, i2, ...iN) ⇒ Array
Returns the subgroups in the most recent match at the given indices.
Class Method Details
.must_C_version ⇒ Object
This method is defined for backward compatibility.
304 305 306 307 308 |
# File 'ext/strscan/strscan.c', line 304
static VALUE
strscan_s_mustc(VALUE self)
{
return self;
}
|
Instance Method Details
#concat(str) ⇒ Object #<<(str) ⇒ Object
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"
397 398 399 400 401 402 403 404 405 406 |
# File 'ext/strscan/strscan.c', line 397
static VALUE
strscan_concat(VALUE self, VALUE str)
{
struct strscanner *p;
GET_SCANNER(self, p);
StringValue(str);
rb_str_append(p->str, str);
return self;
}
|
#[](n) ⇒ Object
Returns 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 # -> ""
s.reset
s.scan(/(?<wday>\w+) (?<month>\w+) (?<day>\d+) /) # -> "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"
s.post_match # -> "1975 14:39"
s.pre_match # -> ""
1185 1186 1187 1188 1189 1190 1191 1192 1193 1194 1195 1196 1197 1198 1199 1200 1201 1202 1203 1204 1205 1206 1207 1208 1209 1210 1211 1212 1213 1214 1215 1216 1217 |
# File 'ext/strscan/strscan.c', line 1185
static VALUE
strscan_aref(VALUE self, VALUE idx)
{
const char *name;
struct strscanner *p;
long i;
GET_SCANNER(self, p);
if (! MATCHED_P(p)) return Qnil;
switch (TYPE(idx)) {
case T_SYMBOL:
idx = rb_sym2str(idx);
/* fall through */
case T_STRING:
if (!RTEST(p->regex)) return Qnil;
RSTRING_GETMEM(idx, name, i);
i = name_to_backref_number(&(p->regs), p->regex, name, name + i, rb_enc_get(idx));
break;
default:
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,
adjust_register_position(p, p->regs.beg[i]),
adjust_register_position(p, p->regs.end[i]));
}
|
#beginning_of_line? ⇒ Boolean
Returns true
if and only if 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
1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 |
# File 'ext/strscan/strscan.c', line 1024
static VALUE
strscan_bol_p(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;
}
|
#captures ⇒ Object
Returns the subgroups in the most recent match (not including the full match). If nothing was priorly matched, it returns nil.
s = StringScanner.new("Fri Dec 12 1975 14:39")
s.scan(/(\w+) (\w+) (\d+) (1980)?/) # -> "Fri Dec 12 "
s.captures # -> ["Fri", "Dec", "12", nil]
s.scan(/(\w+) (\w+) (\d+) (1980)?/) # -> nil
s.captures # -> nil
1251 1252 1253 1254 1255 1256 1257 1258 1259 1260 1261 1262 1263 1264 1265 1266 1267 1268 1269 1270 1271 1272 1273 1274 1275 1276 |
# File 'ext/strscan/strscan.c', line 1251
static VALUE
strscan_captures(VALUE self)
{
struct strscanner *p;
int i, num_regs;
VALUE new_ary;
GET_SCANNER(self, p);
if (! MATCHED_P(p)) return Qnil;
num_regs = p->regs.num_regs;
new_ary = rb_ary_new2(num_regs);
for (i = 1; i < num_regs; i++) {
VALUE str;
if (p->regs.beg[i] == -1)
str = Qnil;
else
str = extract_range(p,
adjust_register_position(p, p->regs.beg[i]),
adjust_register_position(p, p->regs.end[i]));
rb_ary_push(new_ary, str);
}
return new_ary;
}
|
#charpos ⇒ Object
Returns the character 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 size of the string.
In short, it’s a 0-based index into the string.
s = StringScanner.new("abc\u00e4def\u00f6ghi")
s.charpos # -> 0
s.scan_until(/\u00e4/) # -> "abc\u00E4"
s.pos # -> 5
s.charpos # -> 4
444 445 446 447 448 449 450 451 452 |
# File 'ext/strscan/strscan.c', line 444
static VALUE
strscan_get_charpos(VALUE self)
{
struct strscanner *p;
GET_SCANNER(self, p);
return LONG2NUM(rb_enc_strlen(S_PBEG(p), CURPTR(p), rb_enc_get(p->str)));
}
|
#check(pattern) ⇒ Object
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.
743 744 745 746 747 |
# File 'ext/strscan/strscan.c', line 743
static VALUE
strscan_check(VALUE self, VALUE re)
{
return strscan_do_scan(self, re, 0, 1, 1);
}
|
#check_until(pattern) ⇒ Object
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.
837 838 839 840 841 |
# File 'ext/strscan/strscan.c', line 837
static VALUE
strscan_check_until(VALUE self, VALUE re)
{
return strscan_do_scan(self, re, 0, 1, 0);
}
|
#clear ⇒ Object
Equivalent to #terminate. This method is obsolete; use #terminate instead.
346 347 348 349 350 351 |
# File 'ext/strscan/strscan.c', line 346
static VALUE
strscan_clear(VALUE self)
{
rb_warning("StringScanner#clear is obsolete; use #terminate instead");
return strscan_terminate(self);
}
|
#concat(str) ⇒ Object #<<(str) ⇒ Object
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"
397 398 399 400 401 402 403 404 405 406 |
# File 'ext/strscan/strscan.c', line 397
static VALUE
strscan_concat(VALUE self, VALUE str)
{
struct strscanner *p;
GET_SCANNER(self, p);
StringValue(str);
rb_str_append(p->str, str);
return self;
}
|
#empty? ⇒ Boolean
Equivalent to #eos?. This method is obsolete, use #eos? instead.
1058 1059 1060 1061 1062 1063 |
# File 'ext/strscan/strscan.c', line 1058
static VALUE
strscan_empty_p(VALUE self)
{
rb_warning("StringScanner#empty? is obsolete; use #eos? instead");
return strscan_eos_p(self);
}
|
#eos? ⇒ Boolean
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
1045 1046 1047 1048 1049 1050 1051 1052 |
# File 'ext/strscan/strscan.c', line 1045
static VALUE
strscan_eos_p(VALUE self)
{
struct strscanner *p;
GET_SCANNER(self, p);
return EOS_P(p) ? Qtrue : Qfalse;
}
|
#exist?(pattern) ⇒ Boolean
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/ # -> 2
s.exist? /e/ # -> nil
796 797 798 799 800 |
# File 'ext/strscan/strscan.c', line 796
static VALUE
strscan_exist_p(VALUE self, VALUE re)
{
return strscan_do_scan(self, re, 0, 0, 0);
}
|
#fixed_anchor? ⇒ Boolean
Whether scanner
uses fixed anchor mode or not.
If fixed anchor mode is used, \A
always matches the beginning of the string. Otherwise, \A
always matches the current position.
1487 1488 1489 1490 1491 1492 1493 |
# File 'ext/strscan/strscan.c', line 1487
static VALUE
strscan_fixed_anchor_p(VALUE self)
{
struct strscanner *p;
p = check_strscan(self);
return p->fixed_anchor_p ? Qtrue : Qfalse;
}
|
#get_byte ⇒ Object
Scans one byte and returns it. This method is not multibyte 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".force_encoding("euc-jp"))
s.get_byte # => "\xA4"
s.get_byte # => "\xA2"
s.get_byte # => nil
920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 |
# File 'ext/strscan/strscan.c', line 920
static VALUE
strscan_get_byte(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,
adjust_register_position(p, p->regs.beg[0]),
adjust_register_position(p, p->regs.end[0]));
}
|
#getbyte ⇒ Object
Equivalent to #get_byte. This method is obsolete; use #get_byte instead.
943 944 945 946 947 948 |
# File 'ext/strscan/strscan.c', line 943
static VALUE
strscan_getbyte(VALUE self)
{
rb_warning("StringScanner#getbyte is obsolete; use #get_byte instead");
return strscan_get_byte(self);
}
|
#getch ⇒ Object
Scans one character and returns it. This method is multibyte character sensitive.
s = StringScanner.new("ab")
s.getch # => "a"
s.getch # => "b"
s.getch # => nil
s = StringScanner.new("\244\242".force_encoding("euc-jp"))
s.getch # => "\x{A4A2}" # Japanese hira-kana "A" in EUC-JP
s.getch # => nil
883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 |
# File 'ext/strscan/strscan.c', line 883
static VALUE
strscan_getch(VALUE self)
{
struct strscanner *p;
long len;
GET_SCANNER(self, p);
CLEAR_MATCH_STATUS(p);
if (EOS_P(p))
return Qnil;
len = rb_enc_mbclen(CURPTR(p), S_PEND(p), rb_enc_get(p->str));
len = minl(len, S_RESTLEN(p));
p->prev = p->curr;
p->curr += len;
MATCHED(p);
adjust_registers_to_matched(p);
return extract_range(p,
adjust_register_position(p, p->regs.beg[0]),
adjust_register_position(p, p->regs.end[0]));
}
|
#inspect ⇒ Object
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…”>’
1409 1410 1411 1412 1413 1414 1415 1416 1417 1418 1419 1420 1421 1422 1423 1424 1425 1426 1427 1428 1429 1430 1431 1432 1433 1434 1435 1436 1437 1438 1439 |
# File 'ext/strscan/strscan.c', line 1409
static VALUE
strscan_inspect(VALUE self)
{
struct strscanner *p;
VALUE a, b;
p = check_strscan(self);
if (NIL_P(p->str)) {
a = rb_sprintf("#<%"PRIsVALUE" (uninitialized)>", rb_obj_class(self));
return a;
}
if (EOS_P(p)) {
a = rb_sprintf("#<%"PRIsVALUE" fin>", rb_obj_class(self));
return a;
}
if (p->curr == 0) {
b = inspect2(p);
a = rb_sprintf("#<%"PRIsVALUE" %ld/%ld @ %"PRIsVALUE">",
rb_obj_class(self),
p->curr, S_LEN(p),
b);
return a;
}
a = inspect1(p);
b = inspect2(p);
a = rb_sprintf("#<%"PRIsVALUE" %ld/%ld %"PRIsVALUE" @ %"PRIsVALUE">",
rb_obj_class(self),
p->curr, S_LEN(p),
a, b);
return a;
}
|
#match?(pattern) ⇒ Boolean
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?("test") # -> 4
p s.match?(/\s+/) # -> nil
698 699 700 701 702 |
# File 'ext/strscan/strscan.c', line 698
static VALUE
strscan_match_p(VALUE self, VALUE re)
{
return strscan_do_scan(self, re, 0, 0, 1);
}
|
#matched ⇒ Object
Returns the last matched string.
s = StringScanner.new('test string')
s.match?(/\w+/) # -> 4
s.matched # -> "test"
1108 1109 1110 1111 1112 1113 1114 1115 1116 1117 1118 |
# File 'ext/strscan/strscan.c', line 1108
static VALUE
strscan_matched(VALUE self)
{
struct strscanner *p;
GET_SCANNER(self, p);
if (! MATCHED_P(p)) return Qnil;
return extract_range(p,
adjust_register_position(p, p->regs.beg[0]),
adjust_register_position(p, p->regs.end[0]));
}
|
#matched? ⇒ Boolean
Returns true
if and only if the last match was successful.
s = StringScanner.new('test string')
s.match?(/\w+/) # => 4
s.matched? # => true
s.match?(/\d+/) # => nil
s.matched? # => false
1092 1093 1094 1095 1096 1097 1098 1099 |
# File 'ext/strscan/strscan.c', line 1092
static VALUE
strscan_matched_p(VALUE self)
{
struct strscanner *p;
GET_SCANNER(self, p);
return MATCHED_P(p) ? Qtrue : Qfalse;
}
|
#matched_size ⇒ Object
Returns the size of the most recent match in bytes, or nil
if there was no recent match. This is different than matched.size
, which will return the size in characters.
s = StringScanner.new('test string')
s.check /\w+/ # -> "test"
s.matched_size # -> 4
s.check /\d+/ # -> nil
s.matched_size # -> nil
1131 1132 1133 1134 1135 1136 1137 1138 1139 |
# File 'ext/strscan/strscan.c', line 1131
static VALUE
strscan_matched_size(VALUE self)
{
struct strscanner *p;
GET_SCANNER(self, p);
if (! MATCHED_P(p)) return Qnil;
return LONG2NUM(p->regs.end[0] - p->regs.beg[0]);
}
|
#named_captures ⇒ Hash
Returns a hash of string variables matching the regular expression.
scan = StringScanner.new('foobarbaz')
scan.match?(/(?<f>foo)(?<r>bar)(?<z>baz)/)
scan.named_captures # -> {"f"=>"foo", "r"=>"bar", "z"=>"baz"}
1530 1531 1532 1533 1534 1535 1536 1537 1538 1539 1540 1541 1542 1543 |
# File 'ext/strscan/strscan.c', line 1530
static VALUE
strscan_named_captures(VALUE self)
{
struct strscanner *p;
GET_SCANNER(self, p);
named_captures_data data;
data.self = self;
data.captures = rb_hash_new();
if (!RB_NIL_P(p->regex)) {
onig_foreach_name(RREGEXP_PTR(p->regex), named_captures_iter, &data);
}
return data.captures;
}
|
#peek(len) ⇒ Object
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"
961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 |
# File 'ext/strscan/strscan.c', line 961
static VALUE
strscan_peek(VALUE self, VALUE vlen)
{
struct strscanner *p;
long len;
GET_SCANNER(self, p);
len = NUM2LONG(vlen);
if (EOS_P(p))
return str_new(p, "", 0);
len = minl(len, S_RESTLEN(p));
return extract_beg_len(p, p->curr, len);
}
|
#peep(vlen) ⇒ Object
Equivalent to #peek. This method is obsolete; use #peek instead.
981 982 983 984 985 986 |
# File 'ext/strscan/strscan.c', line 981
static VALUE
strscan_peep(VALUE self, VALUE vlen)
{
rb_warning("StringScanner#peep is obsolete; use #peek instead");
return strscan_peek(self, vlen);
}
|
#pointer ⇒ Object
Returns the byte 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 bytesize of the string.
In short, it’s a 0-based index into bytes of 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
422 423 424 425 426 427 428 429 |
# File 'ext/strscan/strscan.c', line 422
static VALUE
strscan_get_pos(VALUE self)
{
struct strscanner *p;
GET_SCANNER(self, p);
return INT2FIX(p->curr);
}
|
#pos=(n) ⇒ Object
Sets the byte position of the scan pointer.
s = StringScanner.new('test string')
s.pos = 7 # -> 7
s.rest # -> "ring"
463 464 465 466 467 468 469 470 471 472 473 474 475 476 |
# File 'ext/strscan/strscan.c', line 463
static VALUE
strscan_set_pos(VALUE self, VALUE 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 LONG2NUM(i);
}
|
#pos ⇒ Object
Returns the byte 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 bytesize of the string.
In short, it’s a 0-based index into bytes of 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
422 423 424 425 426 427 428 429 |
# File 'ext/strscan/strscan.c', line 422
static VALUE
strscan_get_pos(VALUE self)
{
struct strscanner *p;
GET_SCANNER(self, p);
return INT2FIX(p->curr);
}
|
#pos=(n) ⇒ Object
Sets the byte position of the scan pointer.
s = StringScanner.new('test string')
s.pos = 7 # -> 7
s.rest # -> "ring"
463 464 465 466 467 468 469 470 471 472 473 474 475 476 |
# File 'ext/strscan/strscan.c', line 463
static VALUE
strscan_set_pos(VALUE self, VALUE 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 LONG2NUM(i);
}
|
#post_match ⇒ Object
Returns 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"
1340 1341 1342 1343 1344 1345 1346 1347 1348 1349 1350 |
# File 'ext/strscan/strscan.c', line 1340
static VALUE
strscan_post_match(VALUE self)
{
struct strscanner *p;
GET_SCANNER(self, p);
if (! MATCHED_P(p)) return Qnil;
return extract_range(p,
adjust_register_position(p, p->regs.end[0]),
S_LEN(p));
}
|
#pre_match ⇒ Object
Returns 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"
1319 1320 1321 1322 1323 1324 1325 1326 1327 1328 1329 |
# File 'ext/strscan/strscan.c', line 1319
static VALUE
strscan_pre_match(VALUE self)
{
struct strscanner *p;
GET_SCANNER(self, p);
if (! MATCHED_P(p)) return Qnil;
return extract_range(p,
0,
adjust_register_position(p, p->regs.beg[0]));
}
|
#reset ⇒ Object
Reset the scan pointer (index 0) and clear matching data.
313 314 315 316 317 318 319 320 321 322 |
# File 'ext/strscan/strscan.c', line 313
static VALUE
strscan_reset(VALUE self)
{
struct strscanner *p;
GET_SCANNER(self, p);
p->curr = 0;
CLEAR_MATCH_STATUS(p);
return self;
}
|
#rest ⇒ Object
Returns the “rest” of the string (i.e. everything after the scan pointer). If there is no more data (eos? = true), it returns ""
.
1356 1357 1358 1359 1360 1361 1362 1363 1364 1365 1366 |
# File 'ext/strscan/strscan.c', line 1356
static VALUE
strscan_rest(VALUE self)
{
struct strscanner *p;
GET_SCANNER(self, p);
if (EOS_P(p)) {
return str_new(p, "", 0);
}
return extract_range(p, p->curr, S_LEN(p));
}
|
#rest? ⇒ Boolean
Returns true if and only if there is more data in the string. See #eos?. This method is obsolete; use #eos? instead.
s = StringScanner.new('test string')
# These two are opposites
s.eos? # => false
s.rest? # => true
1074 1075 1076 1077 1078 1079 1080 1081 |
# File 'ext/strscan/strscan.c', line 1074
static VALUE
strscan_rest_p(VALUE self)
{
struct strscanner *p;
GET_SCANNER(self, p);
return EOS_P(p) ? Qfalse : Qtrue;
}
|
#rest_size ⇒ Object
s.rest_size
is equivalent to s.rest.size
.
1371 1372 1373 1374 1375 1376 1377 1378 1379 1380 1381 1382 1383 |
# File 'ext/strscan/strscan.c', line 1371
static VALUE
strscan_rest_size(VALUE self)
{
struct strscanner *p;
long i;
GET_SCANNER(self, p);
if (EOS_P(p)) {
return INT2FIX(0);
}
i = S_RESTLEN(p);
return INT2FIX(i);
}
|
#restsize ⇒ Object
s.restsize
is equivalent to s.rest_size
. This method is obsolete; use #rest_size instead.
1389 1390 1391 1392 1393 1394 |
# File 'ext/strscan/strscan.c', line 1389
static VALUE
strscan_restsize(VALUE self)
{
rb_warning("StringScanner#restsize is obsolete; use #rest_size instead");
return strscan_rest_size(self);
}
|
#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("str") # -> "str"
p s.scan(/\w+/) # -> "ing"
p s.scan(/./) # -> nil
680 681 682 683 684 |
# File 'ext/strscan/strscan.c', line 680
static VALUE
strscan_scan(VALUE self, VALUE re)
{
return strscan_do_scan(self, re, 1, 1, 1);
}
|
#scan_full(pattern, advance_pointer_p, return_string_p) ⇒ Object
Tests whether the given pattern
is matched from the current scan pointer. Advances the scan pointer if advance_pointer_p
is true. Returns the matched string if return_string_p
is true. The match register is affected.
“full” means “#scan with full parameters”.
759 760 761 762 763 |
# File 'ext/strscan/strscan.c', line 759
static VALUE
strscan_scan_full(VALUE self, VALUE re, VALUE s, VALUE f)
{
return strscan_do_scan(self, re, RTEST(s), RTEST(f), 1);
}
|
#scan_until(pattern) ⇒ Object
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
777 778 779 780 781 |
# File 'ext/strscan/strscan.c', line 777
static VALUE
strscan_scan_until(VALUE self, VALUE re)
{
return strscan_do_scan(self, re, 1, 1, 0);
}
|
#search_full(pattern, advance_pointer_p, return_string_p) ⇒ Object
Scans the string until the pattern
is matched. Advances the scan pointer if advance_pointer_p
, otherwise not. Returns the matched string if return_string_p
is true, otherwise returns the number of bytes advanced. This method does affect the match register.
852 853 854 855 856 |
# File 'ext/strscan/strscan.c', line 852
static VALUE
strscan_search_full(VALUE self, VALUE re, VALUE s, VALUE f)
{
return strscan_do_scan(self, re, RTEST(s), RTEST(f), 0);
}
|
#size ⇒ Object
Returns the amount of subgroups in the most recent match. The full match counts as a subgroup.
s = StringScanner.new("Fri Dec 12 1975 14:39")
s.scan(/(\w+) (\w+) (\d+) /) # -> "Fri Dec 12 "
s.size # -> 4
1229 1230 1231 1232 1233 1234 1235 1236 1237 |
# File 'ext/strscan/strscan.c', line 1229
static VALUE
strscan_size(VALUE self)
{
struct strscanner *p;
GET_SCANNER(self, p);
if (! MATCHED_P(p)) return Qnil;
return INT2FIX(p->regs.num_regs);
}
|
#skip(pattern) ⇒ Object
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("st") # -> 2
p s.skip(/\w+/) # -> 4
p s.skip(/./) # -> nil
722 723 724 725 726 |
# File 'ext/strscan/strscan.c', line 722
static VALUE
strscan_skip(VALUE self, VALUE re)
{
return strscan_do_scan(self, re, 1, 0, 1);
}
|
#skip_until(pattern) ⇒ Object
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 #
818 819 820 821 822 |
# File 'ext/strscan/strscan.c', line 818
static VALUE
strscan_skip_until(VALUE self, VALUE re)
{
return strscan_do_scan(self, re, 1, 0, 0);
}
|
#string ⇒ Object
Returns the string being scanned.
356 357 358 359 360 361 362 363 |
# File 'ext/strscan/strscan.c', line 356
static VALUE
strscan_get_string(VALUE self)
{
struct strscanner *p;
GET_SCANNER(self, p);
return p->str;
}
|
#string=(str) ⇒ Object
Changes the string being scanned to str
and resets the scanner. Returns str
.
371 372 373 374 375 376 377 378 379 380 381 |
# File 'ext/strscan/strscan.c', line 371
static VALUE
strscan_set_string(VALUE self, VALUE str)
{
struct strscanner *p = check_strscan(self);
StringValue(str);
p->str = str;
p->curr = 0;
CLEAR_MATCH_STATUS(p);
return str;
}
|
#terminate ⇒ Object #clear ⇒ Object
Sets the scan pointer to the end of the string and clear matching data.
331 332 333 334 335 336 337 338 339 340 |
# File 'ext/strscan/strscan.c', line 331
static VALUE
strscan_terminate(VALUE self)
{
struct strscanner *p;
GET_SCANNER(self, p);
p->curr = S_LEN(p);
CLEAR_MATCH_STATUS(p);
return self;
}
|
#unscan ⇒ Object
Sets 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 record not exist
999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 |
# File 'ext/strscan/strscan.c', line 999
static VALUE
strscan_unscan(VALUE self)
{
struct strscanner *p;
GET_SCANNER(self, p);
if (! MATCHED_P(p))
rb_raise(ScanError, "unscan failed: previous match record not exist");
p->curr = p->prev;
CLEAR_MATCH_STATUS(p);
return self;
}
|
#values_at(i1, i2, ...iN) ⇒ Array
Returns the subgroups in the most recent match at the given indices. If nothing was priorly matched, it returns nil.
s = StringScanner.new("Fri Dec 12 1975 14:39")
s.scan(/(\w+) (\w+) (\d+) /) # -> "Fri Dec 12 "
s.values_at 0, -1, 5, 2 # -> ["Fri Dec 12 ", "12", nil, "Dec"]
s.scan(/(\w+) (\w+) (\d+) /) # -> nil
s.values_at 0, -1, 5, 2 # -> nil
1292 1293 1294 1295 1296 1297 1298 1299 1300 1301 1302 1303 1304 1305 1306 1307 1308 |
# File 'ext/strscan/strscan.c', line 1292
static VALUE
strscan_values_at(int argc, VALUE *argv, VALUE self)
{
struct strscanner *p;
long i;
VALUE new_ary;
GET_SCANNER(self, p);
if (! MATCHED_P(p)) return Qnil;
new_ary = rb_ary_new2(argc);
for (i = 0; i<argc; i++) {
rb_ary_push(new_ary, strscan_aref(self, argv[i]));
}
return new_ary;
}
|