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

VERSION

Public Class Methods

new(string = '', mode = 'r+') → new_stringio click to toggle source

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

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

open(string = '', mode = 'r+') {|strio| ... } click to toggle source

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.

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

Public Instance Methods

binmode → self click to toggle source

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

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;
}

close → nil click to toggle source

Closes self for both reading and writing.

Raises IOError if reading or writing is attempted.

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

close_read → nil click to toggle source

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

Raises IOError if reading is attempted.

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;
}

close_write → nil click to toggle source

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

Raises IOError if writing is attempted.

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;
}

closed? → true or false click to toggle source

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

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

closed_read? → true or false click to toggle source

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

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

closed_write? → true or false click to toggle source

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

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

each(sep, limit, chomp: false) {|line| } -> self click to toggle source

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

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

    RETURN_ENUMERATOR(self, argc, argv);

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

    while (!NIL_P(line = strio_getline(&arg, ptr))) {
        rb_yield(line);
    }
    return self;
}

Also aliased as: each_line

each_byte {|byte| ... } → self click to toggle source

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

With no block given, returns an enumerator.

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;
}

each_char {|c| ... } → self click to toggle source

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

With no block given, returns an enumerator.

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;
}

each_codepoint {|codepoint| ... } → self click to toggle source

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

With no block given, returns an enumerator.

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;
}

each_line(*args)

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 -> true or false click to toggle source

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

Raises IOError if the stream is not opened for reading.

static VALUE
strio_eof(VALUE self)
{
    if (strio_to_read(self)) return Qfalse;
    return Qtrue;
}

Also aliased as: eof?

eof?()

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 click to toggle source

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

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

fcntl(*args) click to toggle source

Raises NotImplementedError.

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

    UNREACHABLE;
}

fileno() click to toggle source

Returns nil. Just for compatibility to IO.

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

flush() click to toggle source

Returns an object itself. Just for compatibility to IO.

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

fsync() click to toggle source

Returns 0. Just for compatibility to IO.

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

getbyte → byte or nil click to toggle source

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

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

getc → character or nil click to toggle source

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

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 (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);
}

gets(sep = $/, chomp: false) → string or nil click to toggle source

gets(limit, chomp: false) → string or nil

gets(sep, limit, chomp: false) → string or nil

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

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) {
        return rb_enc_str_new(0, 0, get_enc(ptr));
    }

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

internal_encoding → encoding click to toggle source

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

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

isatty() click to toggle source

Returns false. Just for compatibility to IO.

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

Also aliased as: tty?

length → integer

Returns the size of the buffer string.

Alias for: size

lineno → current_line_number click to toggle source

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

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

lineno = new_line_number → new_line_number click to toggle source

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

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

pid() click to toggle source

Returns nil. Just for compatibility to IO.

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

pos → stream_position click to toggle source

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

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

pos = new_position → new_position click to toggle source

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

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;
}

pread(maxlen, offset) → string click to toggle source

pread(maxlen, offset, out_string) → string

See IO#pread.

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;
}

putc(obj) → obj click to toggle source

See IO#putc.

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)) {
        str = rb_str_substr(ch, 0, 1);
    }
    else {
        char c = NUM2CHR(ch);
        str = rb_str_new(&c, 1);
    }
    strio_write(self, str);
    return ch;
}

read([length [, outbuf]]) → string, outbuf, or nil click to toggle source

See IO#read.

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 && ptr->pos >= RSTRING_LEN(ptr->string)) {
                if (!NIL_P(str)) rb_str_resize(str, 0);
                return Qnil;
            }
            binary = 1;
            break;
        }
        /* fall through */
      case 0:
        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_associate(str, rb_ascii8bit_encoding());
        else
            rb_enc_copy(str, ptr->string);
    }
    ptr->pos += RSTRING_LEN(str);
    return str;
}

readlines(sep=$/, chomp: false) → array click to toggle source

readlines(limit, chomp: false) → array

readlines(sep, limit, chomp: false) → array

See IO#readlines.

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;
}

reopen(other, mode = 'r+') → self click to toggle source

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"

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

rewind → 0 click to toggle source

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

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

seek(offset, whence = SEEK_SET) → 0 click to toggle source

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

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

set_encoding(ext_enc, [int_enc[, opt]]) → strio click to toggle source

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.

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 (WRITABLE(self)) {
        rb_enc_associate(ptr->string, enc);
    }

    return self;
}

set_encoding_by_bom() click to toggle 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);
}

size → integer click to toggle source

Returns the size of the buffer string.

static VALUE
strio_size(VALUE self)
{
    VALUE string = StringIO(self)->string;
    if (NIL_P(string)) {
        rb_raise(rb_eIOError, "not opened");
    }
    return ULONG2NUM(RSTRING_LEN(string));
}

Also aliased as: length

string → string click to toggle source

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

static VALUE
strio_get_string(VALUE self)
{
    return StringIO(self)->string;
}

string = other_string → other_string click to toggle source

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

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 = OBJ_FROZEN(string) ? FMODE_READABLE : FMODE_READWRITE;
    ptr->pos = 0;
    ptr->lineno = 0;
    RB_OBJ_WRITE(self, &ptr->string, string);
    return string;
}

sync → true click to toggle source

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

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

sync=(p1) click to toggle source

Returns the argument unchanged. Just for compatibility to IO.

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

pos → stream_position click to toggle source

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

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

truncate(integer) → 0 click to toggle source

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

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

tty?()

Returns false. Just for compatibility to IO.

Alias for: isatty

ungetbyte(byte) → nil click to toggle source

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

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

    check_modifiable(ptr);
    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 {
        long cl;
        SafeStringValue(c);
        cl = RSTRING_LEN(c);
        if (cl > 0) {
            strio_unget_bytes(ptr, RSTRING_PTR(c), cl);
            RB_GC_GUARD(c);
        }
    }
    return Qnil;
}

ungetc(character) → nil click to toggle source

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

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

    check_modifiable(ptr);
    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);
        rb_enc_mbcput(cc, buf, enc);
        return strio_unget_bytes(ptr, buf, len);
    }
    else {
        SafeStringValue(c);
        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_bytes(ptr, RSTRING_PTR(c), RSTRING_LEN(c));
        RB_GC_GUARD(c);
        return Qnil;
    }
}

write(string, ...) → integer click to toggle source

syswrite(string) → integer

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.

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