Pseudo I/O on String object.

Methods
B
C
E
F
G
I
L
N
O
P
R
S
T
U
W
Included Modules
Class Public methods
StringIO.new(string=""[, mode])

Creates new StringIO instance from with string and mode.

Source: show 

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);
    strio_init(argc, argv, ptr, self);
    return self;
}
StringIO.open(string=""[, mode]) {|strio| ...}

Equivalent to ::new except that when it is called with a block, it yields with the new instance and closes it, and returns the result which returned from the block.

Source: show 

static VALUE
strio_s_open(int argc, VALUE *argv, VALUE klass)
{
    VALUE obj = rb_class_new_instance(argc, argv, klass);
    if (!rb_block_given_p()) return obj;
    return rb_ensure(rb_yield, obj, strio_finalize, obj);
}
Instance Public methods
strio.binmode → true

Source: show 

#define strio_binmode strio_self
bytes()

This is a deprecated alias for each_byte.

Source: show 

static VALUE
strio_bytes(VALUE self)
{
    rb_warn("StringIO#bytes is deprecated; use #each_byte instead");
    if (!rb_block_given_p())
        return rb_enumeratorize(self, ID2SYM(rb_intern("each_byte")), 0, 0);
    return strio_each_byte(self);
}
chars()

This is a deprecated alias for each_char.

Source: show 

static VALUE
strio_chars(VALUE self)
{
    rb_warn("StringIO#chars is deprecated; use #each_char instead");
    if (!rb_block_given_p())
        return rb_enumeratorize(self, ID2SYM(rb_intern("each_char")), 0, 0);
    return strio_each_char(self);
}
strio.close → nil

Closes strio. The strio is unavailable for any further data operations; an IOError is raised if such an attempt is made.

Source: show 

static VALUE
strio_close(VALUE self)
{
    StringIO(self);
    if (CLOSED(self)) {
        rb_raise(rb_eIOError, "closed stream");
    }
    RBASIC(self)->flags &= ~STRIO_READWRITE;
    return Qnil;
}
strio.close_read → nil

Closes the read end of a StringIO. Will raise an IOError if the strio is not readable.

Source: show 

static VALUE
strio_close_read(VALUE self)
{
    StringIO(self);
    if (!READABLE(self)) {
        rb_raise(rb_eIOError, "closing non-duplex IO for reading");
    }
    RBASIC(self)->flags &= ~STRIO_READABLE;
    return Qnil;
}
strio.close_write → nil

Closes the write end of a StringIO. Will raise an IOError if the strio is not writeable.

Source: show 

static VALUE
strio_close_write(VALUE self)
{
    StringIO(self);
    if (!WRITABLE(self)) {
        rb_raise(rb_eIOError, "closing non-duplex IO for writing");
    }
    RBASIC(self)->flags &= ~STRIO_WRITABLE;
    return Qnil;
}
strio.closed? → true or false

Returns true if strio is completely closed, false otherwise.

Source: show 

static VALUE
strio_closed(VALUE self)
{
    StringIO(self);
    if (!CLOSED(self)) return Qfalse;
    return Qtrue;
}
strio.closed_read? → true or false

Returns true if strio is not readable, false otherwise.

Source: show 

static VALUE
strio_closed_read(VALUE self)
{
    StringIO(self);
    if (READABLE(self)) return Qfalse;
    return Qtrue;
}
strio.closed_write? → true or false

Returns true if strio is not writable, false otherwise.

Source: show 

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

This is a deprecated alias for each_codepoint.

Source: show 

static VALUE
strio_codepoints(VALUE self)
{
    rb_warn("StringIO#codepoints is deprecated; use #each_codepoint instead");
    if (!rb_block_given_p())
        return rb_enumeratorize(self, ID2SYM(rb_intern("each_codepoint")), 0, 0);
    return strio_each_codepoint(self);
}
strio.each(sep=$/) {|line| block } → strio strio.each(limit) {|line| block } → strio strio.each(sep, limit) {|line| block } → strio strio.each(...) → anEnumerator strio.each_line(sep=$/) {|line| block } → strio strio.each_line(limit) {|line| block } → strio strio.each_line(sep,limit) {|line| block } → strio strio.each_line(...) → anEnumerator

See IO#each.

Source: show 

static VALUE
strio_each(int argc, VALUE *argv, VALUE self)
{
    VALUE line;

    StringIO(self);
    RETURN_ENUMERATOR(self, argc, argv);

    if (argc > 0 && !NIL_P(argv[argc-1]) && NIL_P(rb_check_string_type(argv[argc-1])) &&
        NUM2LONG(argv[argc-1]) == 0) {
        rb_raise(rb_eArgError, "invalid limit: 0 for each_line");
    }

    while (!NIL_P(line = strio_getline(argc, argv, readable(self)))) {
        rb_yield(line);
    }
    return self;
}
strio.each_byte {|byte| block } → strio strio.each_byte → anEnumerator

See IO#each_byte.

Source: show 

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

    RETURN_ENUMERATOR(self, 0, 0);

    while (ptr->pos < RSTRING_LEN(ptr->string)) {
        char c = RSTRING_PTR(ptr->string)[ptr->pos++];
        rb_yield(CHR2FIX(c));
    }
    return self;
}
strio.each_char {|char| block } → strio strio.each_char → anEnumerator

See IO#each_char.

Source: show 

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;
}
strio.each_codepoint {|c| block } → strio strio.each_codepoint → anEnumerator

See IO#each_codepoint.

Source: show 

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 = rb_enc_get(ptr->string);
    for (;;) {
        if (ptr->pos >= RSTRING_LEN(ptr->string)) {
            return self;
        }

        c = rb_enc_codepoint_len(RSTRING_PTR(ptr->string)+ptr->pos,
                                 RSTRING_END(ptr->string), &n, enc);
        rb_yield(UINT2NUM(c));
        ptr->pos += n;
    }
    return self;
}
strio.each_line(sep=$/) {|line| block } → strio strio.each_line(limit) {|line| block } → strio strio.each_line(sep,limit) {|line| block } → strio strio.each_line(...) → anEnumerator

See IO#each.

Source: show 

static VALUE
strio_each(int argc, VALUE *argv, VALUE self)
{
    VALUE line;

    StringIO(self);
    RETURN_ENUMERATOR(self, argc, argv);

    if (argc > 0 && !NIL_P(argv[argc-1]) && NIL_P(rb_check_string_type(argv[argc-1])) &&
        NUM2LONG(argv[argc-1]) == 0) {
        rb_raise(rb_eArgError, "invalid limit: 0 for each_line");
    }

    while (!NIL_P(line = strio_getline(argc, argv, readable(self)))) {
        rb_yield(line);
    }
    return self;
}
strio.eof → true or false strio.eof? → true or false

Returns true if strio is at end of file. The stringio must be opened for reading or an IOError will be raised.

Source: show 

static VALUE
strio_eof(VALUE self)
{
    struct StringIO *ptr = readable(self);
    if (ptr->pos < RSTRING_LEN(ptr->string)) return Qfalse;
    return Qtrue;
}
strio.eof? → true or false

Returns true if strio is at end of file. The stringio must be opened for reading or an IOError will be raised.

Source: show 

static VALUE
strio_eof(VALUE self)
{
    struct StringIO *ptr = readable(self);
    if (ptr->pos < RSTRING_LEN(ptr->string)) return Qfalse;
    return Qtrue;
}
strio.external_encoding => encoding

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

Source: show 

static VALUE
strio_external_encoding(VALUE self)
{
    return rb_enc_from_encoding(rb_enc_get(StringIO(self)->string));
}
strio.fcntl

Source: show 

#define strio_fcntl strio_unimpl
strio.fileno → nil

Source: show 

#define strio_fileno strio_nil
strio.flush → strio

Source: show 

#define strio_flush strio_self
strio.fsync → 0

Source: show 

#define strio_fsync strio_0
strio.getbyte → fixnum or nil

See IO#getbyte.

Source: show 

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);
}
strio.getc → string or nil

See IO#getc.

Source: show 

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

    if (ptr->pos >= RSTRING_LEN(ptr->string)) {
        return Qnil;
    }
    p = RSTRING_PTR(ptr->string)+ptr->pos;
    len = rb_enc_mbclen(p, RSTRING_END(ptr->string), enc);
    ptr->pos += len;
    return rb_enc_str_new(p, len, rb_enc_get(ptr->string));
}
strio.gets(sep=$/) → string or nil strio.gets(limit) → string or nil strio.gets(sep, limit) → string or nil

See IO#gets.

Source: show 

static VALUE
strio_gets(int argc, VALUE *argv, VALUE self)
{
    VALUE str = strio_getline(argc, argv, readable(self));

    rb_lastline_set(str);
    return str;
}
strio.internal_encoding => encoding

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

Source: show 

static VALUE
strio_internal_encoding(VALUE self)
{
     return Qnil;
}
strio.isatty → nil

Source: show 

#define strio_isatty strio_false
strio.size → integer

Returns the size of the buffer string.

Source: show 

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));
}
strio.lineno → integer

Returns the current line number in strio. The stringio must be opened for reading. lineno counts the number of times gets is called, rather than the number of newlines encountered. The two values will differ if gets is called with a separator other than newline. See also the $. variable.

Source: show 

static VALUE
strio_get_lineno(VALUE self)
{
    return LONG2NUM(StringIO(self)->lineno);
}
strio.lineno = integer → integer

Manually sets the current line number to the given value. $. is updated only on the next read.

Source: show 

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

This is a deprecated alias for each_line.

Source: show 

static VALUE
strio_lines(int argc, VALUE *argv, VALUE self)
{
    rb_warn("StringIO#lines is deprecated; use #each_line instead");
    if (!rb_block_given_p())
        return rb_enumeratorize(self, ID2SYM(rb_intern("each_line")), argc, argv);
    return strio_each(argc, argv, self);
}
strio.pid → nil

Source: show 

#define strio_pid strio_nil
strio.pos → integer strio.tell → integer

Returns the current offset (in bytes) of strio.

Source: show 

static VALUE
strio_get_pos(VALUE self)
{
    return LONG2NUM(StringIO(self)->pos);
}
strio.pos = integer → integer

Seeks to the given position (in bytes) in strio.

Source: show 

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;
}
strio.putc(obj) → obj

See IO#putc.

Source: show 

static VALUE
strio_putc(VALUE self, VALUE ch)
{
    struct StringIO *ptr = writable(self);
    int c = NUM2CHR(ch);
    long olen;

    check_modifiable(ptr);
    olen = RSTRING_LEN(ptr->string);
    if (ptr->flags & FMODE_APPEND) {
        ptr->pos = olen;
    }
    strio_extend(ptr, ptr->pos, 1);
    RSTRING_PTR(ptr->string)[ptr->pos++] = c;
    OBJ_INFECT(ptr->string, self);
    return ch;
}
strio.read([length [, outbuf]]) → string, outbuf, or nil

See IO#read.

Source: show 

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);
        }
      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) {
            if (NIL_P(str)) {
                str = rb_str_new(0, 0);
            }
            else {
                rb_str_resize(str, 0);
            }
            return str;
        }
        else {
            len -= ptr->pos;
        }
        break;
      default:
        rb_raise(rb_eArgError, "wrong number of arguments (%d for 0)", argc);
    }
    if (NIL_P(str)) {
        str = strio_substr(ptr, ptr->pos, len);
        if (binary) rb_enc_associate(str, rb_ascii8bit_encoding());
    }
    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;
}
strio.readlines(sep=$/) → array strio.readlines(limit) → array strio.readlines(sep,limit) → array

See IO#readlines.

Source: show 

static VALUE
strio_readlines(int argc, VALUE *argv, VALUE self)
{
    VALUE ary, line;

    StringIO(self);
    ary = rb_ary_new();
    if (argc > 0 && !NIL_P(argv[argc-1]) && NIL_P(rb_check_string_type(argv[argc-1])) &&
        NUM2LONG(argv[argc-1]) == 0) {
        rb_raise(rb_eArgError, "invalid limit: 0 for readlines");
    }

    while (!NIL_P(line = strio_getline(argc, argv, readable(self)))) {
        rb_ary_push(ary, line);
    }
    return ary;
}
strio.reopen(other_StrIO) → strio strio.reopen(string, mode) → strio

Reinitializes strio with the given other_StrIO or string and mode (see StringIO#new).

Source: show 

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);
    }
    strio_init(argc, argv, StringIO(self), self);
    return self;
}
strio.rewind → 0

Positions strio to the beginning of input, resetting lineno to zero.

Source: show 

static VALUE
strio_rewind(VALUE self)
{
    struct StringIO *ptr = StringIO(self);
    ptr->pos = 0;
    ptr->lineno = 0;
    return INT2FIX(0);
}
strio.seek(amount, whence=SEEK_SET) → 0

Seeks to a given offset amount in the stream according to the value of whence (see IO#seek).

Source: show 

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

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

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.

Source: show 

static VALUE
strio_set_encoding(int argc, VALUE *argv, VALUE self)
{
    rb_encoding* enc;
    VALUE str = StringIO(self)->string;
    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_to_encoding(ext_enc);
    }
    rb_enc_associate(str, enc);
    return self;
}
strio.size → integer

Returns the size of the buffer string.

Source: show 

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));
}
strio.string → string

Returns underlying String object, the subject of IO.

Source: show 

static VALUE
strio_get_string(VALUE self)
{
    return StringIO(self)->string;
}
strio.string = string → string

Changes underlying String object, the subject of IO.

Source: show 

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;
    return ptr->string = string;
}
strio.sync → true

Returns true always.

Source: show 

static VALUE
strio_get_sync(VALUE self)
{
    StringIO(self);
    return Qtrue;
}
strio.sync = boolean → boolean

Source: show 

#define strio_set_sync strio_first
strio.pos → integer strio.tell → integer

Returns the current offset (in bytes) of strio.

Source: show 

static VALUE
strio_get_pos(VALUE self)
{
    return LONG2NUM(StringIO(self)->pos);
}
strio.truncate(integer) → 0

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

Source: show 

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 len;
}
strio.tty? → nil

Source: show 

#define strio_isatty strio_false
strio.ungetbyte(fixnum) → nil

See IO#ungetbyte

Source: show 

static VALUE
strio_ungetbyte(VALUE self, VALUE c)
{
    struct StringIO *ptr = readable(self);
    char buf[1], *cp = buf;
    long pos = ptr->pos, cl = 1;
    VALUE str = ptr->string;

    if (NIL_P(c)) return Qnil;
    if (FIXNUM_P(c)) {
        buf[0] = (char)FIX2INT(c);
    }
    else {
        SafeStringValue(c);
        cp = RSTRING_PTR(c);
        cl = RSTRING_LEN(c);
        if (cl == 0) return Qnil;
    }
    check_modifiable(ptr);
    rb_str_modify(str);
    if (cl > pos) {
        char *s;
        long rest = RSTRING_LEN(str) - pos;
        rb_str_resize(str, rest + cl);
        s = RSTRING_PTR(str);
        memmove(s + cl, s + pos, rest);
        pos = 0;
    }
    else {
        pos -= cl;
    }
    memcpy(RSTRING_PTR(str) + pos, cp, cl);
    ptr->pos = pos;
    RB_GC_GUARD(c);
    return Qnil;
}
strio.ungetc(string) → nil

Pushes back one character (passed as a parameter) onto strio such that a subsequent buffered read will return it. There is no limitation for multiple pushbacks including pushing back behind the beginning of the buffer string.

Source: show 

static VALUE
strio_ungetc(VALUE self, VALUE c)
{
    struct StringIO *ptr = readable(self);
    long lpos, clen;
    char *p, *pend;
    rb_encoding *enc, *enc2;

    if (NIL_P(c)) return Qnil;
    check_modifiable(ptr);
    if (FIXNUM_P(c)) {
        int cc = FIX2INT(c);
        char buf[16];

        enc = rb_enc_get(ptr->string);
        rb_enc_mbcput(cc, buf, enc);
        c = rb_enc_str_new(buf, rb_enc_codelen(cc, enc), enc);
    }
    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);
        }
    }
    if (RSTRING_LEN(ptr->string) < ptr->pos) {
        long len = RSTRING_LEN(ptr->string);
        rb_str_resize(ptr->string, ptr->pos - 1);
        memset(RSTRING_PTR(ptr->string) + len, 0, ptr->pos - len - 1);
        rb_str_concat(ptr->string, c);
        ptr->pos--;
    }
    else {
        /* get logical position */
        lpos = 0; p = RSTRING_PTR(ptr->string); pend = p + ptr->pos;
        for (;;) {
            clen = rb_enc_mbclen(p, pend, enc);
            if (p+clen >= pend) break;
            p += clen;
            lpos++;
        }
        clen = p - RSTRING_PTR(ptr->string);
        rb_str_update(ptr->string, lpos, ptr->pos ? 1 : 0, c);
        ptr->pos = clen;
    }

    return Qnil;
}
strio.write(string) → integer strio.syswrite(string) → integer

Appends the given string to the underlying buffer string of strio. 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.

Source: show 

static VALUE
strio_write(VALUE self, VALUE str)
{
    struct StringIO *ptr = writable(self);
    long len, olen;
    rb_encoding *enc, *enc2;

    RB_GC_GUARD(str);
    if (!RB_TYPE_P(str, T_STRING))
        str = rb_obj_as_string(str);
    enc = rb_enc_get(ptr->string);
    enc2 = rb_enc_get(str);
    if (enc != enc2 && enc != rb_ascii8bit_encoding()) {
        str = rb_str_conv_enc(str, enc2, enc);
    }
    len = RSTRING_LEN(str);
    if (len == 0) return INT2FIX(0);
    check_modifiable(ptr);
    olen = RSTRING_LEN(ptr->string);
    if (ptr->flags & FMODE_APPEND) {
        ptr->pos = olen;
    }
    if (ptr->pos == olen) {
        rb_str_cat(ptr->string, RSTRING_PTR(str), len);
    }
    else {
        strio_extend(ptr, ptr->pos, len);
        memmove(RSTRING_PTR(ptr->string)+ptr->pos, RSTRING_PTR(str), len);
        OBJ_INFECT(ptr->string, str);
    }
    OBJ_INFECT(ptr->string, self);
    ptr->pos += len;
    return LONG2NUM(len);
}