JezK
Edit File: string_scanner.rbs
# <!-- rdoc-file=ext/strscan/strscan.c --> # 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 # * #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. # class StringScanner # <!-- # rdoc-file=ext/strscan/strscan.c # - StringScanner.must_C_version # --> # This method is defined for backward compatibility. # def self.must_C_version: () -> self public # <!-- rdoc-file=ext/strscan/strscan.c --> # 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" # def <<: (String) -> self # <!-- # rdoc-file=ext/strscan/strscan.c # - [](n) # --> # 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 # -> "" # def []: (Integer) -> String? # <!-- # rdoc-file=ext/strscan/strscan.c # - beginning_of_line?() # --> # 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 # def beginning_of_line?: () -> bool alias bol? beginning_of_line? # <!-- # rdoc-file=ext/strscan/strscan.c # - captures # --> # 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+) /) # -> "Fri Dec 12 " # s.captures # -> ["Fri", "Dec", "12"] # s.scan(/(\w+) (\w+) (\d+) /) # -> nil # s.captures # -> nil # def captures: () -> Array[String]? # <!-- # rdoc-file=ext/strscan/strscan.c # - charpos() # --> # 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ädeföghi") # s.charpos # -> 0 # s.scan_until(/ä/) # -> "abcä" # s.pos # -> 5 # s.charpos # -> 4 # def charpos: () -> Integer # <!-- # rdoc-file=ext/strscan/strscan.c # - 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. # def check: (Regexp) -> String? # <!-- # rdoc-file=ext/strscan/strscan.c # - 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. # def check_until: (Regexp) -> String # <!-- # rdoc-file=ext/strscan/strscan.c # - clear() # --> # Equivalent to #terminate. This method is obsolete; use #terminate instead. # def clear: () -> void # <!-- # rdoc-file=ext/strscan/strscan.c # - 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" # alias concat << # <!-- # rdoc-file=ext/strscan/strscan.c # - empty?() # --> # Equivalent to #eos?. This method is obsolete, use #eos? instead. # def empty?: () -> bool # <!-- # rdoc-file=ext/strscan/strscan.c # - 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 # def eos?: () -> bool # <!-- # rdoc-file=ext/strscan/strscan.c # - 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/ # -> 2 # s.exist? /e/ # -> nil # def exist?: (Regexp) -> Integer? # <!-- # rdoc-file=ext/strscan/strscan.c # - scanner.fixed_anchor? -> true or false # --> # 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. # def fixed_anchor?: () -> bool # <!-- # rdoc-file=ext/strscan/strscan.c # - get_byte() # --> # 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 # def get_byte: () -> String? # <!-- # rdoc-file=ext/strscan/strscan.c # - getbyte() # --> # Equivalent to #get_byte. This method is obsolete; use #get_byte instead. # def getbyte: () -> String? # <!-- # rdoc-file=ext/strscan/strscan.c # - getch() # --> # 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 # def getch: () -> String? # <!-- # rdoc-file=ext/strscan/strscan.c # - 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...">' # def inspect: () -> String # <!-- # rdoc-file=ext/strscan/strscan.c # - 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?("test") # -> 4 # p s.match?(/\s+/) # -> nil # def match?: (Regexp) -> Integer? # <!-- # rdoc-file=ext/strscan/strscan.c # - matched() # --> # Returns the last matched string. # # s = StringScanner.new('test string') # s.match?(/\w+/) # -> 4 # s.matched # -> "test" # def matched: () -> String? # <!-- # rdoc-file=ext/strscan/strscan.c # - matched?() # --> # 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 # def matched?: () -> bool # <!-- # rdoc-file=ext/strscan/strscan.c # - matched_size() # --> # 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 # def matched_size: () -> Integer? # <!-- # rdoc-file=ext/strscan/strscan.c # - 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" # def peek: (Integer) -> String # <!-- # rdoc-file=ext/strscan/strscan.c # - peep(p1) # --> # Equivalent to #peek. This method is obsolete; use #peek instead. # def peep: (Integer) -> String # <!-- rdoc-file=ext/strscan/strscan.c --> # 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 # def pointer: () -> Integer # <!-- rdoc-file=ext/strscan/strscan.c --> # Sets the byte position of the scan pointer. # # s = StringScanner.new('test string') # s.pos = 7 # -> 7 # s.rest # -> "ring" # def pointer=: (Integer) -> Integer # <!-- # rdoc-file=ext/strscan/strscan.c # - pos() # --> # 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 # def pos: () -> Integer # <!-- # rdoc-file=ext/strscan/strscan.c # - pos=(n) # --> # Sets the byte position of the scan pointer. # # s = StringScanner.new('test string') # s.pos = 7 # -> 7 # s.rest # -> "ring" # def pos=: (Integer) -> Integer # <!-- # rdoc-file=ext/strscan/strscan.c # - post_match() # --> # 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" # def post_match: () -> String # <!-- # rdoc-file=ext/strscan/strscan.c # - pre_match() # --> # 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" # def pre_match: () -> String # <!-- # rdoc-file=ext/strscan/strscan.c # - reset() # --> # Reset the scan pointer (index 0) and clear matching data. # def reset: () -> void # <!-- # rdoc-file=ext/strscan/strscan.c # - rest() # --> # Returns the "rest" of the string (i.e. everything after the scan pointer). If # there is no more data (eos? = true), it returns `""`. # def rest: () -> String # <!-- # rdoc-file=ext/strscan/strscan.c # - rest?() # --> # 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') # s.eos? # These two # s.rest? # are opposites. # def rest?: () -> bool # <!-- # rdoc-file=ext/strscan/strscan.c # - rest_size() # --> # `s.rest_size` is equivalent to `s.rest.size`. # def rest_size: () -> Integer # <!-- # rdoc-file=ext/strscan/strscan.c # - restsize() # --> # `s.restsize` is equivalent to `s.rest_size`. This method is obsolete; use # #rest_size instead. # def restsize: () -> Integer # <!-- # rdoc-file=ext/strscan/strscan.c # - 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 # def scan: (Regexp) -> String? # <!-- # rdoc-file=ext/strscan/strscan.c # - scan_full(pattern, advance_pointer_p, return_string_p) # --> # 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". # def scan_full: (Regexp pattern, bool advance_pointer_p, bool return_string_p) -> untyped # <!-- # rdoc-file=ext/strscan/strscan.c # - 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 # def scan_until: (Regexp) -> String? # <!-- # rdoc-file=ext/strscan/strscan.c # - search_full(pattern, advance_pointer_p, return_string_p) # --> # 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. # def search_full: (Regexp pattern, bool advance_pointer_p, bool return_string_p) -> untyped # <!-- # rdoc-file=ext/strscan/strscan.c # - size # --> # 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 # def size: () -> Integer # <!-- # rdoc-file=ext/strscan/strscan.c # - 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("st") # -> 2 # p s.skip(/\w+/) # -> 4 # p s.skip(/./) # -> nil # def skip: (Regexp) -> Integer? # <!-- # rdoc-file=ext/strscan/strscan.c # - 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 # # def skip_until: (Regexp) -> Integer? # <!-- # rdoc-file=ext/strscan/strscan.c # - string() # --> # Returns the string being scanned. # def string: () -> String # <!-- # rdoc-file=ext/strscan/strscan.c # - string=(str) # --> # Changes the string being scanned to `str` and resets the scanner. Returns # `str`. # def string=: (String) -> String # <!-- # rdoc-file=ext/strscan/strscan.c # - terminate # - clear # --> # Sets the scan pointer to the end of the string and clear matching data. # def terminate: () -> void # <!-- # rdoc-file=ext/strscan/strscan.c # - unscan() # --> # 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 # def unscan: () -> void # <!-- # rdoc-file=ext/strscan/strscan.c # - scanner.values_at( i1, i2, ... iN ) -> an_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 # def values_at: (*Integer) -> Array[String]? private # <!-- # rdoc-file=ext/strscan/strscan.c # - StringScanner.new(string, fixed_anchor: false) # - StringScanner.new(string, dup = false) # --> # Creates a new StringScanner object to scan over the given `string`. # # If `fixed_anchor` is `true`, `\A` always matches the beginning of the string. # Otherwise, `\A` always matches the current position. # # `dup` argument is obsolete and not used now. # def initialize: (String, ?bool dup, ?fixed_anchor: bool) -> untyped # <!-- # rdoc-file=ext/strscan/strscan.c # - dup # - clone # --> # Duplicates a StringScanner object. # def initialize_copy: (StringScanner) -> void end StringScanner::Id: String StringScanner::Version: String