stringio 3.1.6 → 3.1.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 144b6bb8aaa29ad8b3447e979841af712093bdfe19623f26d46a595740541da6
-  data.tar.gz: a0936d98e00b6dec96769e8189b564fee83d922a7d7f2787fa58b15e648ff22f
+  metadata.gz: 7955baf0f07b14461ca7f88b4c2f97383d9cf1114e07fd7408e1e332f974c139
+  data.tar.gz: 4169d5e9055f8ce90725fc374030ff97b8473734741c3cb741527f7e0aefd865
 SHA512:
-  metadata.gz: 3c49d46b584a010121a0c20a176a1e389178f8e53810d9898107c28154116519caf8883d68339a69a580b684f236854c36eecd4562182bf1724e67d951351a05
-  data.tar.gz: 69189970d83c1093020071a1c86c7eb60067b06e0500b112aa55c82ad97a95ad4ba66ce7f08c018ae58312a662a9cc55de59129c5d6ebcad93c2ec9c5927ed98
+  metadata.gz: e91d6fa5462e3afec46f4e709dd746e8bb275198825eca723634b2837207270c05973f224884525da256fd1ad17b1da7659046f78135ba958651715c7a34b5f7
+  data.tar.gz: 673e6b9e4e59a31b708963893bcc9ea80e01351b272b82992467b72e8c7a074eb9f2f8f854cbdc2767ca826c5d9351cfaa82ce721e8a32dca41ca6ad9a47f883

data/.rdoc_options

@@ -1,2 +1,5 @@
 ---
 main_page: README.md
+rdoc_include:
+- doc
+op_dir: html

data/NEWS.md

@@ -1,5 +1,49 @@
 # News
 
+## 3.1.8 - 2025-11-12
+
+### Improvements
+
+  * Improved documents
+    * Patch by Burdette Lamar
+
+### Fixes
+
+  * Fixed SEGV in `StringIO#seek` with `SEEK_END` on `StringIO.new(nil)`
+    * GH-137
+    * Patch by koh-sh
+
+  * Fixed SEGV in `StringIO#read` on `StringIO.new(nil)`
+
+  * Fixed SEGV in `StringIO#pread` on `StringIO.new(nil)`
+
+  * Fixed SEGV in `StringIO#eof?` on `StringIO.new(nil)`
+
+  * JRuby: Fixed a bug that `StringIO#read` doesn't clear code range
+    * GH-156
+    * Patch by Karol Bucek
+
+### Thanks
+
+  * koh-sh
+
+  * Burdette Lamar
+
+  * Karol Bucek
+
+## 3.1.7 - 2025-04-21
+
+### Improvements
+
+  * CRuby: Added support for `rb_io_mode_t` that will be introduced in
+    Ruby 3.5 or later.
+    * GH-129
+    * Patch by Samuel Williams
+
+### Thanks
+
+  * Samuel Williams
+
 ## 3.1.6 - 2025-03-25
 
 ### Fixes

data/docs/io.rb

@@ -1,8 +1,3 @@
-# :stopdoc:
+# The {built-in class for I/O}[https://docs.ruby-lang.org/en/master/IO.html].
 class IO
-  module generic_readable
-  end
-  module generic_writable
-  end
 end
-# :startdoc:

data/ext/stringio/extconf.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: false
 require 'mkmf'
 if RUBY_ENGINE == 'ruby'
+  have_type("rb_io_mode_t", "ruby/io.h")
+
   create_makefile('stringio')
 else
   File.write('Makefile', dummy_makefile("").join)

data/ext/stringio/stringio.c

@@ -13,13 +13,14 @@
 **********************************************************************/
 
 static const char *const
-STRINGIO_VERSION = "3.1.6";
+STRINGIO_VERSION = "3.1.8";
 
 #include <stdbool.h>
 
 #include "ruby.h"
 #include "ruby/io.h"
 #include "ruby/encoding.h"
+#include "ruby/version.h"
 #if defined(HAVE_FCNTL_H) || defined(_WIN32)
 #include <fcntl.h>
 #elif defined(HAVE_SYS_FCNTL_H)
@@ -35,12 +36,29 @@ STRINGIO_VERSION = "3.1.6";
 # define rb_class_new_instance_kw(argc, argv, klass, kw_splat) rb_class_new_instance(argc, argv, klass)
 #endif
 
+static inline bool
+str_chilled_p(VALUE str)
+{
+#if (RUBY_API_VERSION_MAJOR == 3 && RUBY_API_VERSION_MINOR >= 4) || RUBY_API_VERSION_MAJOR >= 4
+    // Do not attempt to modify chilled strings on Ruby 3.4+
+    // RUBY_FL_USER2 == STR_CHILLED_LITERAL
+    // RUBY_FL_USER3 == STR_CHILLED_SYMBOL_TO_S
+    return FL_TEST_RAW(str, RUBY_FL_USER2 | RUBY_FL_USER3);
+#else
+    return false;
+#endif
+}
+
+#ifndef HAVE_TYPE_RB_IO_MODE_T
+typedef int rb_io_mode_t;
+#endif
+
 struct StringIO {
     VALUE string;
     rb_encoding *enc;
     long pos;
     long lineno;
-    int flags;
+    rb_io_mode_t flags;
     int count;
 };
 
@@ -185,6 +203,18 @@ check_modifiable(struct StringIO *ptr)
     }
 }
 
+static inline bool
+outside_p(struct StringIO *ptr, long pos)
+{
+    return NIL_P(ptr->string) || pos >= RSTRING_LEN(ptr->string);
+}
+
+static inline bool
+eos_p(struct StringIO *ptr)
+{
+    return outside_p(ptr, ptr->pos);
+}
+
 static VALUE
 strio_s_allocate(VALUE klass)
 {
@@ -195,17 +225,32 @@ strio_s_allocate(VALUE klass)
  * call-seq:
  *   StringIO.new(string = '', mode = 'r+') -> new_stringio
  *
- * Note that +mode+ defaults to <tt>'r'</tt> if +string+ is frozen.
- *
  * Returns a new \StringIO instance formed from +string+ and +mode+;
- * see {Access Modes}[rdoc-ref:File@Access+Modes]:
+ * the instance should be closed when no longer needed:
+ *
+ *   strio = StringIO.new
+ *   strio.string        # => ""
+ *   strio.closed_read?  # => false
+ *   strio.closed_write? # => false
+ *   strio.close
  *
- *   strio = StringIO.new # => #<StringIO>
+ * If +string+ is frozen, the default +mode+ is <tt>'r'</tt>:
+ *
+ *   strio = StringIO.new('foo'.freeze)
+ *   strio.string        # => "foo"
+ *   strio.closed_read?  # => false
+ *   strio.closed_write? # => true
  *   strio.close
  *
- * The instance should be closed when no longer needed.
+ * Argument +mode+ must be a valid
+ * {Access Mode}[https://docs.ruby-lang.org/en/master/File.html#class-File-label-Access+Modes],
+ * which may be a string or an integer constant:
+ *
+ *   StringIO.new('foo', 'w+')
+ *   StringIO.new('foo', File::RDONLY)
  *
- * Related: StringIO.open (accepts block; closes automatically).
+ * Related: StringIO.open
+ * (passes the \StringIO object to the block; closes the object automatically on block exit).
  */
 static VALUE
 strio_initialize(int argc, VALUE *argv, VALUE self)
@@ -340,23 +385,20 @@ strio_finalize(VALUE self)
 
 /*
  * call-seq:
- *   StringIO.open(string = '', mode = 'r+') {|strio| ... }
- *
- * Note that +mode+ defaults to <tt>'r'</tt> if +string+ is frozen.
+ *   StringIO.open(string = '', mode = 'r+') -> new_stringio
+ *   StringIO.open(string = '', mode = 'r+') {|strio| ... } -> object
  *
- * Creates a new \StringIO instance formed from +string+ and +mode+;
- * see {Access Modes}[rdoc-ref:File@Access+Modes].
+ * Creates new \StringIO instance by calling <tt>StringIO.new(string, mode)</tt>.
  *
- * With no block, returns the new instance:
+ * With no block given, returns the new instance:
  *
  *   strio = StringIO.open # => #<StringIO>
  *
- * With a block, calls the block with the new instance
+ * With a block given, calls the block with the new instance
  * and returns the block's value;
- * closes the instance on block exit.
+ * closes the instance on block exit:
  *
- *   StringIO.open {|strio| p strio }
- *   # => #<StringIO>
+ *   StringIO.open('foo') {|strio| strio.string.upcase } # => "FOO"
  *
  * Related: StringIO.new.
  */
@@ -382,7 +424,7 @@ strio_s_new(int argc, VALUE *argv, VALUE klass)
 }
 
 /*
- * Returns +false+.  Just for compatibility to IO.
+ * Returns +false+; for compatibility with IO.
  */
 static VALUE
 strio_false(VALUE self)
@@ -392,7 +434,7 @@ strio_false(VALUE self)
 }
 
 /*
- * Returns +nil+.  Just for compatibility to IO.
+ * Returns +nil+; for compatibility with IO.
  */
 static VALUE
 strio_nil(VALUE self)
@@ -402,7 +444,7 @@ strio_nil(VALUE self)
 }
 
 /*
- * Returns an object itself.  Just for compatibility to IO.
+ * Returns +self+; for compatibility with IO.
  */
 static VALUE
 strio_self(VALUE self)
@@ -412,7 +454,7 @@ strio_self(VALUE self)
 }
 
 /*
- * Returns 0.  Just for compatibility to IO.
+ * Returns 0; for compatibility with IO.
  */
 static VALUE
 strio_0(VALUE self)
@@ -472,7 +514,7 @@ strio_get_string(VALUE self)
  * call-seq:
  *   string = other_string -> other_string
  *
- * Assigns the underlying string as +other_string+, and sets position to zero;
+ * Replaces the stored string with +other_string+, and sets the position to zero;
  * returns +other_string+:
  *
  *   StringIO.open('foo') do |strio|
@@ -486,7 +528,7 @@ strio_get_string(VALUE self)
  *   "foo"
  *   "bar"
  *
- * Related: StringIO#string (returns the underlying string).
+ * Related: StringIO#string (returns the stored string).
  */
 static VALUE
 strio_set_string(VALUE self, VALUE string)
@@ -507,11 +549,16 @@ strio_set_string(VALUE self, VALUE string)
  * call-seq:
  *   close -> nil
  *
- * Closes +self+ for both reading and writing.
+ * Closes +self+ for both reading and writing; returns +nil+:
  *
- * Raises IOError if reading or writing is attempted.
+ *   strio = StringIO.new
+ *   strio.closed? # => false
+ *   strio.close   # => nil
+ *   strio.closed? # => true
+ *   strio.read    # Raises IOError: not opened for reading
+ *   strio.write   # Raises IOError: not opened for writing
  *
- * Related: StringIO#close_read, StringIO#close_write.
+ * Related: StringIO#close_read, StringIO#close_write, StringIO.closed?.
  */
 static VALUE
 strio_close(VALUE self)
@@ -525,9 +572,16 @@ strio_close(VALUE self)
  * call-seq:
  *   close_read -> nil
  *
- * Closes +self+ for reading; closed-write setting remains unchanged.
+ * Closes +self+ for reading;
+ * closed-write setting remains unchanged;
+ * returns +nil+:
  *
- * Raises IOError if reading is attempted.
+ *   strio = StringIO.new
+ *   strio.closed_read?  # => false
+ *   strio.close_read    # => nil
+ *   strio.closed_read?  # => true
+ *   strio.closed_write? # => false
+ *   strio.read          # Raises IOError: not opened for reading
  *
  * Related: StringIO#close, StringIO#close_write.
  */
@@ -546,11 +600,16 @@ strio_close_read(VALUE self)
  * call-seq:
  *   close_write -> nil
  *
- * Closes +self+ for writing; closed-read setting remains unchanged.
+ * Closes +self+ for writing; closed-read setting remains unchanged; returns +nil+:
  *
- * Raises IOError if writing is attempted.
+ *   strio = StringIO.new
+ *   strio.closed_write? # => false
+ *   strio.close_write   # => nil
+ *   strio.closed_write? # => true
+ *   strio.closed_read?  # => false
+ *   strio.write('foo')  # Raises IOError: not opened for writing
  *
- * Related: StringIO#close, StringIO#close_read.
+ * Related: StringIO#close, StringIO#close_read, StringIO#closed_write?.
  */
 static VALUE
 strio_close_write(VALUE self)
@@ -567,8 +626,16 @@ strio_close_write(VALUE self)
  * call-seq:
  *   closed? -> true or false
  *
- * Returns +true+ if +self+ is closed for both reading and writing,
- * +false+ otherwise.
+ * Returns whether +self+ is closed for both reading and writing:
+ *
+ *   strio = StringIO.new
+ *   strio.closed?     # => false  # Open for reading and writing.
+ *   strio.close_read
+ *   strio.closed?     # => false  # Still open for writing.
+ *   strio.close_write
+ *   strio.closed?     # => true   # Now closed for both.
+ *
+ * Related: StringIO.closed_read?, StringIO.closed_write?.
  */
 static VALUE
 strio_closed(VALUE self)
@@ -582,7 +649,14 @@ strio_closed(VALUE self)
  * call-seq:
  *   closed_read? -> true or false
  *
- * Returns +true+ if +self+ is closed for reading, +false+ otherwise.
+ * Returns whether +self+ is closed for reading:
+ *
+ *   strio = StringIO.new
+ *   strio.closed_read?   # => false
+ *   strio.close_read
+ *   strio.closed_read?   # => true
+ *
+ * Related: StringIO#closed?, StringIO#closed_write?, StringIO#close_read.
  */
 static VALUE
 strio_closed_read(VALUE self)
@@ -596,7 +670,14 @@ strio_closed_read(VALUE self)
  * call-seq:
  *   closed_write? -> true or false
  *
- * Returns +true+ if +self+ is closed for writing, +false+ otherwise.
+ * Returns whether +self+ is closed for writing:
+ *
+ *   strio = StringIO.new
+ *   strio.closed_write? # => false
+ *   strio.close_write
+ *   strio.closed_write? # => true
+ *
+ * Related: StringIO#close_write, StringIO#closed?, StringIO#closed_read?.
  */
 static VALUE
 strio_closed_write(VALUE self)
@@ -610,19 +691,26 @@ static struct StringIO *
 strio_to_read(VALUE self)
 {
     struct StringIO *ptr = readable(self);
-    if (NIL_P(ptr->string)) return NULL;
-    if (ptr->pos < RSTRING_LEN(ptr->string)) return ptr;
-    return NULL;
+    if (eos_p(ptr)) return NULL;
+    return ptr;
 }
 
 /*
  * call-seq:
  *   eof? -> true or false
  *
- * Returns +true+ if positioned at end-of-stream, +false+ otherwise;
- * see {Position}[rdoc-ref:IO@Position].
+ * Returns whether +self+ is positioned at end-of-stream:
+ *
+ *   strio = StringIO.new('foo')
+ *   strio.pos  # => 0
+ *   strio.eof? # => false
+ *   strio.read # => "foo"
+ *   strio.pos  # => 3
+ *   strio.eof? # => true
+ *   strio.close_read
+ *   strio.eof? # Raises IOError: not opened for reading
  *
- * Raises IOError if the stream is not opened for reading.
+ * Related: StringIO#pos.
  */
 static VALUE
 strio_eof(VALUE self)
@@ -686,7 +774,7 @@ strio_set_lineno(VALUE self, VALUE lineno)
  *   binmode -> self
  *
  * Sets the data mode in +self+ to binary mode;
- * see {Data Mode}[rdoc-ref:File@Data+Mode].
+ * see {Data Mode}[https://docs.ruby-lang.org/en/master/File.html#class-File-label-Data+Mode].
  *
  */
 static VALUE
@@ -819,7 +907,11 @@ strio_seek(int argc, VALUE *argv, VALUE self)
 	offset = ptr->pos;
 	break;
       case 2:
-	offset = RSTRING_LEN(ptr->string);
+	if (NIL_P(ptr->string)) {
+	    offset = 0;
+	} else {
+	    offset = RSTRING_LEN(ptr->string);
+	}
 	break;
       default:
 	error_inval("invalid whence");
@@ -852,10 +944,9 @@ strio_get_sync(VALUE self)
  * call-seq:
  *   each_byte {|byte| ... } -> self
  *
- * With a block given, calls the block with each remaining byte in the stream;
- * see {Byte IO}[rdoc-ref:IO@Byte+IO].
+ * :include: stringio/each_byte.rdoc
  *
- * With no block given, returns an enumerator.
+ * Related: StringIO#each_char, StringIO#each_codepoint, StringIO#each_line.
  */
 static VALUE
 strio_each_byte(VALUE self)
@@ -873,10 +964,10 @@ strio_each_byte(VALUE self)
 
 /*
  * call-seq:
- *   getc -> character or nil
+ *   getc -> character, byte, or nil
+ *
+ * :include: stringio/getc.rdoc
  *
- * Reads and returns the next character from the stream;
- * see {Character IO}[rdoc-ref:IO@Character+IO].
  */
 static VALUE
 strio_getc(VALUE self)
@@ -888,7 +979,7 @@ strio_getc(VALUE self)
     int len;
     char *p;
 
-    if (NIL_P(str) || pos >= RSTRING_LEN(str)) {
+    if (eos_p(ptr)) {
 	return Qnil;
     }
     p = RSTRING_PTR(str)+pos;
@@ -899,17 +990,17 @@ strio_getc(VALUE self)
 
 /*
  * call-seq:
- *   getbyte -> byte or nil
+ *   getbyte -> integer or nil
+ *
+ * :include: stringio/getbyte.rdoc
  *
- * Reads and returns the next 8-bit byte from the stream;
- * see {Byte IO}[rdoc-ref:IO@Byte+IO].
  */
 static VALUE
 strio_getbyte(VALUE self)
 {
     struct StringIO *ptr = readable(self);
     int c;
-    if (NIL_P(ptr->string) || ptr->pos >= RSTRING_LEN(ptr->string)) {
+    if (eos_p(ptr)) {
 	return Qnil;
     }
     c = RSTRING_PTR(ptr->string)[ptr->pos++];
@@ -1078,12 +1169,11 @@ strio_readbyte(VALUE self)
 
 /*
  * call-seq:
- *   each_char {|c| ... } -> self
+ *   each_char {|char| ... } -> self
  *
- * With a block given, calls the block with each remaining character in the stream;
- * see {Character IO}[rdoc-ref:IO@Character+IO].
+ * :include: stringio/each_char.rdoc
  *
- * With no block given, returns an enumerator.
+ * Related: StringIO#each_byte, StringIO#each_codepoint, StringIO#each_line.
  */
 static VALUE
 strio_each_char(VALUE self)
@@ -1102,10 +1192,9 @@ strio_each_char(VALUE self)
  * call-seq:
  *   each_codepoint {|codepoint| ... } -> self
  *
- * With a block given, calls the block with each remaining codepoint in the stream;
- * see {Codepoint IO}[rdoc-ref:IO@Codepoint+IO].
+ * :include: stringio/each_codepoint.rdoc
  *
- * With no block given, returns an enumerator.
+ * Related: StringIO#each_byte, StringIO#each_char, StringIO#each_line.
  */
 static VALUE
 strio_each_codepoint(VALUE self)
@@ -1339,9 +1428,8 @@ strio_getline(struct getline_arg *arg, struct StringIO *ptr)
  *   gets(limit, chomp: false) -> string or nil
  *   gets(sep, limit, chomp: false) -> string or nil
  *
- * Reads and returns a line from the stream;
- * assigns the return value to <tt>$_</tt>;
- * see {Line IO}[rdoc-ref:IO@Line+IO].
+ * :include: stringio/gets.rdoc
+ *
  */
 static VALUE
 strio_gets(int argc, VALUE *argv, VALUE self)
@@ -1378,15 +1466,177 @@ strio_readline(int argc, VALUE *argv, VALUE self)
 }
 
 /*
+ * :markup: markdown
+ *
  * call-seq:
  *   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}[rdoc-ref:IO@Line+IO].
+ * With a block given calls the block with each remaining line (see "Position" below) in the stream;
+ * returns `self`.
+ *
+ * Leaves stream position as end-of-stream.
+ *
+ * **No Arguments**
+ *
+ * With no arguments given,
+ * reads lines using the default record separator global variable `$/`, whose initial value is `"\n"`.
+ *
+ * ```
+ * strio = StringIO.new(TEXT)
+ * strio.each_line {|line| p line }
+ * strio.eof? # => true
+ * ```
+ *
+ * Output:
+ *
+ * ```
+ * "First line\n"
+ * "Second line\n"
+ * "\n"
+ * "Fourth line\n"
+ * "Fifth line\n"
+ * ```
+ *
+ * **Argument `sep`**
+ *
+ * With only string argument `sep` given,
+ * reads lines using that string as the record separator:
+ *
+ * ```
+ * strio = StringIO.new(TEXT)
+ * strio.each_line(' ') {|line| p line }
+ * ```
+ *
+ * Output:
+ *
+ * ```
+ * "First "
+ * "line\nSecond "
+ * "line\n\nFourth "
+ * "line\nFifth "
+ * "line\n"
+ * ```
+ *
+ * **Argument `limit`**
+ *
+ * With only integer argument `limit` given,
+ * reads lines using the default record separator global variable `$/`, whose initial value is `"\n"`;
+ * also limits the size (in characters) of each line to the given limit:
+ *
+ * ```
+ * strio = StringIO.new(TEXT)
+ * strio.each_line(10) {|line| p line }
+ * ```
+ *
+ * Output:
+ *
+ * ```
+ * "First line"
+ * "\n"
+ * "Second lin"
+ * "e\n"
+ * "\n"
+ * "Fourth lin"
+ * "e\n"
+ * "Fifth line"
+ * "\n"
+ * ```
+ * **Arguments `sep` and `limit`**
+ *
+ * With arguments `sep` and `limit` both given,
+ * honors both:
+ *
+ * ```
+ * strio = StringIO.new(TEXT)
+ * strio.each_line(' ', 10) {|line| p line }
+ * ```
+ *
+ * Output:
+ *
+ * ```
+ * "First "
+ * "line\nSecon"
+ * "d "
+ * "line\n\nFour"
+ * "th "
+ * "line\nFifth"
+ * " "
+ * "line\n"
+ * ```
+ *
+ * **Position**
+ *
+ * As stated above, method `each` _remaining_ line in the stream.
+ *
+ * In the examples above each `strio` object starts with its position at beginning-of-stream;
+ * but in other cases the position may be anywhere (see StringIO#pos):
+ *
+ * ```
+ * strio = StringIO.new(TEXT)
+ * strio.pos = 30 # Set stream position to character 30.
+ * strio.each_line {|line| p line }
+ * ```
+ *
+ * Output:
+ *
+ * ```
+ * " line\n"
+ * "Fifth line\n"
+ * ```
+ *
+ * **Special Record Separators**
+ *
+ * Like some methds in class `IO`, StringIO.each honors two special record separators;
+ * see {Special Line Separators}[https://docs.ruby-lang.org/en/master/IO.html#class-IO-label-Special+Line+Separator+Values].
+ *
+ * ```
+ * strio = StringIO.new(TEXT)
+ * strio.each_line('') {|line| p line } # Read as paragraphs (separated by blank lines).
+ * ```
+ *
+ * Output:
+ *
+ * ```
+ * "First line\nSecond line\n\n"
+ * "Fourth line\nFifth line\n"
+ * ```
+ *
+ * ```
+ * strio = StringIO.new(TEXT)
+ * strio.each_line(nil) {|line| p line } # "Slurp"; read it all.
+ * ```
+ *
+ * Output:
+ *
+ * ```
+ * "First line\nSecond line\n\nFourth line\nFifth line\n"
+ * ```
+ *
+ * **Keyword Argument `chomp`**
+ *
+ * With keyword argument `chomp` given as `true` (the default is `false`),
+ * removes trailing newline (if any) from each line:
+ *
+ * ```
+ * strio = StringIO.new(TEXT)
+ * strio.each_line(chomp: true) {|line| p line }
+ * ```
+ *
+ * Output:
+ *
+ * ```
+ * "First line"
+ * "Second line"
+ * ""
+ * "Fourth line"
+ * "Fifth line"
+ * ```
+ *
+ * With no block given, returns a new {Enumerator}[https://docs.ruby-lang.org/en/master/Enumerator.html].
+ *
+ * Related: StringIO.each_byte, StringIO.each_char, StringIO.each_codepoint.
  */
 static VALUE
 strio_each(int argc, VALUE *argv, VALUE self)
@@ -1587,10 +1837,9 @@ strio_read(int argc, VALUE *argv, VALUE self)
 	    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 (eos_p(ptr)) {
 		if (!NIL_P(str)) rb_str_resize(str, 0);
-		return Qnil;
+		return len > 0 ? Qnil : rb_str_new(0, 0);
 	    }
 	    binary = 1;
 	    break;
@@ -1666,7 +1915,7 @@ strio_pread(int argc, VALUE *argv, VALUE self)
 
     struct StringIO *ptr = readable(self);
 
-    if (offset >= RSTRING_LEN(ptr->string)) {
+    if (outside_p(ptr, offset)) {
 	rb_eof_error();
     }
 
@@ -1797,12 +2046,20 @@ strio_truncate(VALUE self, VALUE len)
 }
 
 /*
- *  call-seq:
- *     strio.external_encoding   => encoding
+ * call-seq:
+ *   external_encoding -> encoding or nil
+ *
+ * Returns an Encoding object that represents the encoding of the string;
+ * see {Encoding}[https://docs.ruby-lang.org/en/master/Encoding.html]:
+ *
+ *   strio = StringIO.new('foo')
+ *   strio.external_encoding # => #<Encoding:UTF-8>
+ *
+ * Returns +nil+ if +self+ has no string and is in write mode:
+ *
+ *   strio = StringIO.new(nil, 'w+')
+ *   strio.external_encoding # => nil
  *
- *  Returns the Encoding object that represents the encoding of the file.
- *  If the stream is write mode and no encoding is specified, returns
- *  +nil+.
  */
 
 static VALUE
@@ -1814,10 +2071,9 @@ strio_external_encoding(VALUE self)
 
 /*
  *  call-seq:
- *     strio.internal_encoding   => encoding
+ *     internal_encoding -> nil
  *
- *  Returns the Encoding of the internal string if conversion is
- *  specified.  Otherwise returns +nil+.
+ *  Returns +nil+; for compatibility with IO.
  */
 
 static VALUE
@@ -1852,14 +2108,15 @@ strio_set_encoding(int argc, VALUE *argv, VALUE self)
 	enc = rb_find_encoding(ext_enc);
 	if (!enc) {
 	    rb_io_enc_t convconfig;
-	    int oflags, fmode;
+	    int oflags;
+	    rb_io_mode_t 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)) {
+    if (!NIL_P(ptr->string) && WRITABLE(self) && !str_chilled_p(ptr->string)) {
 	rb_enc_associate(ptr->string, enc);
     }
 
@@ -1885,16 +2142,9 @@ strio_set_encoding_by_bom(VALUE self)
 }
 
 /*
- * \IO streams for strings, with access similar to
- * {IO}[rdoc-ref:IO];
- * see {IO}[rdoc-ref:IO].
- *
- * === About the Examples
- *
- * Examples on this page assume that \StringIO has been required:
- *
- *   require 'stringio'
+ * :markup: markdown
  *
+ * :include: stringio/stringio.md
  */
 void
 Init_stringio(void)
@@ -1902,7 +2152,7 @@ Init_stringio(void)
 #undef rb_intern
 
 #ifdef HAVE_RB_EXT_RACTOR_SAFE
-  rb_ext_ractor_safe(true);
+    rb_ext_ractor_safe(true);
 #endif
 
     VALUE StringIO = rb_define_class("StringIO", rb_cObject);
@@ -1994,7 +2244,9 @@ Init_stringio(void)
     rb_define_method(StringIO, "set_encoding_by_bom", strio_set_encoding_by_bom, 0);
 
     {
+	/* :stopdoc: */
 	VALUE mReadable = rb_define_module_under(rb_cIO, "generic_readable");
+	/* :startdoc: */
 	rb_define_method(mReadable, "readchar", strio_readchar, 0);
 	rb_define_method(mReadable, "readbyte", strio_readbyte, 0);
 	rb_define_method(mReadable, "readline", strio_readline, -1);
@@ -2004,7 +2256,9 @@ Init_stringio(void)
 	rb_include_module(StringIO, mReadable);
     }
     {
+	/* :stopdoc: */
 	VALUE mWritable = rb_define_module_under(rb_cIO, "generic_writable");
+	/* :startdoc: */
 	rb_define_method(mWritable, "<<", strio_addstr, 1);
 	rb_define_method(mWritable, "print", strio_print, -1);
 	rb_define_method(mWritable, "printf", strio_printf, -1);

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: stringio
 version: !ruby/object:Gem::Version
-  version: 3.1.6
+  version: 3.1.8
 platform: ruby
 authors:
 - Nobu Nakada
 - Charles Oliver Nutter
 bindir: bin
 cert_chain: []
-date: 2025-03-25 00:00:00.000000000 Z
+date: 2025-11-12 00:00:00.000000000 Z
 dependencies: []
 description: Pseudo `IO` class from/to `String`.
 email:
@@ -42,7 +42,7 @@ licenses:
 - Ruby
 - BSD-2-Clause
 metadata:
-  changelog_uri: https://github.com/ruby/stringio/releases/tag/v3.1.6
+  changelog_uri: https://github.com/ruby/stringio/releases/tag/v3.1.8
 rdoc_options: []
 require_paths:
 - lib
@@ -57,7 +57,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.2
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Pseudo IO on String
 test_files: []