# class StringIO

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

MAX_LENGTH

  Maximum length that a `StringIO` instance can hold

VERSION

  The version string

### Public Class Methods

new(string = '', mode = 'r+') → new_stringio
Source

    static VALUE
    strio_initialize(int argc, VALUE *argv, VALUE self)
    {
        struct StringIO *ptr = check_strio(self);

        if (!ptr) {
            DATA_PTR(self) = ptr = strio_alloc();
        }
        rb_call_super(0, 0);
        return strio_init(argc, argv, ptr, self);
    }

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

open(string = '', mode = 'r+') {|strio| ... }
Source

    static VALUE
    strio_s_open(int argc, VALUE *argv, VALUE klass)
    {
        VALUE obj = rb_class_new_instance_kw(argc, argv, klass, RB_PASS_CALLED_KEYWORDS);
        if (!rb_block_given_p()) return obj;
        return rb_ensure(rb_yield, obj, strio_finalize, obj);
    }

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`.

### Public Instance Methods

binmode → self
Source

    static VALUE
    strio_binmode(VALUE self)
    {
        struct StringIO *ptr = StringIO(self);
        rb_encoding *enc = rb_ascii8bit_encoding();

        ptr->enc = enc;
        if (WRITABLE(self)) {
            rb_enc_associate(ptr->string, enc);
        }
        return self;
    }

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

close → nil
Source

    static VALUE
    strio_close(VALUE self)
    {
        StringIO(self);
        RBASIC(self)->flags &= ~STRIO_READWRITE;
        return Qnil;
    }

Closes `self` for both reading and writing.

Raises `IOError` if reading or writing is attempted.

Related: `StringIO#close_read`, `StringIO#close_write`.

close_read → nil
Source

    static VALUE
    strio_close_read(VALUE self)
    {
        struct StringIO *ptr = StringIO(self);
        if (!(ptr->flags & FMODE_READABLE)) {
            rb_raise(rb_eIOError, "closing non-duplex IO for reading");
        }
        RBASIC(self)->flags &= ~STRIO_READABLE;
        return Qnil;
    }

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

Raises `IOError` if reading is attempted.

Related: `StringIO#close`, `StringIO#close_write`.

close_write → nil
Source

    static VALUE
    strio_close_write(VALUE self)
    {
        struct StringIO *ptr = StringIO(self);
        if (!(ptr->flags & FMODE_WRITABLE)) {
            rb_raise(rb_eIOError, "closing non-duplex IO for writing");
        }
        RBASIC(self)->flags &= ~STRIO_WRITABLE;
        return Qnil;
    }

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

Raises `IOError` if writing is attempted.

Related: `StringIO#close`, `StringIO#close_read`.

closed? → true or false
Source

    static VALUE
    strio_closed(VALUE self)
    {
        StringIO(self);
        if (!CLOSED(self)) return Qfalse;
        return Qtrue;
    }

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

closed_read? → true or false
Source

    static VALUE
    strio_closed_read(VALUE self)
    {
        StringIO(self);
        if (READABLE(self)) return Qfalse;
        return Qtrue;
    }

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

closed_write? → true or false
Source

    static VALUE
    strio_closed_write(VALUE self)
    {
        StringIO(self);
        if (WRITABLE(self)) return Qfalse;
        return Qtrue;
    }

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

each
Source
Also aliased as: each_line
each_byte {|byte| ... } → self
Source

    static VALUE
    strio_each_byte(VALUE self)
    {
        struct StringIO *ptr;

        RETURN_ENUMERATOR(self, 0, 0);

        while ((ptr = strio_to_read(self)) != NULL) {
            char c = RSTRING_PTR(ptr->string)[ptr->pos++];
            rb_yield(CHR2FIX(c));
        }
        return self;
    }

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

With no block given, returns an enumerator.

each_char {|c| ... } → self
Source

    static VALUE
    strio_each_char(VALUE self)
    {
        VALUE c;

        RETURN_ENUMERATOR(self, 0, 0);

        while (!NIL_P(c = strio_getc(self))) {
            rb_yield(c);
        }
        return self;
    }

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

With no block given, returns an enumerator.

each_codepoint {|codepoint| ... } → self
Source

    static VALUE
    strio_each_codepoint(VALUE self)
    {
        struct StringIO *ptr;
        rb_encoding *enc;
        unsigned int c;
        int n;

        RETURN_ENUMERATOR(self, 0, 0);

        ptr = readable(self);
        enc = get_enc(ptr);
        while ((ptr = strio_to_read(self)) != NULL) {
            c = rb_enc_codepoint_len(RSTRING_PTR(ptr->string)+ptr->pos,
                                     RSTRING_END(ptr->string), &n, enc);
            ptr->pos += n;
            rb_yield(UINT2NUM(c));
        }
        return self;
    }

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

With no block given, returns an enumerator.

each_line(sep = $/, chomp: false) {|line| ... } → self
each_line(limit, chomp: false) {|line| ... } → self
each_line(sep, limit, chomp: false) {|line| ... } → self

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

Alias for: each
eof
Source
Also aliased as: eof?
eof? → true or false

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

Raises `IOError` if the stream is not opened for reading.

Alias for: eof
external_encoding → encoding
Source

    static VALUE
    strio_external_encoding(VALUE self)
    {
        struct StringIO *ptr = StringIO(self);
        return rb_enc_from_encoding(get_enc(ptr));
    }

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

fcntl (*args)
Source

    static VALUE
    strio_unimpl(int argc, VALUE *argv, VALUE self)
    {
        StringIO(self);
        rb_notimplement();

        UNREACHABLE;
    }

Raises `NotImplementedError`.

fileno ()
Source

    static VALUE
    strio_nil(VALUE self)
    {
        StringIO(self);
        return Qnil;
    }

Returns `nil`. Just for compatibility to `IO`.

flush ()
Source

    static VALUE
    strio_self(VALUE self)
    {
        StringIO(self);
        return self;
    }

Returns an object itself. Just for compatibility to `IO`.

fsync ()
Source

    static VALUE
    strio_0(VALUE self)
    {
        StringIO(self);
        return INT2FIX(0);
    }

Returns 0. Just for compatibility to `IO`.

getbyte → byte or nil
Source

    static VALUE
    strio_getbyte(VALUE self)
    {
        struct StringIO *ptr = readable(self);
        int c;
        if (NIL_P(ptr->string) || ptr->pos >= RSTRING_LEN(ptr->string)) {
            return Qnil;
        }
        c = RSTRING_PTR(ptr->string)[ptr->pos++];
        return CHR2FIX(c);
    }

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

getc → character or nil
Source

    static VALUE
    strio_getc(VALUE self)
    {
        struct StringIO *ptr = readable(self);
        rb_encoding *enc = get_enc(ptr);
        VALUE str = ptr->string;
        long pos = ptr->pos;
        int len;
        char *p;

        if (NIL_P(str) || pos >= RSTRING_LEN(str)) {
            return Qnil;
        }
        p = RSTRING_PTR(str)+pos;
        len = rb_enc_mbclen(p, RSTRING_END(str), enc);
        ptr->pos += len;
        return enc_subseq(str, pos, len, enc);
    }

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

gets(sep = $/, chomp: false) → string or nil
gets(limit, chomp: false) → string or nil
gets(sep, limit, chomp: false) → string or nil
Source

    static VALUE
    strio_gets(int argc, VALUE *argv, VALUE self)
    {
        struct StringIO *ptr = readable(self);
        struct getline_arg arg;
        VALUE str;

        if (prepare_getline_args(ptr, &arg, argc, argv)->limit == 0) {
            if (NIL_P(ptr->string)) return Qnil;
            return rb_enc_str_new(0, 0, get_enc(ptr));
        }

        str = strio_getline(&arg, ptr);
        rb_lastline_set(str);
        return str;
    }

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

internal_encoding → encoding
Source

    static VALUE
    strio_internal_encoding(VALUE self)
    {
        return Qnil;
    }

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

isatty ()
Source

    static VALUE
    strio_false(VALUE self)
    {
        StringIO(self);
        return Qfalse;
    }

Returns `false`. Just for compatibility to `IO`.

Also aliased as: tty?
length → integer

Returns the size of the buffer string.

Alias for: size
lineno → current_line_number
Source

    static VALUE
    strio_get_lineno(VALUE self)
    {
        return LONG2NUM(StringIO(self)->lineno);
    }

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

lineno = new_line_number → new_line_number
Source

    static VALUE
    strio_set_lineno(VALUE self, VALUE lineno)
    {
        StringIO(self)->lineno = NUM2LONG(lineno);
        return lineno;
    }

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

pid ()
Source

    static VALUE
    strio_nil(VALUE self)
    {
        StringIO(self);
        return Qnil;
    }

Returns `nil`. Just for compatibility to `IO`.

pos → stream_position
Source

    static VALUE
    strio_get_pos(VALUE self)
    {
        return LONG2NUM(StringIO(self)->pos);
    }

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

pos = new_position → new_position
Source

    static VALUE
    strio_set_pos(VALUE self, VALUE pos)
    {
        struct StringIO *ptr = StringIO(self);
        long p = NUM2LONG(pos);
        if (p < 0) {
            error_inval(0);
        }
        ptr->pos = p;
        return pos;
    }

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

pread(maxlen, offset) → string
pread(maxlen, offset, out_string) → string
Source

    static VALUE
    strio_pread(int argc, VALUE *argv, VALUE self)
    {
        VALUE rb_len, rb_offset, rb_buf;
        rb_scan_args(argc, argv, "21", &rb_len, &rb_offset, &rb_buf);
        long len = NUM2LONG(rb_len);
        long offset = NUM2LONG(rb_offset);

        if (len < 0) {
            rb_raise(rb_eArgError, "negative string size (or size too big): %" PRIsVALUE, rb_len);
        }

        if (len == 0) {
            if (NIL_P(rb_buf)) {
                return rb_str_new("", 0);
            }
            return rb_buf;
        }

        if (offset < 0) {
            rb_syserr_fail_str(EINVAL, rb_sprintf("pread: Invalid offset argument: %" PRIsVALUE, rb_offset));
        }

        struct StringIO *ptr = readable(self);

        if (offset >= RSTRING_LEN(ptr->string)) {
            rb_eof_error();
        }

        if (NIL_P(rb_buf)) {
            return strio_substr(ptr, offset, len, rb_ascii8bit_encoding());
        }

        long rest = RSTRING_LEN(ptr->string) - offset;
        if (len > rest) len = rest;
        rb_str_resize(rb_buf, len);
        rb_enc_associate(rb_buf, rb_ascii8bit_encoding());
        MEMCPY(RSTRING_PTR(rb_buf), RSTRING_PTR(ptr->string) + offset, char, len);
        return rb_buf;
    }

See `IO#pread`.

putc(obj) → obj
Source

    static VALUE
    strio_putc(VALUE self, VALUE ch)
    {
        struct StringIO *ptr = writable(self);
        VALUE str;

        check_modifiable(ptr);
        if (RB_TYPE_P(ch, T_STRING)) {
            if (NIL_P(ptr->string)) return ch;
            str = rb_str_substr(ch, 0, 1);
        }
        else {
            char c = NUM2CHR(ch);
            if (NIL_P(ptr->string)) return ch;
            str = rb_str_new(&c, 1);
        }
        strio_write(self, str);
        return ch;
    }

See `IO#putc`.

read([length [, outbuf]]) → string, outbuf, or nil
Source

    static VALUE
    strio_read(int argc, VALUE *argv, VALUE self)
    {
        struct StringIO *ptr = readable(self);
        VALUE str = Qnil;
        long len;
        int binary = 0;

        switch (argc) {
          case 2:
            str = argv[1];
            if (!NIL_P(str)) {
                StringValue(str);
                rb_str_modify(str);
            }
            /* fall through */
          case 1:
            if (!NIL_P(argv[0])) {
                len = NUM2LONG(argv[0]);
                if (len < 0) {
                    rb_raise(rb_eArgError, "negative length %ld given", len);
                }
                if (len > 0 &&
                    (NIL_P(ptr->string) || ptr->pos >= RSTRING_LEN(ptr->string))) {
                    if (!NIL_P(str)) rb_str_resize(str, 0);
                    return Qnil;
                }
                binary = 1;
                break;
            }
            /* fall through */
          case 0:
            if (NIL_P(ptr->string)) return Qnil;
            len = RSTRING_LEN(ptr->string);
            if (len <= ptr->pos) {
                rb_encoding *enc = get_enc(ptr);
                if (NIL_P(str)) {
                    str = rb_str_new(0, 0);
                }
                else {
                    rb_str_resize(str, 0);
                }
                rb_enc_associate(str, enc);
                return str;
            }
            else {
                len -= ptr->pos;
            }
            break;
          default:
            rb_error_arity(argc, 0, 2);
        }
        if (NIL_P(str)) {
            rb_encoding *enc = binary ? rb_ascii8bit_encoding() : get_enc(ptr);
            str = strio_substr(ptr, ptr->pos, len, enc);
        }
        else {
            long rest = RSTRING_LEN(ptr->string) - ptr->pos;
            if (len > rest) len = rest;
            rb_str_resize(str, len);
            MEMCPY(RSTRING_PTR(str), RSTRING_PTR(ptr->string) + ptr->pos, char, len);
            if (!binary) {
                rb_enc_copy(str, ptr->string);
            }
        }
        ptr->pos += RSTRING_LEN(str);
        return str;
    }

See `IO#read`.

readlines(sep=$/, chomp: false) → array
readlines(limit, chomp: false) → array
readlines(sep, limit, chomp: false) → array
Source

    static VALUE
    strio_readlines(int argc, VALUE *argv, VALUE self)
    {
        VALUE ary, line;
        struct StringIO *ptr = readable(self);
        struct getline_arg arg;

        if (prepare_getline_args(ptr, &arg, argc, argv)->limit == 0) {
            rb_raise(rb_eArgError, "invalid limit: 0 for readlines");
        }

        ary = rb_ary_new();
        while (!NIL_P(line = strio_getline(&arg, ptr))) {
            rb_ary_push(ary, line);
        }
        return ary;
    }

See `IO#readlines`.

reopen(other, mode = 'r+') → self
Source

    static VALUE
    strio_reopen(int argc, VALUE *argv, VALUE self)
    {
        rb_io_taint_check(self);
        if (argc == 1 && !RB_TYPE_P(*argv, T_STRING)) {
            return strio_copy(self, *argv);
        }
        return strio_init(argc, argv, StringIO(self), self);
    }

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"

rewind → 0
Source

    static VALUE
    strio_rewind(VALUE self)
    {
        struct StringIO *ptr = StringIO(self);
        ptr->pos = 0;
        ptr->lineno = 0;
        return INT2FIX(0);
    }

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

seek(offset, whence = SEEK_SET) → 0
Source

    static VALUE
    strio_seek(int argc, VALUE *argv, VALUE self)
    {
        VALUE whence;
        struct StringIO *ptr = StringIO(self);
        long amount, offset;

        rb_scan_args(argc, argv, "11", NULL, &whence);
        amount = NUM2LONG(argv[0]);
        if (CLOSED(self)) {
            rb_raise(rb_eIOError, "closed stream");
        }
        switch (NIL_P(whence) ? 0 : NUM2LONG(whence)) {
          case 0:
            offset = 0;
            break;
          case 1:
            offset = ptr->pos;
            break;
          case 2:
            offset = RSTRING_LEN(ptr->string);
            break;
          default:
            error_inval("invalid whence");
        }
        if (amount > LONG_MAX - offset || amount + offset < 0) {
            error_inval(0);
        }
        ptr->pos = amount + offset;
        return INT2FIX(0);
    }

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

set_encoding(ext_enc, [int_enc[, opt]]) → strio
Source

    static VALUE
    strio_set_encoding(int argc, VALUE *argv, VALUE self)
    {
        rb_encoding* enc;
        struct StringIO *ptr = StringIO(self);
        VALUE ext_enc, int_enc, opt;

        argc = rb_scan_args(argc, argv, "11:", &ext_enc, &int_enc, &opt);

        if (NIL_P(ext_enc)) {
            enc = rb_default_external_encoding();
        }
        else {
            enc = rb_find_encoding(ext_enc);
            if (!enc) {
                rb_io_enc_t convconfig;
                int oflags, fmode;
                VALUE vmode = rb_str_append(rb_str_new_cstr("r:"), ext_enc);
                rb_io_extract_modeenc(&vmode, 0, Qnil, &oflags, &fmode, &convconfig);
                enc = convconfig.enc2;
            }
        }
        ptr->enc = enc;
        if (!NIL_P(ptr->string) && WRITABLE(self)) {
            rb_enc_associate(ptr->string, enc);
        }

        return self;
    }

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`.

set_encoding_by_bom → strio or nil
Source

    static VALUE
    strio_set_encoding_by_bom(VALUE self)
    {
        struct StringIO *ptr = StringIO(self);

        if (!set_encoding_by_bom(ptr)) return Qnil;
        return rb_enc_from_encoding(ptr->enc);
    }

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

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

size → integer
Source

    static VALUE
    strio_size(VALUE self)
    {
        VALUE string = StringIO(self)->string;
        if (NIL_P(string)) {
            return INT2FIX(0);
        }
        return ULONG2NUM(RSTRING_LEN(string));
    }

Returns the size of the buffer string.

Also aliased as: length
string → string
Source

    static VALUE
    strio_get_string(VALUE self)
    {
        return StringIO(self)->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).

string = other_string → other_string
Source

    static VALUE
    strio_set_string(VALUE self, VALUE string)
    {
        struct StringIO *ptr = StringIO(self);

        rb_io_taint_check(self);
        ptr->flags &= ~FMODE_READWRITE;
        StringValue(string);
        ptr->flags = readonly_string_p(string) ? FMODE_READABLE : FMODE_READWRITE;
        ptr->pos = 0;
        ptr->lineno = 0;
        RB_OBJ_WRITE(self, &ptr->string, string);
        return 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).

sync → true
Source

    static VALUE
    strio_get_sync(VALUE self)
    {
        StringIO(self);
        return Qtrue;
    }

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

sync= (p1)
Source

    static VALUE
    strio_first(VALUE self, VALUE arg)
    {
        StringIO(self);
        return arg;
    }

Returns the argument unchanged. Just for compatibility to `IO`.

pos → stream_position
Source

    static VALUE
    strio_get_pos(VALUE self)
    {
        return LONG2NUM(StringIO(self)->pos);
    }

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

truncate(integer) → 0
Source

    static VALUE
    strio_truncate(VALUE self, VALUE len)
    {
        VALUE string = writable(self)->string;
        long l = NUM2LONG(len);
        long plen;
        if (l < 0) {
            error_inval("negative length");
        }
        if (NIL_P(string)) return 0;
        plen = RSTRING_LEN(string);
        rb_str_resize(string, l);
        if (plen < l) {
            MEMZERO(RSTRING_PTR(string) + plen, char, l - plen);
        }
        return INT2FIX(0);
    }

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

tty? ()

Returns `false`. Just for compatibility to `IO`.

Alias for: isatty
ungetbyte(byte) → nil
Source

    static VALUE
    strio_ungetbyte(VALUE self, VALUE c)
    {
        struct StringIO *ptr = readable(self);

        check_modifiable(ptr);
        if (NIL_P(ptr->string)) return Qnil;
        if (NIL_P(c)) return Qnil;
        if (RB_INTEGER_TYPE_P(c)) {
            /* rb_int_and() not visible from exts */
            VALUE v = rb_funcall(c, '&', 1, INT2FIX(0xff));
            const char cc = NUM2INT(v) & 0xFF;
            strio_unget_bytes(ptr, &cc, 1);
        }
        else {
            StringValue(c);
            strio_unget_string(ptr, c);
        }
        return Qnil;
    }

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

ungetc(character) → nil
Source

    static VALUE
    strio_ungetc(VALUE self, VALUE c)
    {
        struct StringIO *ptr = readable(self);
        rb_encoding *enc, *enc2;

        check_modifiable(ptr);
        if (NIL_P(ptr->string)) return Qnil;
        if (NIL_P(c)) return Qnil;
        if (RB_INTEGER_TYPE_P(c)) {
            int len, cc = NUM2INT(c);
            char buf[16];

            enc = rb_enc_get(ptr->string);
            len = rb_enc_codelen(cc, enc);
            if (len <= 0) {
                rb_enc_uint_chr(cc, enc); /* to raise an exception */
                UNREACHABLE;
            }
            rb_enc_mbcput(cc, buf, enc);
            return strio_unget_bytes(ptr, buf, len);
        }
        else {
            StringValue(c);
            if (RSTRING_LEN(c) == 0) return Qnil;
            enc = rb_enc_get(ptr->string);
            enc2 = rb_enc_get(c);
            if (enc != enc2 && enc != rb_ascii8bit_encoding()) {
                c = rb_str_conv_enc(c, enc2, enc);
            }
            strio_unget_string(ptr, c);
            return Qnil;
        }
    }

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

write(string, ...) → integer
syswrite(string) → integer
Source

    static VALUE
    strio_write_m(int argc, VALUE *argv, VALUE self)
    {
        long len = 0;
        while (argc-- > 0) {
            /* StringIO can't exceed long limit */
            len += strio_write(self, *argv++);
        }
        return LONG2NUM(len);
    }

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`.