summaryrefslogtreecommitdiff
path: root/doc/strscan/methods
diff options
context:
space:
mode:
Diffstat (limited to 'doc/strscan/methods')
-rw-r--r--doc/strscan/methods/get_byte.md27
-rw-r--r--doc/strscan/methods/get_charpos.md16
-rw-r--r--doc/strscan/methods/get_pos.md11
-rw-r--r--doc/strscan/methods/getch.md40
-rw-r--r--doc/strscan/methods/scan.md48
-rw-r--r--doc/strscan/methods/scan_until.md49
-rw-r--r--doc/strscan/methods/set_pos.md23
-rw-r--r--doc/strscan/methods/skip.md40
-rw-r--r--doc/strscan/methods/skip_until.md48
-rw-r--r--doc/strscan/methods/terminate.md27
10 files changed, 329 insertions, 0 deletions
diff --git a/doc/strscan/methods/get_byte.md b/doc/strscan/methods/get_byte.md
new file mode 100644
index 0000000000..775226638e
--- /dev/null
+++ b/doc/strscan/methods/get_byte.md
@@ -0,0 +1,27 @@
+Returns the next byte, if available:
+
+- If the [position][2]
+ is not at the end of the [stored string][1]:
+
+ - Returns the next byte.
+ - Increments the [byte position][2].
+ - Adjusts the [character position][7].
+
+ ```rb
+ scanner = StringScanner.new(HIRAGANA_TEXT)
+ # => #<StringScanner 0/15 @ "\xE3\x81\x93\xE3\x82...">
+ scanner.string # => "こんにちは"
+ [scanner.get_byte, scanner.pos, scanner.charpos] # => ["\xE3", 1, 1]
+ [scanner.get_byte, scanner.pos, scanner.charpos] # => ["\x81", 2, 2]
+ [scanner.get_byte, scanner.pos, scanner.charpos] # => ["\x93", 3, 1]
+ [scanner.get_byte, scanner.pos, scanner.charpos] # => ["\xE3", 4, 2]
+ [scanner.get_byte, scanner.pos, scanner.charpos] # => ["\x82", 5, 3]
+ [scanner.get_byte, scanner.pos, scanner.charpos] # => ["\x93", 6, 2]
+ ```
+
+- Otherwise, returns `nil`, and does not change the positions.
+
+ ```rb
+ scanner.terminate
+ [scanner.get_byte, scanner.pos, scanner.charpos] # => [nil, 15, 5]
+ ```
diff --git a/doc/strscan/methods/get_charpos.md b/doc/strscan/methods/get_charpos.md
new file mode 100644
index 0000000000..4de07897dc
--- /dev/null
+++ b/doc/strscan/methods/get_charpos.md
@@ -0,0 +1,16 @@
+Returns the [character position][7] (initially zero),
+which may be different from the [byte position][2]
+given by method #pos:
+
+```rb
+scanner = StringScanner.new(HIRAGANA_TEXT)
+scanner.string # => "こんにちは"
+scanner.getch # => "こ" # 3-byte character.
+scanner.getch # => "ん" # 3-byte character.
+put_situation(scanner)
+# Situation:
+# pos: 6
+# charpos: 2
+# rest: "にちは"
+# rest_size: 9
+```
diff --git a/doc/strscan/methods/get_pos.md b/doc/strscan/methods/get_pos.md
new file mode 100644
index 0000000000..56b1636812
--- /dev/null
+++ b/doc/strscan/methods/get_pos.md
@@ -0,0 +1,11 @@
+Returns the integer [byte position][2],
+which may be different from the [character position][7]:
+
+```rb
+scanner = StringScanner.new(HIRAGANA_TEXT)
+scanner.string # => "こんにちは"
+scanner.pos # => 0
+scanner.getch # => "こ" # 3-byte character.
+scanner.charpos # => 1
+scanner.pos # => 3
+```
diff --git a/doc/strscan/methods/getch.md b/doc/strscan/methods/getch.md
new file mode 100644
index 0000000000..ede1d2b071
--- /dev/null
+++ b/doc/strscan/methods/getch.md
@@ -0,0 +1,40 @@
+Returns the next (possibly multibyte) character,
+if available:
+
+- If the [position][2]
+ is at the beginning of a character:
+
+ - Returns the character.
+ - Increments the [character position][7] by 1.
+ - Increments the [byte position][2]
+ by the size (in bytes) of the character.
+
+ ```rb
+ scanner = StringScanner.new(HIRAGANA_TEXT)
+ scanner.string # => "こんにちは"
+ [scanner.getch, scanner.pos, scanner.charpos] # => ["こ", 3, 1]
+ [scanner.getch, scanner.pos, scanner.charpos] # => ["ん", 6, 2]
+ [scanner.getch, scanner.pos, scanner.charpos] # => ["に", 9, 3]
+ [scanner.getch, scanner.pos, scanner.charpos] # => ["ち", 12, 4]
+ [scanner.getch, scanner.pos, scanner.charpos] # => ["は", 15, 5]
+ [scanner.getch, scanner.pos, scanner.charpos] # => [nil, 15, 5]
+ ```
+
+- If the [position][2] is within a multi-byte character
+ (that is, not at its beginning),
+ behaves like #get_byte (returns a 1-byte character):
+
+ ```rb
+ scanner.pos = 1
+ [scanner.getch, scanner.pos, scanner.charpos] # => ["\x81", 2, 2]
+ [scanner.getch, scanner.pos, scanner.charpos] # => ["\x93", 3, 1]
+ [scanner.getch, scanner.pos, scanner.charpos] # => ["ん", 6, 2]
+ ```
+
+- If the [position][2] is at the end of the [stored string][1],
+ returns `nil` and does not modify the positions:
+
+ ```rb
+ scanner.terminate
+ [scanner.getch, scanner.pos, scanner.charpos] # => [nil, 15, 5]
+ ```
diff --git a/doc/strscan/methods/scan.md b/doc/strscan/methods/scan.md
new file mode 100644
index 0000000000..805c797913
--- /dev/null
+++ b/doc/strscan/methods/scan.md
@@ -0,0 +1,48 @@
+Attempts to [match][17] the given `pattern`
+at the beginning of the [target substring][3].
+
+If the match succeeds:
+
+- Returns the matched substring.
+- Increments the [byte position][2] by <tt>substring.bytesize</tt>,
+ and may increment the [character position][7].
+- Sets [match values][9].
+
+```rb
+scanner = StringScanner.new(HIRAGANA_TEXT)
+scanner.string # => "こんにちは"
+scanner.pos = 6
+scanner.scan(/に/) # => "に"
+put_match_values(scanner)
+# Basic match values:
+# matched?: true
+# matched_size: 3
+# pre_match: "こん"
+# matched : "に"
+# post_match: "ちは"
+# Captured match values:
+# size: 1
+# captures: []
+# named_captures: {}
+# values_at: ["に", nil]
+# []:
+# [0]: "に"
+# [1]: nil
+put_situation(scanner)
+# Situation:
+# pos: 9
+# charpos: 3
+# rest: "ちは"
+# rest_size: 6
+```
+
+If the match fails:
+
+- Returns `nil`.
+- Does not increment byte and character positions.
+- Clears match values.
+
+```rb
+scanner.scan(/nope/) # => nil
+match_values_cleared?(scanner) # => true
+```
diff --git a/doc/strscan/methods/scan_until.md b/doc/strscan/methods/scan_until.md
new file mode 100644
index 0000000000..5fb2912a1b
--- /dev/null
+++ b/doc/strscan/methods/scan_until.md
@@ -0,0 +1,49 @@
+Attempts to [match][17] the given `pattern`
+anywhere (at any [position][2]) in the [target substring][3].
+
+If the match attempt succeeds:
+
+- Sets [match values][9].
+- Sets the [byte position][2] to the end of the matched substring;
+ may adjust the [character position][7].
+- Returns the matched substring.
+
+
+```rb
+scanner = StringScanner.new(HIRAGANA_TEXT)
+scanner.string # => "こんにちは"
+scanner.pos = 6
+scanner.scan_until(/ち/) # => "にち"
+put_match_values(scanner)
+# Basic match values:
+# matched?: true
+# matched_size: 3
+# pre_match: "こんに"
+# matched : "ち"
+# post_match: "は"
+# Captured match values:
+# size: 1
+# captures: []
+# named_captures: {}
+# values_at: ["ち", nil]
+# []:
+# [0]: "ち"
+# [1]: nil
+put_situation(scanner)
+# Situation:
+# pos: 12
+# charpos: 4
+# rest: "は"
+# rest_size: 3
+```
+
+If the match attempt fails:
+
+- Clears match data.
+- Returns `nil`.
+- Does not update positions.
+
+```rb
+scanner.scan_until(/nope/) # => nil
+match_values_cleared?(scanner) # => true
+```
diff --git a/doc/strscan/methods/set_pos.md b/doc/strscan/methods/set_pos.md
new file mode 100644
index 0000000000..6a43edeb41
--- /dev/null
+++ b/doc/strscan/methods/set_pos.md
@@ -0,0 +1,23 @@
+Sets the [byte position][2] and the [character position][11];
+returns `n`.
+
+Does not affect [match values][9].
+
+For non-negative `n`, sets the position to `n`:
+
+```rb
+scanner = StringScanner.new(HIRAGANA_TEXT)
+scanner.string # => "こんにちは"
+scanner.pos = 3 # => 3
+scanner.rest # => "んにちは"
+scanner.charpos # => 1
+```
+
+For negative `n`, counts from the end of the [stored string][1]:
+
+```rb
+scanner.pos = -9 # => -9
+scanner.pos # => 6
+scanner.rest # => "にちは"
+scanner.charpos # => 2
+```
diff --git a/doc/strscan/methods/skip.md b/doc/strscan/methods/skip.md
new file mode 100644
index 0000000000..7e924b624b
--- /dev/null
+++ b/doc/strscan/methods/skip.md
@@ -0,0 +1,40 @@
+Attempts to [match][17] the given `pattern`
+at the beginning of the [target substring][3];
+
+If the match succeeds:
+
+- Increments the [byte position][2] by substring.bytesize,
+ and may increment the [character position][7].
+- Sets [match values][9].
+- Returns the size (bytes) of the matched substring.
+
+```rb
+scanner = StringScanner.new(HIRAGANA_TEXT)
+scanner.string # => "こんにちは"
+scanner.pos = 6
+scanner.skip(/に/) # => 3
+put_match_values(scanner)
+# Basic match values:
+# matched?: true
+# matched_size: 3
+# pre_match: "こん"
+# matched : "に"
+# post_match: "ちは"
+# Captured match values:
+# size: 1
+# captures: []
+# named_captures: {}
+# values_at: ["に", nil]
+# []:
+# [0]: "に"
+# [1]: nil
+put_situation(scanner)
+# Situation:
+# pos: 9
+# charpos: 3
+# rest: "ちは"
+# rest_size: 6
+
+scanner.skip(/nope/) # => nil
+match_values_cleared?(scanner) # => true
+```
diff --git a/doc/strscan/methods/skip_until.md b/doc/strscan/methods/skip_until.md
new file mode 100644
index 0000000000..a0ffab0b84
--- /dev/null
+++ b/doc/strscan/methods/skip_until.md
@@ -0,0 +1,48 @@
+Attempts to [match][17] the given `pattern`
+anywhere (at any [position][2]) in the [target substring][3].
+
+If the match attempt succeeds:
+
+- Sets [match values][9].
+- Sets the [byte position][2] to the end of the matched substring;
+ may adjust the [character position][7].
+- Returns the size of the matched substring.
+
+```rb
+scanner = StringScanner.new(HIRAGANA_TEXT)
+scanner.string # => "こんにちは"
+scanner.pos = 6
+scanner.skip_until(/ち/) # => 6
+put_match_values(scanner)
+# Basic match values:
+# matched?: true
+# matched_size: 3
+# pre_match: "こんに"
+# matched : "ち"
+# post_match: "は"
+# Captured match values:
+# size: 1
+# captures: []
+# named_captures: {}
+# values_at: ["ち", nil]
+# []:
+# [0]: "ち"
+# [1]: nil
+put_situation(scanner)
+# Situation:
+# pos: 12
+# charpos: 4
+# rest: "は"
+# rest_size: 3
+```
+
+If the match attempt fails:
+
+- Clears match values.
+- Returns `nil`.
+- Does not update positions.
+
+```rb
+scanner.skip_until(/nope/) # => nil
+match_values_cleared?(scanner) # => true
+```
diff --git a/doc/strscan/methods/terminate.md b/doc/strscan/methods/terminate.md
new file mode 100644
index 0000000000..27f7d41cb1
--- /dev/null
+++ b/doc/strscan/methods/terminate.md
@@ -0,0 +1,27 @@
+Sets the scanner to end-of-string;
+returns +self+:
+
+- Sets both [positions][11] to end-of-stream.
+- Clears [match values][9].
+
+```rb
+scanner = StringScanner.new(HIRAGANA_TEXT)
+scanner.string # => "こんにちは"
+scanner.scan_until(/に/)
+put_situation(scanner)
+# Situation:
+# pos: 9
+# charpos: 3
+# rest: "ちは"
+# rest_size: 6
+match_values_cleared?(scanner) # => false
+
+scanner.terminate # => #<StringScanner fin>
+put_situation(scanner)
+# Situation:
+# pos: 15
+# charpos: 5
+# rest: ""
+# rest_size: 0
+match_values_cleared?(scanner) # => true
+```
generated by cgit v1.2.3 (git 2.25.1) at 2026-05-29 21:54:01 +0000