Class: StringIO

Inherits:
Object
  • Object
show all
Includes:
Enumerable, Readable, Writable
Defined in:
ext/stringio/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 = 'r+') ⇒ Object

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



275
276
277
278
279
280
281
282
283
284
285
 
# File 'ext/stringio/stringio.c', line 275

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:



436
437
438
439
440
441
442
443
444
445
446
 
# File 'ext/stringio/stringio.c', line 436

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 = 'r+') {|strio| ... } ⇒ Object

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.

Yields:

  • (strio) 


427
428
429
430
431
432
433
 
# File 'ext/stringio/stringio.c', line 427

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

#binmode ⇒ self

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

Returns:

  • (self) 


752
753
754
755
756
757
758
759
760
761
762
763
 
# File 'ext/stringio/stringio.c', line 752

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

Closes self for both reading and writing.

Raises IOError if reading or writing is attempted.

Related: StringIO#close_read, StringIO#close_write.

Returns:

  • (nil) 


579
580
581
582
583
584
585
 
# File 'ext/stringio/stringio.c', line 579

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

#close_read ⇒ nil

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

Raises IOError if reading is attempted.

Related: StringIO#close, StringIO#close_write.

Returns:

  • (nil) 


597
598
599
600
601
602
603
604
605
606
 
# File 'ext/stringio/stringio.c', line 597

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

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

Raises IOError if writing is attempted.

Related: StringIO#close, StringIO#close_read.

Returns:

  • (nil) 


618
619
620
621
622
623
624
625
626
627
 
# File 'ext/stringio/stringio.c', line 618

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 self is closed for both reading and writing, false otherwise.

Returns:

  • (Boolean) 


636
637
638
639
640
641
642
 
# File 'ext/stringio/stringio.c', line 636

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

#closed_read? ⇒ Boolean

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

Returns:

  • (Boolean) 


650
651
652
653
654
655
656
 
# File 'ext/stringio/stringio.c', line 650

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

#closed_write? ⇒ Boolean

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

Returns:

  • (Boolean) 


664
665
666
667
668
669
670
 
# File 'ext/stringio/stringio.c', line 664

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

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

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

StringIO#each is an alias for StringIO#each_line.

Overloads:

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

    Yields:

    • (line)

    Returns:

    • (self)
  • #each_line(limit, chomp: false) {|line| ... } ⇒ self

    Yields:

    • (line)

    Returns:

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

    Yields:

    • (line)

    Returns:

    • (self) 


1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
 
# File 'ext/stringio/stringio.c', line 1425

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| ... } ⇒ self

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

With no block given, returns an enumerator.

Yields:

  • (byte)

Returns:

  • (self) 


922
923
924
925
926
927
928
929
930
931
932
933
934
 
# File 'ext/stringio/stringio.c', line 922

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

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

With no block given, returns an enumerator.

Yields:

  • (c)

Returns:

  • (self) 


1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
 
# File 'ext/stringio/stringio.c', line 1141

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

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

With no block given, returns an enumerator.

Yields:

  • (codepoint)

Returns:

  • (self) 


1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
 
# File 'ext/stringio/stringio.c', line 1163

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(sep = $/, chomp: false) {|line| ... } ⇒ self #each_line(limit, chomp: false) {|line| ... } ⇒ self #each_line(sep, limit, chomp: false) {|line| ... } ⇒ self

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

StringIO#each is an alias for StringIO#each_line.

Overloads:

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

    Yields:

    • (line)

    Returns:

    • (self)
  • #each_line(limit, chomp: false) {|line| ... } ⇒ self

    Yields:

    • (line)

    Returns:

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

    Yields:

    • (line)

    Returns:

    • (self) 


1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
 
# File 'ext/stringio/stringio.c', line 1425

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

#eof? ⇒ Boolean

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

Raises IOError if the stream is not opened for reading.

StreamIO#eof is an alias for StreamIO#eof?.

Returns:

  • (Boolean) 


691
692
693
694
695
696
 
# File 'ext/stringio/stringio.c', line 691

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

#eof? ⇒ Boolean

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

Raises IOError if the stream is not opened for reading.

StreamIO#eof is an alias for StreamIO#eof?.

Returns:

  • (Boolean) 


691
692
693
694
695
696
 
# File 'ext/stringio/stringio.c', line 691

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

#external_encoding ⇒ Encoding

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) 


1780
1781
1782
1783
1784
1785
 
# File 'ext/stringio/stringio.c', line 1780

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

#fcntl ⇒ Object

#fileno ⇒ nil

Returns:

  • (nil)

#flush ⇒ Object

#fsync ⇒ 0

Returns:

  • (0)

#getbyte ⇒ nil

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

Returns:

  • (nil) 


969
970
971
972
973
974
975
976
977
978
979
 
# File 'ext/stringio/stringio.c', line 969

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 ⇒ nil

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

Returns:

  • (nil) 


943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
 
# File 'ext/stringio/stringio.c', line 943

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?

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

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) 


1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
 
# File 'ext/stringio/stringio.c', line 1379

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:



699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
 
# File 'ext/stringio/stringio.c', line 699

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_encoding ⇒ Encoding

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

Returns:

  • (Encoding) 


1795
1796
1797
1798
1799
 
# File 'ext/stringio/stringio.c', line 1795

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

#isatty ⇒ nil #tty? ⇒ nil

Overloads:

  • #isatty ⇒ nil

    Returns:

    • (nil)
  • #tty? ⇒ nil

    Returns:

    • (nil)

#length ⇒ Integer #size ⇒ Integer

Returns the size of the buffer string.

Overloads:

  • #length ⇒ Integer

    Returns:

    • (Integer)
  • #size ⇒ Integer

    Returns:

    • (Integer) 


1738
1739
1740
1741
1742
1743
1744
1745
1746
 
# File 'ext/stringio/stringio.c', line 1738

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

#lineno ⇒ Object

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



724
725
726
727
728
 
# File 'ext/stringio/stringio.c', line 724

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

#lineno=(new_line_number) ⇒ Object

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



737
738
739
740
741
742
 
# File 'ext/stringio/stringio.c', line 737

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

#pid ⇒ nil

Returns:

  • (nil)

#pos ⇒ Object

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

StringIO#tell is an alias for StringIO#pos.



814
815
816
817
818
 
# File 'ext/stringio/stringio.c', line 814

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

#pos=(new_position) ⇒ Object

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



827
828
829
830
831
832
833
834
835
836
837
 
# File 'ext/stringio/stringio.c', line 827

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) 


1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
 
# File 'ext/stringio/stringio.c', line 1566

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) 


1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
 
# File 'ext/stringio/stringio.c', line 1598

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


1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
 
# File 'ext/stringio/stringio.c', line 1452

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, mode = 'r+') ⇒ self

Reinitializes the stream with the given other (string or StringIO) and mode; see IO.new:

StringIO.open('foo') do |strio|
  p strio.string
  strio.reopen('bar')
  p strio.string
  other_strio = StringIO.new('baz')
  strio.reopen(other_strio)
  p strio.string
  other_strio.close
end

Output:

"foo"
"bar"
"baz"

Returns:

  • (self) 


795
796
797
798
799
800
801
802
803
 
# File 'ext/stringio/stringio.c', line 795

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

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

Returns:

  • (0) 


847
848
849
850
851
852
853
854
 
# File 'ext/stringio/stringio.c', line 847

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

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

Returns:

  • (0) 


864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
 
# File 'ext/stringio/stringio.c', line 864

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.



1811
1812
1813
1814
1815
1816
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
1833
1834
1835
1836
1837
1838
1839
 
# File 'ext/stringio/stringio.c', line 1811

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) {
	    struct 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 ⇒ Object 



1841
1842
1843
1844
1845
1846
1847
1848
 
# File 'ext/stringio/stringio.c', line 1841

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

#length ⇒ Integer #size ⇒ Integer

Returns the size of the buffer string.

Overloads:

  • #length ⇒ Integer

    Returns:

    • (Integer)
  • #size ⇒ Integer

    Returns:

    • (Integer) 


1738
1739
1740
1741
1742
1743
1744
1745
1746
 
# File 'ext/stringio/stringio.c', line 1738

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

#string ⇒ String

Returns underlying string:

StringIO.open('foo') do |strio|
  p strio.string
  strio.string = 'bar'
  p strio.string
end

Output:

"foo"
"bar"

Related: StringIO#string= (assigns the underlying string).

Returns:

  • (String) 


529
530
531
532
533
 
# File 'ext/stringio/stringio.c', line 529

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

#string=(other_string) ⇒ Object

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



555
556
557
558
559
560
561
562
563
564
565
566
567
 
# File 'ext/stringio/stringio.c', line 555

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

#sync ⇒ true

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

Returns:

  • (true) 


902
903
904
905
906
907
 
# File 'ext/stringio/stringio.c', line 902

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

#sync=(boolean) ⇒ Boolean

Returns:

  • (Boolean)

#tell ⇒ Object

#truncate(integer) ⇒ 0

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

Returns:

  • (0) 


1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
 
# File 'ext/stringio/stringio.c', line 1755

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

Returns:

  • (Boolean)

#ungetbyte(byte) ⇒ nil

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

Returns:

  • (nil) 


1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
 
# File 'ext/stringio/stringio.c', line 1046

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

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

Returns:

  • (nil) 


1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
 
# File 'ext/stringio/stringio.c', line 1008

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) 


1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
 
# File 'ext/stringio/stringio.c', line 1480

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