Class: StringIO

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

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

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

Creates new StringIO instance from with string and mode.


165
166
167
168
169
170
171
172
173
174
175
176
# File 'stringio.c', line 165

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

    if (!ptr) {
	DATA_PTR(self) = ptr = strio_alloc();
    }
    rb_call_super(0, 0);
    strio_init(argc, argv, ptr, self);
    return self;
}

Class Method Details

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

236
237
238
239
240
241
242
# File 'stringio.c', line 236

static VALUE
strio_s_open(int argc, VALUE *argv, VALUE klass)
{
    VALUE obj = rb_class_new_instance(argc, argv, klass);
    if (!rb_block_given_p()) return obj;
    return rb_ensure(rb_yield, obj, strio_finalize, obj);
}

Instance Method Details

#binmodetrue

Returns:

  • (true)

496
497
498
499
500
501
502
503
504
505
506
507
# File 'stringio.c', line 496

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.


660
661
662
663
664
665
666
667
# File 'stringio.c', line 660

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.


877
878
879
880
881
882
883
884
# File 'stringio.c', line 877

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 strio. The strio is unavailable for any further data operations; an IOError is raised if such an attempt is made.

Returns:

  • (nil)

344
345
346
347
348
349
350
# File 'stringio.c', line 344

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 strio is not readable.

Returns:

  • (nil)

359
360
361
362
363
364
365
366
367
368
# File 'stringio.c', line 359

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 strio is not writeable.

Returns:

  • (nil)

377
378
379
380
381
382
383
384
385
386
# File 'stringio.c', line 377

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 strio is completely closed, false otherwise.

Returns:

  • (Boolean)

Returns:

  • (Boolean)

394
395
396
397
398
399
400
# File 'stringio.c', line 394

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

#closed_read?Boolean

Returns true if strio is not readable, false otherwise.

Returns:

  • (Boolean)

Returns:

  • (Boolean)

408
409
410
411
412
413
414
# File 'stringio.c', line 408

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

#closed_write?Boolean

Returns true if strio is not writable, false otherwise.

Returns:

  • (Boolean)

Returns:

  • (Boolean)

422
423
424
425
426
427
428
# File 'stringio.c', line 422

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.


921
922
923
924
925
926
927
928
# File 'stringio.c', line 921

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 = $/) {|line| ... } ⇒ Object #each(limit) {|line| ... } ⇒ Object #each(sep, limit) {|line| ... } ⇒ Object #each(...) ⇒ Enumerator

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

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

See IO#each.

Overloads:

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

    Yields:

    • (line)
  • #each(limit) {|line| ... } ⇒ Object

    Yields:

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

    Yields:

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

    Returns:

    • (Enumerator)

1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
# File 'stringio.c', line 1103

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

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

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

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

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

See IO#each_byte.

Overloads:

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

    Yields:

    • (byte)
  • #each_byteEnumerator

    Returns:

    • (Enumerator)

643
644
645
646
647
648
649
650
651
652
653
654
655
# File 'stringio.c', line 643

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)

861
862
863
864
865
866
867
868
869
870
871
872
# File 'stringio.c', line 861

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)

893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
# File 'stringio.c', line 893

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 = $/) {|line| ... } ⇒ Object #each(limit) {|line| ... } ⇒ Object #each(sep, limit) {|line| ... } ⇒ Object #each(...) ⇒ Enumerator

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

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

See IO#each.

Overloads:

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

    Yields:

    • (line)
  • #each(limit) {|line| ... } ⇒ Object

    Yields:

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

    Yields:

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

    Returns:

    • (Enumerator)

1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
# File 'stringio.c', line 1103

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

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

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

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

#eofBoolean #eof?Boolean

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

Overloads:

  • #eofBoolean

    Returns:

    • (Boolean)
  • #eof?Boolean

    Returns:

    • (Boolean)

438
439
440
441
442
443
444
# File 'stringio.c', line 438

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 strio is at end of file. The stringio must be opened for reading or an IOError will be raised.

Overloads:

  • #eofBoolean

    Returns:

    • (Boolean)
  • #eof?Boolean

    Returns:

    • (Boolean)

Returns:

  • (Boolean)

438
439
440
441
442
443
444
# File 'stringio.c', line 438

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 strio is write mode and no encoding is specified, returns nil.

Returns:

  • (Encoding)

1452
1453
1454
1455
1456
1457
# File 'stringio.c', line 1452

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)

698
699
700
701
702
703
704
705
706
707
708
# File 'stringio.c', line 698

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)

675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
# File 'stringio.c', line 675

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

    if (ptr->pos >= RSTRING_LEN(ptr->string)) {
	return Qnil;
    }
    p = RSTRING_PTR(ptr->string)+ptr->pos;
    len = rb_enc_mbclen(p, RSTRING_END(ptr->string), enc);
    ptr->pos += len;
    return rb_enc_str_new(p, len, enc);
}

#gets(sep = $/) ⇒ String? #gets(limit) ⇒ String? #gets(sep, limit) ⇒ String?

See IO#gets.

Overloads:

  • #gets(sep = $/) ⇒ String?

    Returns:

    • (String, nil)
  • #gets(limit) ⇒ String?

    Returns:

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

    Returns:

    • (String, nil)

1064
1065
1066
1067
1068
1069
1070
1071
# File 'stringio.c', line 1064

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

    rb_lastline_set(str);
    return str;
}

#initialize_copy(orig) ⇒ Object

:nodoc:


447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
# File 'stringio.c', line 447

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;
    OBJ_INFECT(copy, orig);
    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)

1467
1468
1469
1470
1471
# File 'stringio.c', line 1467

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)

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

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

Returns:

  • (Integer)

476
477
478
479
480
# File 'stringio.c', line 476

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)

489
490
491
492
493
494
# File 'stringio.c', line 489

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.


1125
1126
1127
1128
1129
1130
1131
1132
# File 'stringio.c', line 1125

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

Overloads:

  • #posInteger

    Returns:

    • (Integer)
  • #tellInteger

    Returns:

    • (Integer)

541
542
543
544
545
# File 'stringio.c', line 541

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

#pos=(integer) ⇒ Integer

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

Returns:

  • (Integer)

553
554
555
556
557
558
559
560
561
562
563
# File 'stringio.c', line 553

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)

1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
# File 'stringio.c', line 1243

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)

1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
# File 'stringio.c', line 1275

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);
	}
      case 1:
	if (!NIL_P(argv[0])) {
	    len = NUM2LONG(argv[0]);
	    if (len < 0) {
		rb_raise(rb_eArgError, "negative length %ld given", len);
	    }
	    if (len > 0 && ptr->pos >= RSTRING_LEN(ptr->string)) {
		if (!NIL_P(str)) rb_str_resize(str, 0);
		return Qnil;
	    }
	    binary = 1;
	    break;
	}
	/* fall through */
      case 0:
	len = RSTRING_LEN(ptr->string);
	if (len <= ptr->pos) {
	    if (NIL_P(str)) {
		str = rb_str_new(0, 0);
	    }
	    else {
		rb_str_resize(str, 0);
	    }
	    return str;
	}
	else {
	    len -= ptr->pos;
	}
	break;
    }
    if (NIL_P(str)) {
	str = strio_substr(ptr, ptr->pos, len);
	if (binary) rb_enc_associate(str, rb_ascii8bit_encoding());
    }
    else {
	long rest = RSTRING_LEN(ptr->string) - ptr->pos;
	if (len > rest) len = rest;
	rb_str_resize(str, len);
	MEMCPY(RSTRING_PTR(str), RSTRING_PTR(ptr->string) + ptr->pos, char, len);
	if (binary)
	    rb_enc_associate(str, rb_ascii8bit_encoding());
	else
	    rb_enc_copy(str, ptr->string);
    }
    ptr->pos += RSTRING_LEN(str);
    return str;
}

#readlines(sep = $/) ⇒ Array #readlines(limit) ⇒ Array #readlines(sep, limit) ⇒ Array

See IO#readlines.

Overloads:

  • #readlines(sep = $/) ⇒ Array

    Returns:

    • (Array)
  • #readlines(limit) ⇒ Array

    Returns:

    • (Array)
  • #readlines(sep, limit) ⇒ Array

    Returns:

    • (Array)

1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
# File 'stringio.c', line 1142

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

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

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

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

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


523
524
525
526
527
528
529
530
531
532
# File 'stringio.c', line 523

static VALUE
strio_reopen(int argc, VALUE *argv, VALUE self)
{
    rb_io_taint_check(self);
    if (argc == 1 && !RB_TYPE_P(*argv, T_STRING)) {
	return strio_copy(self, *argv);
    }
    strio_init(argc, argv, StringIO(self), self);
    return self;
}

#rewind0

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

Returns:

  • (0)

572
573
574
575
576
577
578
579
# File 'stringio.c', line 572

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)

588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
# File 'stringio.c', line 588

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

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

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


1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
# File 'stringio.c', line 1483

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

#lengthInteger #sizeInteger

Returns the size of the buffer string.

Overloads:

  • #lengthInteger

    Returns:

    • (Integer)
  • #sizeInteger

    Returns:

    • (Integer)

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

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)

311
312
313
314
315
# File 'stringio.c', line 311

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

#string=(string) ⇒ String

Changes underlying String object, the subject of IO.

Returns:

  • (String)

323
324
325
326
327
328
329
330
331
332
333
334
335
# File 'stringio.c', line 323

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)

625
626
627
628
629
630
# File 'stringio.c', line 625

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 strio must be opened for writing.

Returns:

  • (0)

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

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)

771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
# File 'stringio.c', line 771

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

    check_modifiable(ptr);
    if (NIL_P(c)) return Qnil;
    if (FIXNUM_P(c)) {
	buf[0] = (char)FIX2INT(c);
	return strio_unget_bytes(ptr, buf, 1);
    }
    else {
	SafeStringValue(c);
	cp = RSTRING_PTR(c);
	cl = RSTRING_LEN(c);
	if (cl == 0) return Qnil;
	strio_unget_bytes(ptr, cp, cl);
	RB_GC_GUARD(c);
	return Qnil;
    }
}

#ungetc(string) ⇒ nil

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

Returns:

  • (nil)

736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
# File 'stringio.c', line 736

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 (FIXNUM_P(c)) {
	int cc = FIX2INT(c);
	char buf[16];

	enc = rb_enc_get(ptr->string);
	rb_enc_mbcput(cc, buf, enc);
	return strio_unget_bytes(ptr, buf, rb_enc_codelen(cc, enc));
    }
    else {
	SafeStringValue(c);
	enc = rb_enc_get(ptr->string);
	enc2 = rb_enc_get(c);
	if (enc != enc2 && enc != rb_ascii8bit_encoding()) {
	    c = rb_str_conv_enc(c, enc2, enc);
	}
	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 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.

Overloads:

  • #write(string) ⇒ Integer

    Returns:

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

    Returns:

    • (Integer)

1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
# File 'stringio.c', line 1170

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

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