Class: StringIO

Inherits:
Data
  • Object
show all
Includes:
Enumerable, Readable, Writable
Defined in:
stringio.c

Constant Summary collapse

VERSION =
rb_str_new_cstr(STRINGIO_VERSION)

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#new(string = ""[, mode]) ⇒ Object

Creates new StringIO instance from with string and mode.


258
259
260
261
262
263
264
265
266
267
268
# File 'stringio.c', line 258

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

Class Method Details

.new(*args) ⇒ Object

:nodoc:


399
400
401
402
403
404
405
406
407
408
409
# File 'stringio.c', line 399

static VALUE
strio_s_new(int argc, VALUE *argv, VALUE klass)
{
    if (rb_block_given_p()) {
	VALUE cname = rb_obj_as_string(klass);

	rb_warn("%"PRIsVALUE"::new() does not take block; use %"PRIsVALUE"::open() instead",
		cname, cname);
    }
    return rb_class_new_instance_kw(argc, argv, klass, RB_PASS_CALLED_KEYWORDS);
}

.open(string = ""[, mode]) {|strio| ... } ⇒ Object

Equivalent to StringIO.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.

Yields:

  • (strio)

390
391
392
393
394
395
396
# File 'stringio.c', line 390

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

Instance Method Details

#binmodeObject

Puts stream into binary mode. See IO#binmode.


669
670
671
672
673
674
675
676
677
678
679
680
# File 'stringio.c', line 669

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

#bytesObject

This is a deprecated alias for #each_byte.


833
834
835
836
837
838
839
840
# File 'stringio.c', line 833

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

#charsObject

This is a deprecated alias for #each_char.


1058
1059
1060
1061
1062
1063
1064
1065
# File 'stringio.c', line 1058

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

#closenil

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

Returns:

  • (nil)

511
512
513
514
515
516
517
# File 'stringio.c', line 511

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

#close_readnil

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

Returns:

  • (nil)

526
527
528
529
530
531
532
533
534
535
# File 'stringio.c', line 526

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_writenil

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

Returns:

  • (nil)

544
545
546
547
548
549
550
551
552
553
# File 'stringio.c', line 544

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?Boolean

Returns true if the stream is completely closed, false otherwise.

Returns:

  • (Boolean)

561
562
563
564
565
566
567
# File 'stringio.c', line 561

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

#closed_read?Boolean

Returns true if the stream is not readable, false otherwise.

Returns:

  • (Boolean)

575
576
577
578
579
580
581
# File 'stringio.c', line 575

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

#closed_write?Boolean

Returns true if the stream is not writable, false otherwise.

Returns:

  • (Boolean)

589
590
591
592
593
594
595
# File 'stringio.c', line 589

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

#codepointsObject

This is a deprecated alias for #each_codepoint.


1102
1103
1104
1105
1106
1107
1108
1109
# File 'stringio.c', line 1102

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

#each(sep = $/, chomp: false) {|line| ... } ⇒ Object #each(limit, chomp: false) {|line| ... } ⇒ Object #each(sep, limit, chomp: false) {|line| ... } ⇒ Object #each(...) ⇒ Enumerator

strio.each_line(sep=$/, chomp: false) {|line| block } -> strio

strio.each_line(limit, chomp: false) {|line| block }      -> strio
strio.each_line(sep, limit, chomp: false) {|line| block } -> strio
strio.each_line(...)                                      -> anEnumerator

See IO#each.

Overloads:

  • #each(sep = $/, chomp: false) {|line| ... } ⇒ Object

    Yields:

    • (line)
  • #each(limit, chomp: false) {|line| ... } ⇒ Object

    Yields:

    • (line)
  • #each(sep, limit, chomp: false) {|line| ... } ⇒ Object

    Yields:

    • (line)
  • #each(...) ⇒ Enumerator

    Returns:

    • (Enumerator)

1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
# File 'stringio.c', line 1342

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

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

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

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

#each_byte {|byte| ... } ⇒ Object #each_byteEnumerator

See IO#each_byte.

Overloads:

  • #each_byte {|byte| ... } ⇒ Object

    Yields:

    • (byte)
  • #each_byteEnumerator

    Returns:

    • (Enumerator)

816
817
818
819
820
821
822
823
824
825
826
827
828
# File 'stringio.c', line 816

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

#each_char {|char| ... } ⇒ Object #each_charEnumerator

See IO#each_char.

Overloads:

  • #each_char {|char| ... } ⇒ Object

    Yields:

    • (char)
  • #each_charEnumerator

    Returns:

    • (Enumerator)

1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
# File 'stringio.c', line 1042

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 {|c| ... } ⇒ Object #each_codepointEnumerator

See IO#each_codepoint.

Overloads:

  • #each_codepoint {|c| ... } ⇒ Object

    Yields:

    • (c)
  • #each_codepointEnumerator

    Returns:

    • (Enumerator)

1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
# File 'stringio.c', line 1074

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

#each(sep = $/, chomp: false) {|line| ... } ⇒ Object #each(limit, chomp: false) {|line| ... } ⇒ Object #each(sep, limit, chomp: false) {|line| ... } ⇒ Object #each(...) ⇒ Enumerator

strio.each_line(sep=$/, chomp: false) {|line| block } -> strio

strio.each_line(limit, chomp: false) {|line| block }      -> strio
strio.each_line(sep, limit, chomp: false) {|line| block } -> strio
strio.each_line(...)                                      -> anEnumerator

See IO#each.

Overloads:

  • #each(sep = $/, chomp: false) {|line| ... } ⇒ Object

    Yields:

    • (line)
  • #each(limit, chomp: false) {|line| ... } ⇒ Object

    Yields:

    • (line)
  • #each(sep, limit, chomp: false) {|line| ... } ⇒ Object

    Yields:

    • (line)
  • #each(...) ⇒ Enumerator

    Returns:

    • (Enumerator)

1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
# File 'stringio.c', line 1342

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

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

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

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

#eofBoolean #eof?Boolean

Returns true if the stream is at the end of the data (underlying string). The stream must be opened for reading or an IOError will be raised.

Overloads:

  • #eofBoolean

    Returns:

    • (Boolean)
  • #eof?Boolean

    Returns:

    • (Boolean)

605
606
607
608
609
610
611
# File 'stringio.c', line 605

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

#eofBoolean #eof?Boolean

Returns true if the stream is at the end of the data (underlying string). The stream must be opened for reading or an IOError will be raised.

Overloads:

  • #eofBoolean

    Returns:

    • (Boolean)
  • #eof?Boolean

    Returns:

    • (Boolean)

605
606
607
608
609
610
611
# File 'stringio.c', line 605

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

#external_encodingEncoding

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

Returns:

  • (Encoding)

1703
1704
1705
1706
1707
1708
# File 'stringio.c', line 1703

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

#fcntlObject

#filenonil

Returns:

  • (nil)

#flushObject

#fsync0

Returns:

  • (0)

#getbyteFixnum?

See IO#getbyte.

Returns:

  • (Fixnum, nil)

873
874
875
876
877
878
879
880
881
882
883
# File 'stringio.c', line 873

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

#getcString?

See IO#getc.

Returns:

  • (String, nil)

848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
# File 'stringio.c', line 848

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? #gets(limit, chomp: false) ⇒ String? #gets(sep, limit, chomp: false) ⇒ String?

See IO#gets.

Overloads:

  • #gets(sep = $/, chomp: false) ⇒ String?

    Returns:

    • (String, nil)
  • #gets(limit, chomp: false) ⇒ String?

    Returns:

    • (String, nil)
  • #gets(sep, limit, chomp: false) ⇒ String?

    Returns:

    • (String, nil)

1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
# File 'stringio.c', line 1296

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

    if (prepare_getline_args(&arg, argc, argv)->limit == 0) {
	struct StringIO *ptr = readable(self);
	return rb_enc_str_new(0, 0, get_enc(ptr));
    }

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

#initialize_copy(orig) ⇒ Object

:nodoc:


614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
# File 'stringio.c', line 614

static VALUE
strio_copy(VALUE copy, VALUE orig)
{
    struct StringIO *ptr;

    orig = rb_convert_type(orig, T_DATA, "StringIO", "to_strio");
    if (copy == orig) return copy;
    ptr = StringIO(orig);
    if (check_strio(copy)) {
	strio_free(DATA_PTR(copy));
    }
    DATA_PTR(copy) = ptr;
    RBASIC(copy)->flags &= ~STRIO_READWRITE;
    RBASIC(copy)->flags |= RBASIC(orig)->flags & STRIO_READWRITE;
    ++ptr->count;
    return copy;
}

#internal_encodingEncoding

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

Returns:

  • (Encoding)

1718
1719
1720
1721
1722
# File 'stringio.c', line 1718

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

#isattynil #tty?nil

Overloads:

  • #isattynil

    Returns:

    • (nil)
  • #tty?nil

    Returns:

    • (nil)

#lengthInteger #sizeInteger

Returns the size of the buffer string.

Overloads:

  • #lengthInteger

    Returns:

    • (Integer)
  • #sizeInteger

    Returns:

    • (Integer)

1661
1662
1663
1664
1665
1666
1667
1668
1669
# File 'stringio.c', line 1661

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

#linenoInteger

Returns the current line number. The stream 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.

Returns:

  • (Integer)

642
643
644
645
646
# File 'stringio.c', line 642

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

#lineno=(integer) ⇒ Integer

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

Returns:

  • (Integer)

655
656
657
658
659
660
# File 'stringio.c', line 655

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

#lines(*args) ⇒ Object

This is a deprecated alias for #each_line.


1364
1365
1366
1367
1368
1369
1370
1371
# File 'stringio.c', line 1364

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

#pidnil

Returns:

  • (nil)

#posInteger #tellInteger

Returns the current offset (in bytes).

Overloads:

  • #posInteger

    Returns:

    • (Integer)
  • #tellInteger

    Returns:

    • (Integer)

713
714
715
716
717
# File 'stringio.c', line 713

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

#pos=(integer) ⇒ Integer

Seeks to the given position (in bytes).

Returns:

  • (Integer)

725
726
727
728
729
730
731
732
733
734
735
# File 'stringio.c', line 725

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

#putc(obj) ⇒ Object

See IO#putc.

Returns:

  • (Object)

1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
# File 'stringio.c', line 1490

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?

See IO#read.

Returns:

  • (String, nil)

1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
# File 'stringio.c', line 1522

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

    rb_check_arity(argc, 0, 2);
    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;
    }
    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 #readlines(limit, chomp: false) ⇒ Array #readlines(sep, limit, chomp: false) ⇒ Array

See IO#readlines.

Overloads:

  • #readlines(sep = $/, chomp: false) ⇒ Array

    Returns:

    • (Array)
  • #readlines(limit, chomp: false) ⇒ Array

    Returns:

    • (Array)
  • #readlines(sep, limit, chomp: false) ⇒ Array

    Returns:

    • (Array)

1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
# File 'stringio.c', line 1381

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

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

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

#reopen(other_StrIO) ⇒ Object #reopen(string, mode) ⇒ Object

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


696
697
698
699
700
701
702
703
704
# File 'stringio.c', line 696

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

#rewind0

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

Returns:

  • (0)

744
745
746
747
748
749
750
751
# File 'stringio.c', line 744

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

#seek(amount, whence = SEEK_SET) ⇒ 0

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

Returns:

  • (0)

760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
# File 'stringio.c', line 760

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]]) ⇒ Object

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.


1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
# File 'stringio.c', line 1734

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

    return self;
}

#set_encoding_by_bomObject


1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
# File 'stringio.c', line 1757

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

    if (ptr->enc) {
	rb_raise(rb_eArgError, "encoding conversion is set");
    }
    if (!set_encoding_by_bom(ptr)) return Qnil;
    return rb_enc_from_encoding(ptr->enc);
}

#lengthInteger #sizeInteger

Returns the size of the buffer string.

Overloads:

  • #lengthInteger

    Returns:

    • (Integer)
  • #sizeInteger

    Returns:

    • (Integer)

1661
1662
1663
1664
1665
1666
1667
1668
1669
# File 'stringio.c', line 1661

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

#stringString

Returns underlying String object, the subject of IO.

Returns:

  • (String)

478
479
480
481
482
# File 'stringio.c', line 478

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

#string=(string) ⇒ String

Changes underlying String object, the subject of IO.

Returns:

  • (String)

490
491
492
493
494
495
496
497
498
499
500
501
502
# File 'stringio.c', line 490

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

#synctrue

Returns true always.

Returns:

  • (true)

798
799
800
801
802
803
# File 'stringio.c', line 798

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

#sync=(boolean) ⇒ Boolean

Returns:

  • (Boolean)

#tellObject

#truncate(integer) ⇒ 0

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

Returns:

  • (0)

1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
# File 'stringio.c', line 1678

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

#tty?Boolean

Returns:

  • (Boolean)

#ungetbyte(fixnum) ⇒ nil

See IO#ungetbyte

Returns:

  • (nil)

951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
# File 'stringio.c', line 951

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(string) ⇒ nil

Pushes back one character (passed as a parameter) 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.

Returns:

  • (nil)

914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
# File 'stringio.c', line 914

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

Overloads:

  • #write(string, ...) ⇒ Integer

    Returns:

    • (Integer)
  • #syswrite(string) ⇒ Integer

    Returns:

    • (Integer)

1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
# File 'stringio.c', line 1409

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