Class: StringIO

Inherits:
Object
  • Object
show all
Includes:
Enumerable, IO::generic_readable, IO::generic_writable
Defined in:
ext/stringio/stringio.c

Constant Summary collapse

VERSION =

The version string

rb_str_new_cstr(STRINGIO_VERSION)
MAX_LENGTH =

Maximum length that a StringIO instance can hold

LONG2NUM(LONG_MAX)

Class Method Summary collapse

Instance Method Summary collapse

Methods included from IO::generic_readable

#read_nonblock, #readbyte, #readchar, #readline, #readpartial, #sysread

Methods included from IO::generic_writable

#<<, #print, #printf, #puts, #syswrite, #write_nonblock

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



207
208
209
210
211
212
213
214
215
216
217
 
# File 'ext/stringio/stringio.c', line 207

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:



369
370
371
372
373
374
375
376
377
378
379
 
# File 'ext/stringio/stringio.c', line 369

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) 


360
361
362
363
364
365
366
 
# File 'ext/stringio/stringio.c', line 360

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:



689
690
691
692
693
694
695
696
697
698
699
700
 
# File 'ext/stringio/stringio.c', line 689

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:



513
514
515
516
517
518
519
 
# File 'ext/stringio/stringio.c', line 513

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:



531
532
533
534
535
536
537
538
539
540
 
# File 'ext/stringio/stringio.c', line 531

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:



552
553
554
555
556
557
558
559
560
561
 
# File 'ext/stringio/stringio.c', line 552

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:



570
571
572
573
574
575
576
 
# File 'ext/stringio/stringio.c', line 570

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:



584
585
586
587
588
589
590
 
# File 'ext/stringio/stringio.c', line 584

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:



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

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.

Overloads:

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

    Yields:

    • (line)

    Returns:

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

    Yields:

    • (line)

    Returns:

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

    Yields:

    • (line)

    Returns:



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

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

    RETURN_ENUMERATOR(self, argc, argv);

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

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

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



857
858
859
860
861
862
863
864
865
866
867
868
869
 
# File 'ext/stringio/stringio.c', line 857

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:



1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
 
# File 'ext/stringio/stringio.c', line 1075

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:



1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
 
# File 'ext/stringio/stringio.c', line 1097

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.

Overloads:

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

    Yields:

    • (line)

    Returns:

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

    Yields:

    • (line)

    Returns:

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

    Yields:

    • (line)

    Returns:



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

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

    RETURN_ENUMERATOR(self, argc, argv);

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

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

#eof? ⇒ Boolean

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

Raises IOError if the stream is not opened for reading.

Returns:



624
625
626
627
628
629
 
# File 'ext/stringio/stringio.c', line 624

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.

Returns:



624
625
626
627
628
629
 
# File 'ext/stringio/stringio.c', line 624

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:



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

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:

#flush ⇒ Object

#fsync ⇒ 0

Returns:

#getbyte ⇒ nil

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

Returns:



904
905
906
907
908
909
910
911
912
913
914
 
# File 'ext/stringio/stringio.c', line 904

static VALUE
strio_getbyte(VALUE self)
{
    struct StringIO *ptr = readable(self);
    int c;
    if (NIL_P(ptr->string) || 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:



878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
 
# File 'ext/stringio/stringio.c', line 878

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 (NIL_P(str) || 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:

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

    Returns:

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

    Returns:



1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
 
# File 'ext/stringio/stringio.c', line 1333

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

    if (prepare_getline_args(ptr, &arg, argc, argv)->limit == 0) {
  if (NIL_P(ptr->string)) return Qnil;
  return rb_enc_str_new(0, 0, get_enc(ptr));
    }

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

#initialize_copy(orig) ⇒ Object

:nodoc:



632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
 
# File 'ext/stringio/stringio.c', line 632

static VALUE
strio_copy(VALUE copy, VALUE orig)
{
    struct StringIO *ptr, *old_ptr;
    VALUE old_string = Qundef;

    orig = rb_convert_type(orig, T_DATA, "StringIO", "to_strio");
    if (copy == orig) return copy;
    ptr = StringIO(orig);
    old_ptr = check_strio(copy);
    if (old_ptr) {
  old_string = old_ptr->string;
  strio_free(old_ptr);
    }
    DATA_PTR(copy) = ptr;
    RB_OBJ_WRITTEN(copy, old_string, ptr->string);
    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:



1810
1811
1812
1813
1814
 
# File 'ext/stringio/stringio.c', line 1810

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

#isatty ⇒ nil #tty? ⇒ nil

Overloads:

  • #isatty ⇒ nil

    Returns:

  • #tty? ⇒ nil

    Returns:

#length ⇒ Integer #size ⇒ Integer

Returns the size of the buffer string.

Overloads:

  • #length ⇒ Integer

    Returns:

  • #size ⇒ Integer

    Returns:



1751
1752
1753
1754
1755
1756
1757
1758
1759
 
# File 'ext/stringio/stringio.c', line 1751

static VALUE
strio_size(VALUE self)
{
    VALUE string = StringIO(self)->string;
    if (NIL_P(string)) {
  return INT2FIX(0);
    }
    return ULONG2NUM(RSTRING_LEN(string));
}

#lineno ⇒ Object

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



661
662
663
664
665
 
# File 'ext/stringio/stringio.c', line 661

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.



674
675
676
677
678
679
 
# File 'ext/stringio/stringio.c', line 674

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

#pid ⇒ nil

Returns:

#pos ⇒ Object

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



749
750
751
752
753
 
# File 'ext/stringio/stringio.c', line 749

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

#pos=(new_position) ⇒ Object

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



762
763
764
765
766
767
768
769
770
771
772
 
# File 'ext/stringio/stringio.c', line 762

static VALUE
strio_set_pos(VALUE self, VALUE pos)
{
    struct StringIO *ptr = StringIO(self);
    long p = NUM2LONG(pos);
    if (p < 0) {
  error_inval(0);
    }
    ptr->pos = p;
    return pos;
}

#pread(maxlen, offset) ⇒ String #pread(maxlen, offset, out_string) ⇒ String

See IO#pread.

Overloads:

  • #pread(maxlen, offset) ⇒ String

    Returns:

  • #pread(maxlen, offset, out_string) ⇒ String

    Returns:



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
1665
1666
1667
1668
1669
1670
 
# File 'ext/stringio/stringio.c', line 1631

static VALUE
strio_pread(int argc, VALUE *argv, VALUE self)
{
    VALUE rb_len, rb_offset, rb_buf;
    rb_scan_args(argc, argv, "21", &rb_len, &rb_offset, &rb_buf);
    long len = NUM2LONG(rb_len);
    long offset = NUM2LONG(rb_offset);

    if (len < 0) {
  rb_raise(rb_eArgError, "negative string size (or size too big): %" PRIsVALUE, rb_len);
    }

    if (len == 0) {
  if (NIL_P(rb_buf)) {
      return rb_str_new("", 0);
  }
  return rb_buf;
    }

    if (offset < 0) {
  rb_syserr_fail_str(EINVAL, rb_sprintf("pread: Invalid offset argument: %" PRIsVALUE, rb_offset));
    }

    struct StringIO *ptr = readable(self);

    if (offset >= RSTRING_LEN(ptr->string)) {
  rb_eof_error();
    }

    if (NIL_P(rb_buf)) {
  return strio_substr(ptr, offset, len, rb_ascii8bit_encoding());
    }

    long rest = RSTRING_LEN(ptr->string) - offset;
    if (len > rest) len = rest;
    rb_str_resize(rb_buf, len);
    rb_enc_associate(rb_buf, rb_ascii8bit_encoding());
    MEMCPY(RSTRING_PTR(rb_buf), RSTRING_PTR(ptr->string) + offset, char, len);
    return rb_buf;
}

#putc(obj) ⇒ Object

See IO#putc.

Returns:



1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
 
# File 'ext/stringio/stringio.c', line 1521

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

#read([length [, outbuf]]) ⇒ String?

See IO#read.

Returns:



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
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
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
 
# File 'ext/stringio/stringio.c', line 1555

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

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

    Returns:

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

    Returns:



1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
 
# File 'ext/stringio/stringio.c', line 1405

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

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

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

#reopen(other, mode = 'r+') ⇒ self

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:



732
733
734
735
736
737
738
739
740
 
# File 'ext/stringio/stringio.c', line 732

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:



782
783
784
785
786
787
788
789
 
# File 'ext/stringio/stringio.c', line 782

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:



799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
 
# File 'ext/stringio/stringio.c', line 799

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.



1826
1827
1828
1829
1830
1831
1832
1833
1834
1835
1836
1837
1838
1839
1840
1841
1842
1843
1844
1845
1846
1847
1848
1849
1850
1851
1852
1853
1854
 
# File 'ext/stringio/stringio.c', line 1826

static VALUE
strio_set_encoding(int argc, VALUE *argv, VALUE self)
{
    rb_encoding* enc;
    struct StringIO *ptr = StringIO(self);
    VALUE ext_enc, int_enc, opt;

    argc = rb_scan_args(argc, argv, "11:", &ext_enc, &int_enc, &opt);

    if (NIL_P(ext_enc)) {
  enc = rb_default_external_encoding();
    }
    else {
  enc = rb_find_encoding(ext_enc);
  if (!enc) {
      rb_io_enc_t convconfig;
      int oflags, fmode;
      VALUE vmode = rb_str_append(rb_str_new_cstr("r:"), ext_enc);
      rb_io_extract_modeenc(&vmode, 0, Qnil, &oflags, &fmode, &convconfig);
      enc = convconfig.enc2;
  }
    }
    ptr->enc = enc;
    if (!NIL_P(ptr->string) && WRITABLE(self)) {
  rb_enc_associate(ptr->string, enc);
    }

    return self;
}

#set_encoding_by_bom ⇒ nil

Sets the encoding according to the BOM (Byte Order Mark) in the string.

Returns self if the BOM is found, otherwise +nil.

Returns:



1865
1866
1867
1868
1869
1870
1871
1872
 
# File 'ext/stringio/stringio.c', line 1865

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:

  • #size ⇒ Integer

    Returns:



1751
1752
1753
1754
1755
1756
1757
1758
1759
 
# File 'ext/stringio/stringio.c', line 1751

static VALUE
strio_size(VALUE self)
{
    VALUE string = StringIO(self)->string;
    if (NIL_P(string)) {
  return INT2FIX(0);
    }
    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:



462
463
464
465
466
 
# File 'ext/stringio/stringio.c', line 462

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



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

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

#sync ⇒ true

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

Returns:



837
838
839
840
841
842
 
# File 'ext/stringio/stringio.c', line 837

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

#sync=(boolean) ⇒ Boolean

Returns:

#tell ⇒ Object

#truncate(integer) ⇒ 0

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

Returns:



1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
 
# File 'ext/stringio/stringio.c', line 1768

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

#tty? ⇒ Boolean

Returns:

#ungetbyte(byte) ⇒ nil

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

Returns:



979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
 
# File 'ext/stringio/stringio.c', line 979

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

    check_modifiable(ptr);
    if (NIL_P(ptr->string)) return Qnil;
    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:



940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
 
# File 'ext/stringio/stringio.c', line 940

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

    check_modifiable(ptr);
    if (NIL_P(ptr->string)) return Qnil;
    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:

  • #syswrite(string) ⇒ Integer

    Returns:



1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
 
# File 'ext/stringio/stringio.c', line 1433

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