class StringIO

Класс StringIO поддерживает доступ к строке как к потоку, в некотором отношении подобному классу IO.

Создать экземпляр StringIO можно с помощью:

• StringIO.new: возвращает новый объект StringIO, содержащий заданную строку.

• StringIO.open: передаёт новый объект StringIO заданному блоку.

Как и поток IO, поток StringIO имеет определённые свойства:

• Режим чтения/записи: можно ли читать из потока, записывать в него, добавлять данные и т. д.; см. раздел Режим чтения/записи.

• Режим данных: только текст или двоичные данные; см. раздел Режим данных.

• Кодировки: внутренняя и внешняя кодировки; см. раздел Кодировки.

• Позиция: место в потоке, откуда будет выполнено следующее чтение или куда будет выполнена следующая запись; см. раздел Позиция.

• Номер строки: специальная «позиция», ориентированная на строки (отличается от упомянутой выше позиции); см. раздел Номер строки.

• Открыт/закрыт: открыт или закрыт поток для чтения или записи. См. раздел Открытые/закрытые потоки.

• BOM: метка порядка байтов; см. раздел Метка порядка байтов.

Об этих примерах

В примерах на этой странице предполагается, что подключён StringIO:

require 'stringio'

И что определена эта константа:

TEXT = <<EOT
First line
Second line

Fourth line
Fifth line
EOT

Свойства потока

Режим чтения/записи

Краткое описание

В каждом разделе ниже описан режим чтения/записи.

Любой режим можно указать строкой или файловой константой; пример:

strio = StringIO.new('foo', 'a')
strio = StringIO.new('foo', File::WRONLY | File::APPEND)

'r': только для чтения

Режим задаётся одним из следующих способов:

• Строка: 'r'.

• Константа: File::RDONLY.

Начальное состояние:

strio = StringIO.new('foobarbaz', 'r')
strio.pos    # => 0            # Beginning-of-stream.
strio.string # => "foobarbaz"  # Not cleared.

Читать можно в любом месте:

strio.gets(3) # => "foo"
strio.gets(3) # => "bar"
strio.pos = 9
strio.gets(3) # => nil

Запись невозможна:

strio.write('foo')  # Raises IOError: not opened for writing

'w': только для записи

Режим задаётся одним из следующих способов:

• Строка: 'w'.

• Константа: File::WRONLY.

Начальное состояние:

strio = StringIO.new('foo', 'w')
strio.pos    # => 0   # Beginning of stream.
strio.string # => ""  # Initially cleared.

Записывать можно в любом месте (даже за концом потока):

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.

Чтение невозможно:

strio.read  # Raises IOError: not opened for reading

'a': только добавление

Режим задаётся одним из следующих способов:

• Строка: 'a'.

• Константа: File::WRONLY | File::APPEND.

Начальное состояние:

strio = StringIO.new('foo', 'a')
strio.pos    # => 0      # Beginning-of-stream.
strio.string # => "foo"  # Not cleared.

Записывать можно только в конце; позиция не влияет на запись:

strio.write('bar')
strio.string # => "foobar"
strio.write('baz')
strio.string # => "foobarbaz"
strio.pos = 400
strio.write('bat')
strio.string # => "foobarbazbat"

Чтение невозможно:

strio.gets  # Raises IOError: not opened for reading

'r+': чтение/запись

Режим задаётся одним из следующих способов:

• Строка: 'r+'.

• Константа: File::RDRW.

Начальное состояние:

strio = StringIO.new('foobar', 'r+')
strio.pos    # => 0         # Beginning-of-stream.
strio.string # => "foobar"  # Not cleared.

Записывать можно в любом месте (даже за концом потока):

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.

Читать можно в любом месте:

strio.pos = 0
strio.gets(3) # => "FOO"
strio.pos = 6
strio.gets(3) # => "BAZ"
strio.pos = 400
strio.gets(3) # => nil

'w+': чтение/запись (изначально очищен)

Режим задаётся одним из следующих способов:

• Строка: 'w+'.

• Константа: File::RDWR | File::TRUNC.

Начальное состояние:

strio = StringIO.new('foo', 'w+')
strio.pos    # => 0   # Beginning-of-stream.
strio.string # => ""  # Truncated.

Записывать можно в любом месте (даже за концом потока):

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.

Читать можно в любом месте:

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+': чтение/добавление

Режим задаётся одним из следующих способов:

• Строка: 'a+'.

• Константа: File::RDWR | File::APPEND.

Начальное состояние:

strio = StringIO.new('foo', 'a+')
strio.pos    # => 0      # Beginning-of-stream.
strio.string # => "foo"  # Not cleared.

Записывать можно только в конце; rewind; позиция не влияет на запись:

strio.write('bar')
strio.string # => "foobar"
strio.write('baz')
strio.string # => "foobarbaz"
strio.pos = 400
strio.write('bat')
strio.string # => "foobarbazbat"

Читать можно в любом месте:

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 режим

Чтобы указать, следует ли обрабатывать поток как текст или как двоичные данные, к любому из описанных выше строковых режимов чтения/записи можно добавить один из следующих суффиксов:

• 't': текст; инициализирует кодировку как Encoding::UTF_8.

• 'b': двоичные данные; инициализирует кодировку как Encoding::ASCII_8BIT.

Если не указан ни один из них, по умолчанию поток содержит текстовые данные.

Примеры:

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)>

Если режим данных указан, режим чтения/записи нельзя опускать:

StringIO.new(data, 'b')  # Raises ArgumentError: invalid access mode b

Текстовый поток можно преобразовать в двоичный, вызвав метод экземпляра binmode; двоичный поток нельзя преобразовать в текстовый.

Кодировки

У потока есть кодировка; см. раздел Кодировки.

Начальная кодировка нового или повторно открытого потока зависит от его режима данных:

• Текст: Encoding::UTF_8.

• Двоичные данные: Encoding::ASCII_8BIT.

Важны следующие методы экземпляра:

• external_encoding: возвращает текущую кодировку потока в виде объекта Encoding.

• internal_encoding: возвращает nil; у потока нет внутренней кодировки.

• set_encoding: задаёт кодировку потока.

• set_encoding_by_bom: задаёт кодировку потока в соответствии с BOM (меткой порядка байтов) потока.

Примеры:

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>

Позиция

У потока есть позиция — целочисленное смещение (в байтах) внутри потока. Начальная позиция потока равна нулю.

Получение и установка позиции

Каждый из этих методов устанавливает позицию нового или повторно открытого потока в ноль:

• ::new: возвращает новый поток.

• ::open: передаёт новый поток блоку.

• reopen: повторно инициализирует поток.

Каждый из этих методов запрашивает, получает или устанавливает позицию, не изменяя при этом поток иным образом:

• eof?: возвращает, находится ли позиция в конце потока.

• pos: возвращает позицию.

• pos=: задаёт позицию.

• rewind: устанавливает позицию в ноль.

• seek: задаёт позицию.

Примеры:

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

Позиция до и после чтения

За исключением pread, метод чтения из потока (см. раздел Основы чтения) начинает чтение с текущей позиции.

За исключением pread, метод чтения перемещает позицию за пределы прочитанной подстроки.

Примеры:

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.

Позиция до и после записи

Каждый из этих методов начинает запись с текущей позиции и перемещает позицию в конец записанной подстроки:

• putc: записывает заданный символ.

• write: записывает заданные объекты как строки.

• Kernel#puts: записывает заданные объекты как строки, добавляя после каждой перевод строки.

Примеры:

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

Каждый из этих методов записывает данные перед текущей позицией и уменьшает позицию, чтобы записанные данные стали следующими для чтения:

• ungetbyte: помещает заданный байт обратно в поток.

• ungetc: помещает заданный символ обратно в поток.

Примеры:

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"

Этот метод не влияет на позицию:

• truncate: усекает строку потока до заданного размера.

Примеры:

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

Номер строки

У потока есть номер строки, изначально равный нулю:

• Метод lineno возвращает номер строки.

• Метод lineno= задаёт номер строки.

На номер строки может влиять чтение (но никогда — запись); как правило, номер строки увеличивается каждый раз при чтении разделителя записей (по умолчанию: "\n").

Примеры:

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

Установка позиции не влияет на номер строки:

strio.pos = 0
strio.lineno # => 4
strio.gets   # => "First line\n"
strio.pos    # => 11
strio.lineno # => 5

И установка номера строки не влияет на позицию:

strio.lineno = 10
strio.pos    # => 11
strio.gets   # => "Second line\n"
strio.lineno # => 11
strio.pos    # => 23

Открытые/закрытые потоки

Новый поток открыт для чтения или записи и может быть открыт для обеих операций; см. раздел Режим чтения/записи.

Каждый из этих методов устанавливает режим чтения/записи нового или повторно открытого потока:

• ::new: возвращает новый поток.

• ::open: передаёт новый поток блоку.

• reopen: повторно инициализирует поток.

Другие важные методы:

• close: закрывает поток для чтения и записи.

• close_read: закрывает поток для чтения.

• close_write: закрывает поток для записи.

• closed?: возвращает, закрыт ли поток для чтения и записи.

• closed_read?: возвращает, закрыт ли поток для чтения.

• closed_write?: возвращает, закрыт ли поток для записи.

BOM (метка порядка байтов)

Строка, переданная в ::new, ::open или reopen, может содержать в начале необязательную BOM (метку порядка байтов); BOM может повлиять на кодировку потока.

BOM (если она указана):

• Хранится как часть строки потока.

• Не влияет на кодировку немедленно.

• Изначально считается частью потока.

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.

Можно вызвать метод экземпляра set_encoding_by_bom, чтобы «активировать» сохранённую BOM; после этого BOM:

• По-прежнему хранится как часть строки потока.

• Определяет (и может изменять) кодировку потока.

• Больше не считается частью потока.

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.

Базовый ввод-вывод потока

Базовое чтение

Для чтения из потока можно использовать следующие методы экземпляра:

• getbyte: читает и возвращает следующий байт.

• getc: читает и возвращает следующий символ.

• gets: читает и возвращает всю следующую строку или её часть.

• read: читает и возвращает все оставшиеся данные потока или их часть.

• readlines: читает оставшиеся данные потока и возвращает массив его строк.

• Kernel#readline: работает как gets, но вызывает исключение при достижении конца потока.

Перебирать элементы потока можно с помощью следующих методов экземпляра:

• each_byte: читает каждый оставшийся байт и передаёт его блоку.

• each_char: читает каждый оставшийся символ и передаёт его блоку.

• each_codepoint: читает каждую оставшуюся кодовую точку и передаёт её блоку.

• each_line: читает каждую оставшуюся строку целиком или частично и передаёт прочитанную строку блоку

Этот метод экземпляра полезен в многопоточном приложении:

• pread: читает и возвращает весь поток или его часть.

Базовая запись

Для записи в поток с перемещением позиции можно использовать следующие методы экземпляра:

• putc: записывает заданный символ.

• write: записывает заданные объекты в виде строк.

• Kernel#puts записывает заданные объекты в виде строк, добавляя после каждой символ новой строки.

С помощью следующих методов экземпляра можно «поместить данные в начало» потока: каждый из них записывает данные перед текущей позицией и уменьшает позицию, чтобы записанные данные стали следующими для чтения.

• ungetbyte: помещает заданный байт перед текущей позицией.

• ungetc: помещает заданный символ перед текущей позицией.

Ещё один метод записи:

• truncate: обрезает строку потока до заданного размера.

Ввод-вывод строк

Чтение:

• gets: читает и возвращает следующую строку.

• Kernel#readline: работает как gets, но вызывает исключение при достижении конца потока.

• readlines: читает оставшиеся данные потока и возвращает массив его строк.

• each_line: читает каждую оставшуюся строку и передаёт её блоку

Запись:

• Kernel#puts: записывает заданные объекты, добавляя после каждого символ новой строки.

Ввод-вывод символов

Чтение:

• each_char: читает каждый оставшийся символ и передаёт его блоку.

• getc: читает и возвращает следующий символ.

Запись:

• putc: записывает заданный символ.

• ungetc.: помещает заданный символ перед текущей позицией.

Ввод-вывод байтов

Чтение:

• each_byte: читает каждый оставшийся байт и передаёт его блоку.

• getbyte: читает и возвращает следующий байт.

Запись:

• ungetbyte: помещает заданный байт перед текущей позицией.

Ввод-вывод кодовых точек

Чтение:

• each_codepoint: читает каждую оставшуюся кодовую точку и передаёт её блоку.