rbs 3.10.0.pre.2 → 3.10.0

data/stdlib/stringio/0/stringio.rbs

@@ -1,12 +1,33 @@
 # <!-- rdoc-file=ext/stringio/stringio.c -->
-# IO streams for strings, with access similar to
-# [IO](rdoc-ref:IO);
-# see [IO](rdoc-ref:IO).
-# ### About the Examples
+# Class StringIO supports accessing a string as a stream,
+# similar in some ways to [class
+# IO](https://docs.ruby-lang.org/en/master/IO.html).
+# You can create a StringIO instance using:
+# *   StringIO.new: returns a new StringIO object containing the given string.
+# *   StringIO.open: passes a new StringIO object to the given block.
+# Like an IO stream, a StringIO stream has certain properties:
+# *   **Read/write mode**: whether the stream may be read, written, appended to,
+#     etc.;
+#      see [Read/Write Mode](rdoc-ref:StringIO@Read-2FWrite+Mode).
+# *   **Data mode**: text-only or binary;
+#      see [Data Mode](rdoc-ref:StringIO@Data+Mode).
+# *   **Encodings**: internal and external encodings;
+#      see [Encodings](rdoc-ref:StringIO@Encodings).
+# *   **Position**: where in the stream the next read or write is to occur;
+#      see [Position](rdoc-ref:StringIO@Position).
+# *   **Line number**: a special, line-oriented, "position" (different from the
+#     position mentioned above);
+#      see [Line Number](rdoc-ref:StringIO@Line+Number).
+# *   **Open/closed**: whether the stream is open or closed, for reading or
+#     writing.
+#      see [Open/Closed Streams](rdoc-ref:StringIO@Open-2FClosed+Streams).
+# *   **BOM**: byte mark order;
+#      see [Byte Order Mark](rdoc-ref:StringIO@BOM+-28Byte+Order+Mark-29).
+# ## About the Examples
 # Examples on this page assume that StringIO has been required:
 #     require 'stringio'
 #
-# And that these constants have been defined:
+# And that this constant has been defined:
 #     TEXT = <<EOT
 # First line
 # Second line
@@ -15,8 +36,477 @@
 # Fifth line
 # EOT
 #
-# RUSSIAN = 'тест'
-# DATA = "\u9990\u9991\u9992\u9993\u9994"
+# ## Stream Properties
+# ### Read/Write Mode
+# #### Summary
+#        Mode        |Initial Clear?|  Read  | Write
+# -------------------|--------------|--------|--------
+#  `'r'`: read-only  |      No      |Anywhere| Error
+#  `'w'`: write-only |     Yes      | Error  |Anywhere
+# `'a'`: append-only |      No      | Error  |End only
+# `'r+'`: read/write |      No      |Anywhere|Anywhere
+# `'w+'`: read-write |     Yes      |Anywhere|Anywhere
+# `'a+'`: read/append|      No      |Anywhere|End only
+# Each section below describes a read/write mode.
+# Any of the modes may be given as a string or as file constants;
+# example:
+#     strio = StringIO.new('foo', 'a')
+# strio = StringIO.new('foo', File::WRONLY | File::APPEND)
+#
+# #### `'r'`: Read-Only
+# Mode specified as one of:
+# *   String: `'r'`.
+# *   Constant: `File::RDONLY`.
+# Initial state:
+#     strio = StringIO.new('foobarbaz', 'r')
+# strio.pos    # => 0            # Beginning-of-stream.
+# strio.string # => "foobarbaz"  # Not cleared.
+#
+# May be read anywhere:
+#     strio.gets(3) # => "foo"
+# strio.gets(3) # => "bar"
+# strio.pos = 9
+# strio.gets(3) # => nil
+#
+# May not be written:
+#     strio.write('foo')  # Raises IOError: not opened for writing
+#
+# #### `'w'`: Write-Only
+# Mode specified as one of:
+# *   String: `'w'`.
+# *   Constant: `File::WRONLY`.
+# Initial state:
+#     strio = StringIO.new('foo', 'w')
+# strio.pos    # => 0   # Beginning of stream.
+# strio.string # => ""  # Initially cleared.
+#
+# May be written anywhere (even past end-of-stream):
+#     strio.write('foobar')
+# strio.string # => "foobar"
+# strio.rewind
+# strio.write('FOO')
+# strio.string # => "FOObar"
+# strio.pos = 3
+# strio.write('BAR')
+# strio.string # => "FOOBAR"
+# strio.pos = 9
+# strio.write('baz')
+# strio.string # => "FOOBAR\u0000\u0000\u0000baz"  # Null-padded.
+#
+# May not be read:
+#     strio.read  # Raises IOError: not opened for reading
+#
+# #### `'a'`: Append-Only
+# Mode specified as one of:
+# *   String: `'a'`.
+# *   Constant: `File::WRONLY | File::APPEND`.
+# Initial state:
+#     strio = StringIO.new('foo', 'a')
+# strio.pos    # => 0      # Beginning-of-stream.
+# strio.string # => "foo"  # Not cleared.
+#
+# May be written only at the end; position does not affect writing:
+#     strio.write('bar')
+# strio.string # => "foobar"
+# strio.write('baz')
+# strio.string # => "foobarbaz"
+# strio.pos = 400
+# strio.write('bat')
+# strio.string # => "foobarbazbat"
+#
+# May not be read:
+#     strio.gets  # Raises IOError: not opened for reading
+#
+# #### `'r+'`: Read/Write
+# Mode specified as one of:
+# *   String: `'r+'`.
+# *   Constant: `File::RDRW`.
+# Initial state:
+#     strio = StringIO.new('foobar', 'r+')
+# strio.pos    # => 0         # Beginning-of-stream.
+# strio.string # => "foobar"  # Not cleared.
+#
+# May be written anywhere (even past end-of-stream):
+#     strio.write('FOO')
+# strio.string # => "FOObar"
+# strio.write('BAR')
+# strio.string # => "FOOBAR"
+# strio.write('BAZ')
+# strio.string # => "FOOBARBAZ"
+# strio.pos = 12
+# strio.write('BAT')
+# strio.string # => "FOOBARBAZ\u0000\u0000\u0000BAT"  # Null padded.
+#
+# May be read anywhere:
+#     strio.pos = 0
+# strio.gets(3) # => "FOO"
+# strio.pos = 6
+# strio.gets(3) # => "BAZ"
+# strio.pos = 400
+# strio.gets(3) # => nil
+#
+# #### `'w+'`: Read/Write (Initially Clear)
+# Mode specified as one of:
+# *   String: `'w+'`.
+# *   Constant: `File::RDWR | File::TRUNC`.
+# Initial state:
+#     strio = StringIO.new('foo', 'w+')
+# strio.pos    # => 0   # Beginning-of-stream.
+# strio.string # => ""  # Truncated.
+#
+# May be written anywhere (even past end-of-stream):
+#     strio.write('foobar')
+# strio.string # => "foobar"
+# strio.rewind
+# strio.write('FOO')
+# strio.string # => "FOObar"
+# strio.write('BAR')
+# strio.string # => "FOOBAR"
+# strio.write('BAZ')
+# strio.string # => "FOOBARBAZ"
+# strio.pos = 12
+# strio.write('BAT')
+# strio.string # => "FOOBARBAZ\u0000\u0000\u0000BAT"  # Null-padded.
+#
+# May be read anywhere:
+#     strio.rewind
+# strio.gets(3) # => "FOO"
+# strio.gets(3) # => "BAR"
+# strio.pos = 12
+# strio.gets(3) # => "BAT"
+# strio.pos = 400
+# strio.gets(3) # => nil
+#
+# #### `'a+'`: Read/Append
+# Mode specified as one of:
+# *   String: `'a+'`.
+# *   Constant: `File::RDWR | File::APPEND`.
+# Initial state:
+#     strio = StringIO.new('foo', 'a+')
+# strio.pos    # => 0      # Beginning-of-stream.
+# strio.string # => "foo"  # Not cleared.
+#
+# May be written only at the end; #rewind; position does not affect writing:
+#     strio.write('bar')
+# strio.string # => "foobar"
+# strio.write('baz')
+# strio.string # => "foobarbaz"
+# strio.pos = 400
+# strio.write('bat')
+# strio.string # => "foobarbazbat"
+#
+# May be read anywhere:
+#     strio.rewind
+# strio.gets(3) # => "foo"
+# strio.gets(3) # => "bar"
+# strio.pos = 9
+# strio.gets(3) # => "bat"
+# strio.pos = 400
+# strio.gets(3) # => nil
+#
+# ### Data Mode
+# To specify whether the stream is to be treated as text or as binary data,
+# either of the following may be suffixed to any of the string read/write modes
+# above:
+# *   `'t'`: Text;
+#      initializes the encoding as Encoding::UTF_8.
+# *   `'b'`: Binary;
+#      initializes the encoding as Encoding::ASCII_8BIT.
+# If neither is given, the stream defaults to text data.
+# Examples:
+#     strio = StringIO.new('foo', 'rt')
+# strio.external_encoding # => #<Encoding:UTF-8>
+# data = "\u9990\u9991\u9992\u9993\u9994"
+# strio = StringIO.new(data, 'rb')
+# strio.external_encoding # => #<Encoding:BINARY (ASCII-8BIT)>
+#
+# When the data mode is specified, the read/write mode may not be omitted:
+#     StringIO.new(data, 'b')  # Raises ArgumentError: invalid access mode b
+#
+# A text stream may be changed to binary by calling instance method #binmode;
+# a binary stream may not be changed to text.
+# ### Encodings
+# A stream has an encoding; see
+# [Encodings](https://docs.ruby-lang.org/en/master/language/encodings_rdoc.html)
+# .
+# The initial encoding for a new or re-opened stream depends on its [data
+# mode](rdoc-ref:StringIO@Data+Mode):
+# *   Text: `Encoding::UTF_8`.
+# *   Binary: `Encoding::ASCII_8BIT`.
+# These instance methods are relevant:
+# *   #external_encoding: returns the current encoding of the stream as an
+#     `Encoding` object.
+# *   #internal_encoding: returns `nil`; a stream does not have an internal
+#     encoding.
+# *   #set_encoding: sets the encoding for the stream.
+# *   #set_encoding_by_bom: sets the encoding for the stream to the stream's BOM
+#     (byte order mark).
+# Examples:
+#     strio = StringIO.new('foo', 'rt')  # Text mode.
+# strio.external_encoding # => #<Encoding:UTF-8>
+# data = "\u9990\u9991\u9992\u9993\u9994"
+# strio = StringIO.new(data, 'rb') # Binary mode.
+# strio.external_encoding # => #<Encoding:BINARY (ASCII-8BIT)>
+# strio = StringIO.new('foo')
+# strio.external_encoding # => #<Encoding:UTF-8>
+# strio.set_encoding('US-ASCII')
+# strio.external_encoding # => #<Encoding:US-ASCII>
+#
+# ### Position
+# A stream has a *position*, and integer offset (in bytes) into the stream.
+# The initial position of a stream is zero.
+# #### Getting and Setting the Position
+# Each of these methods initializes (to zero) the position of a new or re-opened
+# stream:
+# *   ::new: returns a new stream.
+# *   ::open: passes a new stream to the block.
+# *   #reopen: re-initializes the stream.
+# Each of these methods queries, gets, or sets the position, without otherwise
+# changing the stream:
+# *   #eof?: returns whether the position is at end-of-stream.
+# *   #pos: returns the position.
+# *   #pos=: sets the position.
+# *   #rewind: sets the position to zero.
+# *   #seek: sets the position.
+# Examples:
+#     strio = StringIO.new('foobar')
+# strio.pos  # => 0
+# strio.pos = 3
+# strio.pos  # => 3
+# strio.eof? # => false
+# strio.rewind
+# strio.pos  # => 0
+# strio.seek(0, IO::SEEK_END)
+# strio.pos  # => 6
+# strio.eof? # => true
+#
+# #### Position Before and After Reading
+# Except for #pread, a stream reading method (see [Basic
+# Reading](rdoc-ref:StringIO@Basic+Reading))
+# begins reading at the current position.
+# Except for #pread, a read method advances the position past the read
+# substring.
+# Examples:
+#     strio = StringIO.new(TEXT)
+# strio.string # => "First line\nSecond line\n\nFourth line\nFifth line\n"
+# strio.pos    # => 0
+# strio.getc   # => "F"
+# strio.pos    # => 1
+# strio.gets   # => "irst line\n"
+# strio.pos    # => 11
+# strio.pos = 24
+# strio.gets   # => "Fourth line\n"
+# strio.pos    # => 36
+#
+# strio = StringIO.new('тест') # Four 2-byte characters.
+# strio.pos = 0 # At first byte of first character.
+# strio.read    # => "тест"
+# strio.pos = 1 # At second byte of first character.
+# strio.read    # => "\x82ест"
+# strio.pos = 2 # At first of second character.
+# strio.read    # => "ест"
+#
+# strio = StringIO.new(TEXT)
+# strio.pos = 15
+# a = []
+# strio.each_line {|line| a.push(line) }
+# a         # => ["nd line\n", "\n", "Fourth line\n", "Fifth line\n"]
+# strio.pos # => 47  ## End-of-stream.
+#
+# #### Position Before and After Writing
+# Each of these methods begins writing at the current position,
+# and advances the position to the end of the written substring:
+# *   #putc: writes the given character.
+# *   #write: writes the given objects as strings.
+# *   [Kernel#puts](https://docs.ruby-lang.org/en/master/Kernel.html#method-i-pu
+#     ts): writes given objects as strings, each followed by newline.
+# Examples:
+#     strio = StringIO.new('foo')
+# strio.pos    # => 0
+# strio.putc('b')
+# strio.string # => "boo"
+# strio.pos    # => 1
+# strio.write('r')
+# strio.string # => "bro"
+# strio.pos    # => 2
+# strio.puts('ew')
+# strio.string # => "brew\n"
+# strio.pos    # => 5
+# strio.pos = 8
+# strio.write('foo')
+# strio.string # => "brew\n\u0000\u0000\u0000foo"
+# strio.pos    # => 11
+#
+# Each of these methods writes *before* the current position, and decrements the
+# position
+# so that the written data is next to be read:
+# *   #ungetbyte: unshifts the given byte.
+# *   #ungetc: unshifts the given character.
+# Examples:
+#     strio = StringIO.new('foo')
+# strio.pos = 2
+# strio.ungetc('x')
+# strio.pos    # => 1
+# strio.string # => "fxo"
+# strio.ungetc('x')
+# strio.pos    # => 0
+# strio.string # => "xxo"
+#
+# This method does not affect the position:
+# *   #truncate: truncates the stream's string to the given size.
+# Examples:
+#     strio = StringIO.new('foobar')
+# strio.pos    # => 0
+# strio.truncate(3)
+# strio.string # => "foo"
+# strio.pos    # => 0
+# strio.pos = 500
+# strio.truncate(0)
+# strio.string # => ""
+# strio.pos    # => 500
+#
+# ### Line Number
+# A stream has a line number, which initially is zero:
+# *   Method #lineno returns the line number.
+# *   Method #lineno= sets the line number.
+# The line number can be affected by reading (but never by writing);
+# in general, the line number is incremented each time the record separator
+# (default: `"\n"`) is read.
+# Examples:
+#     strio = StringIO.new(TEXT)
+# strio.string # => "First line\nSecond line\n\nFourth line\nFifth line\n"
+# strio.lineno # => 0
+# strio.gets   # => "First line\n"
+# strio.lineno # => 1
+# strio.getc   # => "S"
+# strio.lineno # => 1
+# strio.gets   # => "econd line\n"
+# strio.lineno # => 2
+# strio.gets   # => "\n"
+# strio.lineno # => 3
+# strio.gets   # => "Fourth line\n"
+# strio.lineno # => 4
+#
+# Setting the position does not affect the line number:
+#     strio.pos = 0
+# strio.lineno # => 4
+# strio.gets   # => "First line\n"
+# strio.pos    # => 11
+# strio.lineno # => 5
+#
+# And setting the line number does not affect the position:
+#     strio.lineno = 10
+# strio.pos    # => 11
+# strio.gets   # => "Second line\n"
+# strio.lineno # => 11
+# strio.pos    # => 23
+#
+# ### Open/Closed Streams
+# A new stream is open for either reading or writing, and may be open for both;
+# see [Read/Write Mode](rdoc-ref:StringIO@Read-2FWrite+Mode).
+# Each of these methods initializes the read/write mode for a new or re-opened
+# stream:
+# *   ::new: returns a new stream.
+# *   ::open: passes a new stream to the block.
+# *   #reopen: re-initializes the stream.
+# Other relevant methods:
+# *   #close: closes the stream for both reading and writing.
+# *   #close_read: closes the stream for reading.
+# *   #close_write: closes the stream for writing.
+# *   #closed?: returns whether the stream is closed for both reading and
+#     writing.
+# *   #closed_read?: returns whether the stream is closed for reading.
+# *   #closed_write?: returns whether the stream is closed for writing.
+# ### BOM (Byte Order Mark)
+# The string provided for ::new, ::open, or #reopen
+# may contain an optional [BOM](https://en.wikipedia.org/wiki/Byte_order_mark)
+# (byte order mark) at the beginning of the string;
+# the BOM can affect the stream's encoding.
+# The BOM (if provided):
+# *   Is stored as part of the stream's string.
+# *   Does *not* immediately affect the encoding.
+# *   Is *initially* considered part of the stream.
+#     utf8_bom = "\xEF\xBB\xBF"
+# string = utf8_bom + 'foo'
+# string.bytes               # => [239, 187, 191, 102, 111, 111]
+# strio.string.bytes.take(3) # => [239, 187, 191]                  # The BOM.
+# strio = StringIO.new(string, 'rb')
+# strio.string.bytes         # => [239, 187, 191, 102, 111, 111]   # BOM is part of the stored string.
+# strio.external_encoding    # => #<Encoding:BINARY (ASCII-8BIT)>  # Default for a binary stream.
+# strio.gets                 # => "\xEF\xBB\xBFfoo"                # BOM is part of the stream.
+#
+# You can call instance method #set_encoding_by_bom to "activate" the stored
+# BOM;
+# after doing so the BOM:
+# *   Is *still* stored as part of the stream's string.
+# *   *Determines* (and may have changed) the stream's encoding.
+# *   Is *no longer* considered part of the stream.
+#     strio.set_encoding_by_bom
+# strio.string.bytes      # => [239, 187, 191, 102, 111, 111]  # BOM is still part of the stored string.
+# strio.external_encoding # => #<Encoding:UTF-8>               # The new encoding.
+# strio.rewind            # => 0
+# strio.gets              # => "foo"                           # BOM is not part of the stream.
+#
+# ## Basic Stream IO
+# ### Basic Reading
+# You can read from the stream using these instance methods:
+# *   #getbyte: reads and returns the next byte.
+# *   #getc: reads and returns the next character.
+# *   #gets: reads and returns all or part of the next line.
+# *   #read: reads and returns all or part of the remaining data in the stream.
+# *   #readlines: reads the remaining data the stream and returns an array of
+#     its lines.
+# *   [Kernel#readline](https://docs.ruby-lang.org/en/master/Kernel.html#method-
+#     i-readline): like #gets, but raises an exception if at end-of-stream.
+# You can iterate over the stream using these instance methods:
+# *   #each_byte: reads each remaining byte, passing it to the block.
+# *   #each_char: reads each remaining character, passing it to the block.
+# *   #each_codepoint: reads each remaining codepoint, passing it to the block.
+# *   #each_line: reads all or part of each remaining line, passing the read
+#     string to the block
+# This instance method is useful in a multi-threaded application:
+# *   #pread: reads and returns all or part of the stream.
+# ### Basic Writing
+# You can write to the stream, advancing the position, using these instance
+# methods:
+# *   #putc: writes a given character.
+# *   #write: writes the given objects as strings.
+# *   [Kernel#puts](https://docs.ruby-lang.org/en/master/Kernel.html#method-i-pu
+#     ts) writes given objects as strings, each followed by newline.
+# You can "unshift" to the stream using these instance methods;
+# each writes *before* the current position, and decrements the position
+# so that the written data is next to be read.
+# *   #ungetbyte: unshifts the given byte.
+# *   #ungetc: unshifts the given character.
+# One more writing method:
+# *   #truncate: truncates the stream's string to the given size.
+# ## Line IO
+# Reading:
+# *   #gets: reads and returns the next line.
+# *   [Kernel#readline](https://docs.ruby-lang.org/en/master/Kernel.html#method-
+#     i-readline): like #gets, but raises an exception if at end-of-stream.
+# *   #readlines: reads the remaining data the stream and returns an array of
+#     its lines.
+# *   #each_line: reads each remaining line, passing it to the block
+# Writing:
+# *   [Kernel#puts](https://docs.ruby-lang.org/en/master/Kernel.html#method-i-pu
+#     ts): writes given objects, each followed by newline.
+# ## Character IO
+# Reading:
+# *   #each_char: reads each remaining character, passing it to the block.
+# *   #getc: reads and returns the next character.
+# Writing:
+# *   #putc: writes the given character.
+# *   #ungetc.: unshifts the given character.
+# ## Byte IO
+# Reading:
+# *   #each_byte: reads each remaining byte, passing it to the block.
+# *   #getbyte: reads and returns the next byte.
+# Writing:
+# *   #ungetbyte: unshifts the given byte.
+# ## Codepoint IO
+# Reading:
+# *   #each_codepoint: reads each remaining codepoint, passing it to the block.
 #
 class StringIO
   # <!--
@@ -78,7 +568,7 @@ class StringIO
   #   - binmode -> self
   # -->
   # Sets the data mode in `self` to binary mode; see [Data
-  # Mode](rdoc-ref:File@Data+Mode).
+  # Mode](rdoc-ref:StringIO@Data+Mode).
   #
   def binmode: () -> self
 
@@ -188,6 +678,137 @@ class StringIO
   #   - each_line(limit, chomp: false) {|line| ... }      -> self
   #   - each_line(sep, limit, chomp: false) {|line| ... } -> self
   # -->
+  # With a block given calls the block with each remaining line (see "Position"
+  # below) in the stream;
+  # returns `self`.
+  # Leaves stream position at end-of-stream.
+  # **No Arguments**
+  # With no arguments given,
+  # reads lines using the default record separator
+  # (global variable `$/`, whose initial value is `"\n"`).
+  #     strio = StringIO.new(TEXT)
+  # strio.each_line {|line| p line }
+  # strio.eof? # => true
+  #
+  # Output:
+  #     "First line\n"
+  # "Second line\n"
+  # "\n"
+  # "Fourth line\n"
+  # "Fifth line\n"
+  #
+  # **Argument `sep`**
+  # With only string argument `sep` given,
+  # reads lines using that string as the record separator:
+  #     strio = StringIO.new(TEXT)
+  # strio.each_line(' ') {|line| p line }
+  #
+  # Output:
+  #     "First "
+  # "line\nSecond "
+  # "line\n\nFourth "
+  # "line\nFifth "
+  # "line\n"
+  #
+  # **Argument `limit`**
+  # With only integer argument `limit` given,
+  # reads lines using the default record separator;
+  # also limits the size (in characters) of each line to the given limit:
+  #     strio = StringIO.new(TEXT)
+  # strio.each_line(10) {|line| p line }
+  #
+  # Output:
+  #     "First line"
+  # "\n"
+  # "Second lin"
+  # "e\n"
+  # "\n"
+  # "Fourth lin"
+  # "e\n"
+  # "Fifth line"
+  # "\n"
+  #
+  # **Arguments `sep` and `limit`**
+  # With arguments `sep` and `limit` both given,
+  # honors both:
+  #     strio = StringIO.new(TEXT)
+  # strio.each_line(' ', 10) {|line| p line }
+  #
+  # Output:
+  #     "First "
+  # "line\nSecon"
+  # "d "
+  # "line\n\nFour"
+  # "th "
+  # "line\nFifth"
+  # " "
+  # "line\n"
+  #
+  # **Position**
+  # As stated above, method `each` *remaining* line in the stream.
+  # In the examples above each `strio` object starts with its position at
+  # beginning-of-stream;
+  # but in other cases the position may be anywhere (see StringIO#pos):
+  #     strio = StringIO.new(TEXT)
+  # strio.pos = 30 # Set stream position to character 30.
+  # strio.each_line {|line| p line }
+  #
+  # Output:
+  #     " line\n"
+  # "Fifth line\n"
+  #
+  # In all the examples above, the stream position is at the beginning of a
+  # character;
+  # in other cases, that need not be so:
+  #     s = 'こんにちは'  # Five 3-byte characters.
+  # strio = StringIO.new(s)
+  # strio.pos = 3   # At beginning of second character.
+  # strio.each_line {|line| p line }
+  # strio.pos = 4   # At second byte of second character.
+  # strio.each_line {|line| p line }
+  # strio.pos = 5   # At third byte of second character.
+  # strio.each_line {|line| p line }
+  #
+  # Output:
+  #     "んにちは"
+  # "\x82\x93にちは"
+  # "\x93にちは"
+  #
+  # **Special Record Separators**
+  # Like some methods in class `IO`, StringIO.each honors two special record
+  # separators;
+  # see [Special Line
+  # Separators](https://docs.ruby-lang.org/en/master/IO.html#class-IO-label-Specia
+  # l+Line+Separator+Values).
+  #     strio = StringIO.new(TEXT)
+  # strio.each_line('') {|line| p line } # Read as paragraphs (separated by blank lines).
+  #
+  # Output:
+  #     "First line\nSecond line\n\n"
+  # "Fourth line\nFifth line\n"
+  #
+  #     strio = StringIO.new(TEXT)
+  # strio.each_line(nil) {|line| p line } # "Slurp"; read it all.
+  #
+  # Output:
+  #     "First line\nSecond line\n\nFourth line\nFifth line\n"
+  #
+  # **Keyword Argument `chomp`**
+  # With keyword argument `chomp` given as `true` (the default is `false`),
+  # removes trailing newline (if any) from each line:
+  #     strio = StringIO.new(TEXT)
+  # strio.each_line(chomp: true) {|line| p line }
+  #
+  # Output:
+  #     "First line"
+  # "Second line"
+  # ""
+  # "Fourth line"
+  # "Fifth line"
+  #
+  # With no block given, returns a new
+  # [Enumerator](https://docs.ruby-lang.org/en/master/Enumerator.html).
+  # Related: StringIO.each_byte, StringIO.each_char, StringIO.each_codepoint.
   #
   def each: (?String sep, ?Integer limit, ?chomp: boolish) { (String) -> untyped } -> self
           | (?String sep, ?Integer limit, ?chomp: boolish) -> ::Enumerator[String, self]
@@ -394,19 +1015,21 @@ class StringIO
   #
   # Returns a byte, not a character:
   #
-  #     s = 'тест'
-  #     s.bytes       # => [209, 130, 208, 181, 209, 129, 209, 130]
+  #     s = 'Привет'
+  #     s.bytes
+  #     # => [208, 159, 209, 128, 208, 184, 208, 178, 208, 181, 209, 130]
   #     strio = StringIO.new(s)
-  #     strio.getbyte # => 209
-  #     strio.getbyte # => 130
+  #     strio.getbyte # => 208
+  #     strio.getbyte # => 159
   #
   #     s = 'こんにちは'
-  #     s.bytes       # => [227, 129, 147, 227, 130, 147, 227, 129, 171, 227, 129, 161, 227, 129, 175]
+  #     s.bytes
+  #     # => [227, 129, 147, 227, 130, 147, 227, 129, 171, 227, 129, 161, 227, 129, 175]
   #     strio = StringIO.new(s)
   #     strio.getbyte # => 227
   #     strio.getbyte # => 129
   #
-  # Related: StringIO.getc.
+  # Related: #each_byte, #ungetbyte, #getc.
   #
   def getbyte: () -> Integer?
 
@@ -428,9 +1051,9 @@ class StringIO
   #
   # Returns characters, not bytes:
   #
-  #     strio = StringIO.new('тест')
-  #     strio.getc # => "т"
-  #     strio.getc # => "е"
+  #     strio = StringIO.new('Привет')
+  #     strio.getc # => "П"
+  #     strio.getc # => "р"
   #
   #     strio = StringIO.new('こんにちは')
   #     strio.getc # => "こ"
@@ -447,7 +1070,7 @@ class StringIO
   #     strio.pos = 5 # => 5     # At third byte of second character; returns byte.
   #     strio.getc    # => "\x93"
   #
-  # Related: StringIO.getbyte.
+  # Related: #getbyte, #putc, #ungetc.
   #
   def getc: () -> String?
 
@@ -477,10 +1100,10 @@ class StringIO
   #     strio.eof? # => true
   #     strio.gets # => nil
   #
-  #     strio = StringIO.new('тест')  # Four 2-byte characters.
+  #     strio = StringIO.new('Привет')  # Six 2-byte characters
   #     strio.pos  # => 0
-  #     strio.gets # => "тест"
-  #     strio.pos  # => 8
+  #     strio.gets # => "Привет"
+  #     strio.pos  # => 12
   #
   # **Argument `sep`**
   #
@@ -526,11 +1149,11 @@ class StringIO
   #
   # The position need not be at a character boundary:
   #
-  #     strio = StringIO.new('тест')  # Four 2-byte characters.
-  #     strio.pos = 2                 # At beginning of second character.
-  #     strio.gets # => "ест"
-  #     strio.pos = 3                 # In middle of second character.
-  #     strio.gets # => "\xB5ст"
+  #     strio = StringIO.new('Привет') # Six 2-byte characters.
+  #     strio.pos = 2                  # At beginning of second character.
+  #     strio.gets # => "ривет"
+  #     strio.pos = 3                  # In middle of second character.
+  #     strio.gets # => "\x80ивет"
   #
   # **Special Record Separators**
   #
@@ -556,7 +1179,7 @@ class StringIO
   #     strio.gets              # => "First line\n"
   #     strio.gets(chomp: true) # => "Second line"
   #
-  # Related: StringIO.each_line.
+  # Related: #each_line, #readlines, [Kernel#puts](rdoc-ref:Kernel#puts).
   #
   def gets: (?String sep, ?Integer limit, ?chomp: boolish) -> String?
 
@@ -573,7 +1196,7 @@ class StringIO
   #   - external_encoding -> encoding or nil
   # -->
   # Returns an Encoding object that represents the encoding of the string; see
-  # [Encoding](rdoc-ref:Encoding):
+  # [Encodings](rdoc-ref:StringIO@Encodings):
   #
   #     strio = StringIO.new('foo')
   #     strio.external_encoding # => #<Encoding:UTF-8>
@@ -598,7 +1221,7 @@ class StringIO
   #   - lineno -> current_line_number
   # -->
   # Returns the current line number in `self`; see [Line
-  # Number](rdoc-ref:IO@Line+Number).
+  # Number](rdoc-ref:StringIO@Line+Number).
   #
   def lineno: () -> Integer
 
@@ -607,7 +1230,7 @@ class StringIO
   #   - lineno = new_line_number -> new_line_number
   # -->
   # Sets the current line number in `self` to the given `new_line_number`; see
-  # [Line Number](rdoc-ref:IO@Line+Number).
+  # [Line Number](rdoc-ref:StringIO@Line+Number).
   #
   def lineno=: (Integer arg0) -> Integer
 
@@ -623,7 +1246,8 @@ class StringIO
   #   rdoc-file=ext/stringio/stringio.c
   #   - pos -> stream_position
   # -->
-  # Returns the current position (in bytes); see [Position](rdoc-ref:IO@Position).
+  # Returns the current position (in bytes); see
+  # [Position](rdoc-ref:StringIO@Position).
   #
   def pos: () -> Integer
 
@@ -631,7 +1255,8 @@ class StringIO
   #   rdoc-file=ext/stringio/stringio.c
   #   - pos = new_position -> new_position
   # -->
-  # Sets the current position (in bytes); see [Position](rdoc-ref:IO@Position).
+  # Sets the current position (in bytes); see
+  # [Position](rdoc-ref:StringIO@Position).
   #
   def pos=: (Integer arg0) -> Integer
 
@@ -779,6 +1404,11 @@ class StringIO
   #   rdoc-file=ext/stringio/stringio.c
   #   - size -> integer
   # -->
+  # Returns the number of bytes in the string in `self`:
+  #
+  #     StringIO.new('hello').size     # => 5  # Five 1-byte characters.
+  #     StringIO.new('тест').size      # => 8  # Four 2-byte characters.
+  #     StringIO.new('こんにちは').size # => 15 # Five 3-byte characters.
   #
   def size: () -> Integer
 
@@ -806,7 +1436,8 @@ class StringIO
   #   rdoc-file=ext/stringio/stringio.c
   #   - pos -> stream_position
   # -->
-  # Returns the current position (in bytes); see [Position](rdoc-ref:IO@Position).
+  # Returns the current position (in bytes); see
+  # [Position](rdoc-ref:StringIO@Position).
   #
   def tell: () -> Integer
 
@@ -868,10 +1499,138 @@ class StringIO
   def codepoints: () { (Integer arg0) -> untyped } -> self
                 | () -> ::Enumerator[Integer, self]
 
-  # <!--
-  #   rdoc-file=ext/stringio/stringio.c
-  #   - each_line(*args)
-  # -->
+  # <!-- rdoc-file=ext/stringio/stringio.c -->
+  # With a block given calls the block with each remaining line (see "Position"
+  # below) in the stream;
+  # returns `self`.
+  # Leaves stream position at end-of-stream.
+  # **No Arguments**
+  # With no arguments given,
+  # reads lines using the default record separator
+  # (global variable `$/`, whose initial value is `"\n"`).
+  #     strio = StringIO.new(TEXT)
+  # strio.each_line {|line| p line }
+  # strio.eof? # => true
+  #
+  # Output:
+  #     "First line\n"
+  # "Second line\n"
+  # "\n"
+  # "Fourth line\n"
+  # "Fifth line\n"
+  #
+  # **Argument `sep`**
+  # With only string argument `sep` given,
+  # reads lines using that string as the record separator:
+  #     strio = StringIO.new(TEXT)
+  # strio.each_line(' ') {|line| p line }
+  #
+  # Output:
+  #     "First "
+  # "line\nSecond "
+  # "line\n\nFourth "
+  # "line\nFifth "
+  # "line\n"
+  #
+  # **Argument `limit`**
+  # With only integer argument `limit` given,
+  # reads lines using the default record separator;
+  # also limits the size (in characters) of each line to the given limit:
+  #     strio = StringIO.new(TEXT)
+  # strio.each_line(10) {|line| p line }
+  #
+  # Output:
+  #     "First line"
+  # "\n"
+  # "Second lin"
+  # "e\n"
+  # "\n"
+  # "Fourth lin"
+  # "e\n"
+  # "Fifth line"
+  # "\n"
+  #
+  # **Arguments `sep` and `limit`**
+  # With arguments `sep` and `limit` both given,
+  # honors both:
+  #     strio = StringIO.new(TEXT)
+  # strio.each_line(' ', 10) {|line| p line }
+  #
+  # Output:
+  #     "First "
+  # "line\nSecon"
+  # "d "
+  # "line\n\nFour"
+  # "th "
+  # "line\nFifth"
+  # " "
+  # "line\n"
+  #
+  # **Position**
+  # As stated above, method `each` *remaining* line in the stream.
+  # In the examples above each `strio` object starts with its position at
+  # beginning-of-stream;
+  # but in other cases the position may be anywhere (see StringIO#pos):
+  #     strio = StringIO.new(TEXT)
+  # strio.pos = 30 # Set stream position to character 30.
+  # strio.each_line {|line| p line }
+  #
+  # Output:
+  #     " line\n"
+  # "Fifth line\n"
+  #
+  # In all the examples above, the stream position is at the beginning of a
+  # character;
+  # in other cases, that need not be so:
+  #     s = 'こんにちは'  # Five 3-byte characters.
+  # strio = StringIO.new(s)
+  # strio.pos = 3   # At beginning of second character.
+  # strio.each_line {|line| p line }
+  # strio.pos = 4   # At second byte of second character.
+  # strio.each_line {|line| p line }
+  # strio.pos = 5   # At third byte of second character.
+  # strio.each_line {|line| p line }
+  #
+  # Output:
+  #     "んにちは"
+  # "\x82\x93にちは"
+  # "\x93にちは"
+  #
+  # **Special Record Separators**
+  # Like some methods in class `IO`, StringIO.each honors two special record
+  # separators;
+  # see [Special Line
+  # Separators](https://docs.ruby-lang.org/en/master/IO.html#class-IO-label-Specia
+  # l+Line+Separator+Values).
+  #     strio = StringIO.new(TEXT)
+  # strio.each_line('') {|line| p line } # Read as paragraphs (separated by blank lines).
+  #
+  # Output:
+  #     "First line\nSecond line\n\n"
+  # "Fourth line\nFifth line\n"
+  #
+  #     strio = StringIO.new(TEXT)
+  # strio.each_line(nil) {|line| p line } # "Slurp"; read it all.
+  #
+  # Output:
+  #     "First line\nSecond line\n\nFourth line\nFifth line\n"
+  #
+  # **Keyword Argument `chomp`**
+  # With keyword argument `chomp` given as `true` (the default is `false`),
+  # removes trailing newline (if any) from each line:
+  #     strio = StringIO.new(TEXT)
+  # strio.each_line(chomp: true) {|line| p line }
+  #
+  # Output:
+  #     "First line"
+  # "Second line"
+  # ""
+  # "Fourth line"
+  # "Fifth line"
+  #
+  # With no block given, returns a new
+  # [Enumerator](https://docs.ruby-lang.org/en/master/Enumerator.html).
+  # Related: StringIO.each_byte, StringIO.each_char, StringIO.each_codepoint.
   #
   def each_line: (?String sep, ?Integer limit, ?chomp: boolish) { (String) -> untyped } -> self
                | (?String sep, ?Integer limit, ?chomp: boolish) -> ::Enumerator[String, self]