Class

IO streams for strings, with access similar to IO; see IO.

About the Examples

Examples on this page assume that StringIO has been required:

require 'stringio'
Constants

The version string

Maximum length that a StringIO instance can hold

Class Methods

Note that mode defaults to 'r' if string is frozen.

Returns a new StringIO instance formed from string and mode; see Access Modes:

strio = StringIO.new # => #<StringIO>
strio.close

The instance should be closed when no longer needed.

Related: StringIO.open (accepts block; closes automatically).

Note that mode defaults to 'r' if string is frozen.

Creates a new StringIO instance formed from string and mode; see Access Modes.

With no block, returns the new instance:

strio = StringIO.open # => #<StringIO>

With a block, calls the block with the new instance and returns the block’s value; closes the instance on block exit.

StringIO.open {|strio| p strio }
# => #<StringIO>

Related: StringIO.new.

Instance Methods

Sets the data mode in self to binary mode; see Data Mode.

Closes self for both reading and writing.

Raises IOError if reading or writing is attempted.

Related: StringIO#close_read, StringIO#close_write.

Closes self for reading; closed-write setting remains unchanged.

Raises IOError if reading is attempted.

Related: StringIO#close, StringIO#close_write.

Closes self for writing; closed-read setting remains unchanged.

Raises IOError if writing is attempted.

Related: StringIO#close, StringIO#close_read.

Returns true if self is closed for both reading and writing, false otherwise.

Returns true if self is closed for reading, false otherwise.

Returns true if self is closed for writing, false otherwise.

Calls the block with each remaining line read from the stream; does nothing if already at end-of-file; returns self. See Line IO.

With a block given, calls the block with each remaining byte in the stream; see Byte IO.

With no block given, returns an enumerator.

With a block given, calls the block with each remaining character in the stream; see Character IO.

With no block given, returns an enumerator.

With a block given, calls the block with each remaining codepoint in the stream; see Codepoint IO.

With no block given, returns an enumerator.

Returns true if positioned at end-of-stream, false otherwise; see Position.

Raises IOError if the stream is not opened for reading.

An alias for eof

Returns the Encoding object that represents the encoding of the file. If the stream is write mode and no encoding is specified, returns nil.

Returns nil. Just for compatibility to IO.

Returns an object itself. Just for compatibility to IO.

Returns 0. Just for compatibility to IO.

Reads and returns the next 8-bit byte from the stream; see Byte IO.

Reads and returns the next character from the stream; see Character IO.

Reads and returns a line from the stream; assigns the return value to $_; see Line IO.

Returns the Encoding of the internal string if conversion is specified. Otherwise returns nil.

Returns false. Just for compatibility to IO.

An alias for size

Returns the current line number in self; see Line Number.

Sets the current line number in self to the given new_line_number; see Line Number.

Returns nil. Just for compatibility to IO.

Returns the current position (in bytes); see Position.

Sets the current position (in bytes); see Position.

See IO#pread.

See IO#putc.

See IO#read.

Reinitializes the stream with the given other (string or StringIO) and mode; see IO.new:

StringIO.open('foo') do |strio|
  p strio.string
  strio.reopen('bar')
  p strio.string
  other_strio = StringIO.new('baz')
  strio.reopen(other_strio)
  p strio.string
  other_strio.close
end

Output:

"foo"
"bar"
"baz"

Sets the current position and line number to zero; see Position and Line Number.

Sets the current position to the given integer offset (in bytes), with respect to a given constant whence; see Position.

Specify the encoding of the StringIO as ext_enc. Use the default external encoding if ext_enc is nil. 2nd argument int_enc and optional hash opt argument are ignored; they are for API compatibility to IO.

Sets the encoding according to the BOM (Byte Order Mark) in the string.

Returns self if the BOM is found, otherwise +nil.

Returns the size of the buffer string.

Returns underlying string:

StringIO.open('foo') do |strio|
  p strio.string
  strio.string = 'bar'
  p strio.string
end

Output:

"foo"
"bar"

Related: StringIO#string= (assigns the underlying string).

Assigns the underlying string as other_string, and sets position to zero; returns other_string:

StringIO.open('foo') do |strio|
  p strio.string
  strio.string = 'bar'
  p strio.string
end

Output:

"foo"
"bar"

Related: StringIO#string (returns the underlying string).

Returns true; implemented only for compatibility with other stream classes.

Returns the argument unchanged. Just for compatibility to IO.

Returns the current position (in bytes); see Position.

Truncates the buffer string to at most integer bytes. The stream must be opened for writing.

An alias for isatty

Pushes back (“unshifts”) an 8-bit byte onto the stream; see Byte IO.

Pushes back (“unshifts”) a character or integer onto the stream; see Character IO.

Appends the given string to the underlying buffer string. The stream must be opened for writing. If the argument is not a string, it will be converted to a string using to_s. Returns the number of bytes written. See IO#write.