In Files

  • stringio/stringio.c

Class/Module Index [+]

Quicksearch

StringIO

Pseudo I/O on String object.

Public Class Methods

new(string=""[, mode]) click to toggle source

Creates new StringIO instance from with string and mode.

 
               static VALUE
strio_initialize(argc, argv, self)
    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);
    return self;
}
            
open(string=""[, mode]) {|strio| ...} click to toggle source

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.

 
               static VALUE
strio_s_open(argc, argv, klass)
    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);
}
            

Public Instance Methods

strio << obj → strio click to toggle source

See IO#<<.

 
               #define strio_addstr rb_io_addstr
            
binmode → true click to toggle source
 
               #define strio_binmode strio_self
            
close → nil click to toggle source

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

 
               static VALUE
strio_close(self)
    VALUE self;
{
    struct StringIO *ptr = StringIO(self);
    if (CLOSED(ptr)) {
        rb_raise(rb_eIOError, "closed stream");
    }
    ptr->flags &= ~FMODE_READWRITE;
    return Qnil;
}
            
close_read → nil click to toggle source

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

 
               static VALUE
strio_close_read(self)
    VALUE self;
{
    struct StringIO *ptr = StringIO(self);
    if (!READABLE(ptr)) {
        rb_raise(rb_eIOError, "closing non-duplex IO for reading");
    }
    ptr->flags &= ~FMODE_READABLE;
    return Qnil;
}
            
close_write → nil click to toggle source

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

 
               static VALUE
strio_close_write(self)
    VALUE self;
{
    struct StringIO *ptr = StringIO(self);
    if (!WRITABLE(ptr)) {
        rb_raise(rb_eIOError, "closing non-duplex IO for writing");
    }
    ptr->flags &= ~FMODE_WRITABLE;
    return Qnil;
}
            
closed? → true or false click to toggle source

Returns true if strio is completely closed, false otherwise.

 
               static VALUE
strio_closed(self)
    VALUE self;
{
    struct StringIO *ptr = StringIO(self);
    if (!CLOSED(ptr)) return Qfalse;
    return Qtrue;
}
            
closed_read? → true or false click to toggle source

Returns true if strio is not readable, false otherwise.

 
               static VALUE
strio_closed_read(self)
    VALUE self;
{
    struct StringIO *ptr = StringIO(self);
    if (READABLE(ptr)) return Qfalse;
    return Qtrue;
}
            
closed_write? → true or false click to toggle source

Returns true if strio is not writable, false otherwise.

 
               static VALUE
strio_closed_write(self)
    VALUE self;
{
    struct StringIO *ptr = StringIO(self);
    if (WRITABLE(ptr)) return Qfalse;
    return Qtrue;
}
            
each(sep_string=$/) {|line| block } → strio click to toggle source
each_line(sep_string=$/) {|line| block } → strio

See IO#each.

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

    while (!NIL_P(line = strio_getline(argc, argv, readable(ptr)))) {
        rb_yield(line);
    }
    return self;
}
            
each_byte {|byte| block } → strio click to toggle source

See IO#each_byte.

 
               static VALUE
strio_each_byte(self)
    VALUE self;
{
    struct StringIO *ptr = readable(StringIO(self));
    while (ptr->pos < RSTRING(ptr->string)->len) {
        char c = RSTRING(ptr->string)->ptr[ptr->pos++];
        rb_yield(CHR2FIX(c));
    }
    return Qnil;
}
            
each_line(sep_string=$/) {|line| block } → strio click to toggle source

See IO#each.

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

    while (!NIL_P(line = strio_getline(argc, argv, readable(ptr)))) {
        rb_yield(line);
    }
    return self;
}
            
eof → true or false click to toggle source
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.

 
               static VALUE
strio_eof(self)
    VALUE self;
{
    struct StringIO *ptr = readable(StringIO(self));
    if (ptr->pos < RSTRING(ptr->string)->len) return Qfalse;
    return Qtrue;
}
            
eof? → true or false click to toggle source

Returns true if strio is at end of file. The stringio must be

opened for reading or an IOError will be raised.

 
               static VALUE
strio_eof(self)
    VALUE self;
{
    struct StringIO *ptr = readable(StringIO(self));
    if (ptr->pos < RSTRING(ptr->string)->len) return Qfalse;
    return Qtrue;
}
            
fcntl click to toggle source
 
               #define strio_fcntl strio_unimpl
            
fileno → nil click to toggle source
 
               #define strio_fileno strio_nil
            
flush → strio click to toggle source
 
               #define strio_flush strio_self
            
fsync → 0 click to toggle source
 
               #define strio_fsync strio_0
            
getc → fixnum or nil click to toggle source

See IO#getc.

 
               static VALUE
strio_getc(self)
    VALUE self;
{
    struct StringIO *ptr = readable(StringIO(self));
    int c;
    if (ptr->pos >= RSTRING(ptr->string)->len) {
        ptr->flags |= STRIO_EOF;
        return Qnil;
    }
    c = RSTRING(ptr->string)->ptr[ptr->pos++];
    return CHR2FIX(c);
}
            
gets(sep_string=$/) → string or nil click to toggle source

See IO#gets.

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

    rb_lastline_set(str);
    return str;
}
            
isatty → nil click to toggle source
 
               #define strio_isatty strio_false
            
size → integer click to toggle source

Returns the size of the buffer string.

 
               static VALUE
strio_size(self)
    VALUE self;
{
    VALUE string = StringIO(self)->string;
    if (NIL_P(string)) {
        rb_raise(rb_eIOError, "not opened");
    }
    return ULONG2NUM(RSTRING(string)->len);
}
            
lineno → integer click to toggle source

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.

 
               static VALUE
strio_get_lineno(self)
    VALUE self;
{
    return LONG2NUM(StringIO(self)->lineno);
}
            
lineno = integer → integer click to toggle source

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

 
               static VALUE
strio_set_lineno(self, lineno)
    VALUE self, lineno;
{
    StringIO(self)->lineno = NUM2LONG(lineno);
    return lineno;
}
            
path → nil click to toggle source
 
               #define strio_path strio_nil
            
pid → nil click to toggle source
 
               #define strio_pid strio_nil
            
pos → integer click to toggle source
tell → integer

Returns the current offset (in bytes) of strio.

 
               static VALUE
strio_get_pos(self)
    VALUE self;
{
    return LONG2NUM(StringIO(self)->pos);
}
            
pos = integer → integer click to toggle source

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

 
               static VALUE
strio_set_pos(self, pos)
    VALUE self;
    VALUE pos;
{
    struct StringIO *ptr = StringIO(self);
    long p = NUM2LONG(pos);
    if (p < 0) {
        error_inval(0);
    }
    ptr->pos = p;
    ptr->flags &= ~STRIO_EOF;
    return pos;
}
            
printf(format_string [, obj, ...] ) → nil click to toggle source

See IO#printf.

 
               #define strio_printf rb_io_printf
            
putc(obj) → obj click to toggle source

See IO#putc.

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

    check_modifiable(ptr);
    olen = RSTRING(ptr->string)->len;
    if (ptr->flags & FMODE_APPEND) {
        ptr->pos = olen;
    }
    strio_extend(ptr, ptr->pos, 1);
    RSTRING(ptr->string)->ptr[ptr->pos++] = c;
    OBJ_INFECT(ptr->string, self);
    return ch;
}
            
puts(obj, ...) → nil click to toggle source

See IO#puts.

 
               #define strio_puts rb_io_puts
            
read([length [, buffer]]) → string, buffer, or nil click to toggle source

See IO#read.

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

    switch (argc) {
      case 2:
        str = argv[1];
        StringValue(str);
        rb_str_modify(str);
      case 1:
        if (!NIL_P(argv[0])) {
            len = olen = NUM2LONG(argv[0]);
            if (len < 0) {
                rb_raise(rb_eArgError, "negative length %ld given", len);
            }
            if (len > 0 && ptr->pos >= RSTRING(ptr->string)->len) {
                ptr->flags |= STRIO_EOF;
                if (!NIL_P(str)) rb_str_resize(str, 0);
                return Qnil;
            }
            else if (ptr->flags & STRIO_EOF) {
                if (!NIL_P(str)) rb_str_resize(str, 0);
                return Qnil;
            }
            break;
        }
        /* fall through */
      case 0:
        olen = -1;
        len = RSTRING(ptr->string)->len;
        if (len <= ptr->pos) {
            ptr->flags |= STRIO_EOF;
            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 = rb_str_substr(ptr->string, ptr->pos, len);
    }
    else {
        long rest = RSTRING(ptr->string)->len - ptr->pos;
        if (len > rest) len = rest;
        rb_str_resize(str, len);
        MEMCPY(RSTRING(str)->ptr, RSTRING(ptr->string)->ptr + ptr->pos, char, len);
    }
    if (NIL_P(str)) {
        if (!(ptr->flags & STRIO_EOF)) str = rb_str_new(0, 0);
        len = 0;
    }
    else {
        ptr->pos += len = RSTRING(str)->len;
    }
    if (olen < 0 || olen > len) ptr->flags |= STRIO_EOF;
    return str;
}
            
readchar → fixnum click to toggle source

See IO#readchar.

 
               static VALUE
strio_readchar(self)
    VALUE self;
{
    VALUE c = strio_getc(self);
    if (NIL_P(c)) rb_eof_error();
    return c;
}
            
readline(sep_string=$/) → string click to toggle source

See IO#readline.

 
               static VALUE
strio_readline(argc, argv, self)
    int argc;
    VALUE *argv;
    VALUE self;
{
    VALUE line = strio_gets(argc, argv, self);
    if (NIL_P(line)) rb_eof_error();
    return line;
}
            
readlines(sep_string=$/) → array click to toggle source

See IO#readlines.

 
               static VALUE
strio_readlines(argc, argv, self)
    int argc;
    VALUE *argv;
    VALUE self;
{
    struct StringIO *ptr = StringIO(self);
    VALUE ary = rb_ary_new(), line;
    while (!NIL_P(line = strio_getline(argc, argv, readable(ptr)))) {
        rb_ary_push(ary, line);
    }
    return ary;
}
            
reopen(other_StrIO) → strio click to toggle source
reopen(string, mode) → strio

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

 
               static VALUE
strio_reopen(argc, argv, self)
    int argc;
    VALUE *argv;
    VALUE self;
{
    if (!OBJ_TAINTED(self)) rb_secure(4);
    if (argc == 1 && TYPE(*argv) != T_STRING) {
        return strio_copy(self, *argv);
    }
    strio_init(argc, argv, StringIO(self));
    return self;
}
            
rewind → 0 click to toggle source

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

 
               static VALUE
strio_rewind(self)
    VALUE self;
{
    struct StringIO *ptr = StringIO(self);
    ptr->pos = 0;
    ptr->lineno = 0;
    ptr->flags &= ~STRIO_EOF;
    return INT2FIX(0);
}
            
seek(amount, whence=SEEK_SET) → 0 click to toggle source

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

 
               static VALUE
strio_seek(argc, argv, self)
    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]);
    switch (NIL_P(whence) ? 0 : NUM2LONG(whence)) {
      case 0:
        break;
      case 1:
        offset += ptr->pos;
        break;
      case 2:
        offset += RSTRING(ptr->string)->len;
        break;
      default:
        rb_raise(rb_eArgError, "invalid whence %ld", NUM2LONG(whence));
    }
    if (offset < 0) {
        error_inval(0);
    }
    ptr->pos = offset;
    ptr->flags &= ~STRIO_EOF;
    return INT2FIX(0);
}
            
size → integer click to toggle source

Returns the size of the buffer string.

 
               static VALUE
strio_size(self)
    VALUE self;
{
    VALUE string = StringIO(self)->string;
    if (NIL_P(string)) {
        rb_raise(rb_eIOError, "not opened");
    }
    return ULONG2NUM(RSTRING(string)->len);
}
            
string → string click to toggle source

Returns underlying String object, the subject of IO.

 
               static VALUE
strio_get_string(self)
    VALUE self;
{
    return StringIO(self)->string;
}
            
string = string → string click to toggle source

Changes underlying String object, the subject of IO.

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

    if (!OBJ_TAINTED(self)) rb_secure(4);
    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;
}
            
sync → true click to toggle source

Returns true always.

 
               static VALUE
strio_get_sync(self)
    VALUE self;
{
    StringIO(self);
    return Qtrue;
}
            
sync = boolean → boolean click to toggle source
 
               #define strio_set_sync strio_first
            
sysread(integer[, outbuf]) → string click to toggle source

Similar to read, but raises EOFError at end of string instead of returning nil, as well as IO#sysread does.

 
               static VALUE
strio_sysread(argc, argv, self)
    int argc;
    VALUE *argv;
    VALUE self;
{
    VALUE val = strio_read(argc, argv, self);
    if (NIL_P(val) || RSTRING(val)->len == 0) {
        rb_eof_error();
    }
    return val;
}
            
write(string) → integer click to toggle source
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.

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

    if (TYPE(str) != T_STRING)
        str = rb_obj_as_string(str);
    len = RSTRING(str)->len;
    if (!len) return INT2FIX(0);
    check_modifiable(ptr);
    olen = RSTRING(ptr->string)->len;
    if (ptr->flags & FMODE_APPEND) {
        ptr->pos = olen;
    }
    if (ptr->pos == olen) {
        rb_str_cat(ptr->string, RSTRING(str)->ptr, len);
    }
    else {
        strio_extend(ptr, ptr->pos, len);
        rb_str_update(ptr->string, ptr->pos, len, str);
    }
    OBJ_INFECT(ptr->string, self);
    ptr->pos += len;
    return LONG2NUM(len);
}
            
pos → integer click to toggle source
tell → integer

Returns the current offset (in bytes) of strio.

 
               static VALUE
strio_get_pos(self)
    VALUE self;
{
    return LONG2NUM(StringIO(self)->pos);
}
            
truncate(integer) → 0 click to toggle source

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

 
               static VALUE
strio_truncate(self, len)
    VALUE self, len;
{
    VALUE string = writable(StringIO(self))->string;
    long l = NUM2LONG(len);
    long plen = RSTRING(string)->len;
    if (l < 0) {
        error_inval("negative legnth");
    }
    rb_str_resize(string, l);
    if (plen < l) {
        MEMZERO(RSTRING(string)->ptr + plen, char, l - plen);
    }
    return len;
}
            
tty? → nil click to toggle source
 
               #define strio_isatty strio_false
            
ungetc(integer) → nil click to toggle source

Pushes back one character (passed as a parameter) onto strio such that a subsequent buffered read will return it. Pushing back behind the beginning of the buffer string is not possible. Nothing will be done if such an attempt is made. In other case, there is no limitation for multiple pushbacks.

 
               static VALUE
strio_ungetc(self, ch)
    VALUE self, ch;
{
    struct StringIO *ptr = readable(StringIO(self));
    int cc = NUM2INT(ch);
    long len, pos = ptr->pos;

    if (cc != EOF) {
        len = RSTRING(ptr->string)->len;
        if (pos == 0) {
            char *p;
            rb_str_resize(ptr->string, len + 1);
            p = RSTRING(ptr->string)->ptr;
            memmove(p + 1, p, len);
        }
        else {
            if (len < pos-- ||
                (unsigned char)RSTRING(ptr->string)->ptr[pos] !=
                (unsigned char)cc) {
                strio_extend(ptr, pos, 1);
            }
            --ptr->pos;
        }
        RSTRING(ptr->string)->ptr[pos] = cc;
        OBJ_INFECT(ptr->string, self);
        ptr->flags &= ~STRIO_EOF;
    }
    return Qnil;
}
            
write(string) → integer click to toggle source
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.

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

    if (TYPE(str) != T_STRING)
        str = rb_obj_as_string(str);
    len = RSTRING(str)->len;
    if (!len) return INT2FIX(0);
    check_modifiable(ptr);
    olen = RSTRING(ptr->string)->len;
    if (ptr->flags & FMODE_APPEND) {
        ptr->pos = olen;
    }
    if (ptr->pos == olen) {
        rb_str_cat(ptr->string, RSTRING(str)->ptr, len);
    }
    else {
        strio_extend(ptr, ptr->pos, len);
        rb_str_update(ptr->string, ptr->pos, len, str);
    }
    OBJ_INFECT(ptr->string, self);
    ptr->pos += len;
    return LONG2NUM(len);
}
            

Commenting is here to help enhance the documentation. For example, code samples, or clarification of the documentation.

If you have questions about Ruby or the documentation, please post to one of the Ruby mailing lists. You will get better, faster, help that way.

If you wish to post a correction of the docs, please do so, but also file bug report so that it can be corrected for the next release. Thank you.

If you want to help improve the Ruby documentation, please visit Documenting-ruby.org.

blog comments powered by Disqus