From 3462ca8b1b96833b5b0e8b3a5e84c94693a0c658 Mon Sep 17 00:00:00 2001
From: BurdetteLamar <burdettelamar@yahoo.com>
Date: Sun, 7 Dec 2025 19:58:50 +0000
Subject: [PATCH 1/2] [DOC] Doc for StringIO#putc

---
 doc/stringio/putc.rdoc  | 72 +++++++++++++++++++++++++++++++++++++++++
 ext/stringio/stringio.c |  5 +--
 2 files changed, 75 insertions(+), 2 deletions(-)
 create mode 100644 doc/stringio/putc.rdoc

diff --git a/doc/stringio/putc.rdoc b/doc/stringio/putc.rdoc
new file mode 100644
index 00000000..9d73254f
--- /dev/null
+++ b/doc/stringio/putc.rdoc
@@ -0,0 +1,72 @@
+Replaces one or more bytes at position +pos+
+with bytes of the given argument;
+returns the argument.
+
+\StringIO object for 1-byte characters.
+
+  strio = StringIO.new('foo')
+
+With 1-byte argument, replaces one byte:
+
+  strio.putc('b')
+  strio.string    # => "boo"
+  strio.putc('a') # => "a"
+  strio.string    # => "bao"
+  strio.putc('r') # => "r"
+  strio.string    # => "bar"
+  strio.putc('n') # => "n"
+  strio.string    # => "barn"
+
+Fills with null characters if necessary:
+
+  strio.pos = 6
+  strio.putc('x') # => "x"
+  strio.string    # => "barn\u0000\u0000x"
+
+With integer argument, replaces one byte with the low-order byte of the integer:
+
+  strio = StringIO.new('foo')
+  strio.putc(70)
+  strio.string # => "Foo"
+  strio.putc(79)
+  strio.string # => "FOo"
+  strio.putc(79 + 1024)
+  strio.string # => "FOO"
+
+\StringIO object for Multi-byte characters:
+
+  greek = 'αβγδε' # Five 2-byte characters.
+  strio = StringIO.new(greek)
+  strio.string# => "αβγδε"
+  strio.string.b        # => "\xCE\xB1\xCE\xB2\xCE\xB3\xCE\xB4\xCE\xB5"
+  strio.string.bytesize # => 10
+  strio.string.chars    # => ["α", "β", "γ", "δ", "ε"]
+  strio.string.size     # => 5
+
+With 1-byte argument, replaces one byte of the string:
+
+  strio.putc(' ')       # 1-byte ascii space.
+  strio.string          # => " \xB1βγδε"
+  strio.string.b        # => " \xB1\xCE\xB2\xCE\xB3\xCE\xB4\xCE\xB5"
+  strio.string.bytesize # => 10
+  strio.string.chars    # => [" ", "\xB1", "β", "γ", "δ", "ε"]
+  strio.string.size     # => 6
+
+  strio.putc(' ')
+  strio.string          # => "  βγδε"
+  strio.string.b        # => "  \xCE\xB2\xCE\xB3\xCE\xB4\xCE\xB5"
+  strio.string.bytesize # => 10
+  strio.string.chars    # => [" ", " ", "β", "γ", "δ", "ε"]
+  strio.string.size     # => 6
+
+With 2-byte argument, replaces two bytes of the string:
+
+  strio.rewind
+  strio.putc('α')
+  strio.string          # => "αβγδε"
+  strio.string.b        # => "\xCE\xB1\xCE\xB2\xCE\xB3\xCE\xB4\xCE\xB5"
+  strio.string.bytesize # => 10
+  strio.string.chars    # => ["α", "β", "γ", "δ", "ε"]
+  strio.string.size     # => 5
+
+Related: #getc, #ungetc.
diff --git a/ext/stringio/stringio.c b/ext/stringio/stringio.c
index b60827fa..fee09adb 100644
--- a/ext/stringio/stringio.c
+++ b/ext/stringio/stringio.c
@@ -1615,9 +1615,10 @@ strio_write(VALUE self, VALUE str)
 
 /*
  * call-seq:
- *   strio.putc(obj)    -> obj
+ *   putc(object) -> object
+ *
+ * :include: stringio/putc.rdoc
  *
- * See IO#putc.
  */
 static VALUE
 strio_putc(VALUE self, VALUE ch)

From f31c31733945874e50dc171ea5e8309181501dc3 Mon Sep 17 00:00:00 2001
From: BurdetteLamar <burdettelamar@yahoo.com>
Date: Sun, 7 Dec 2025 20:41:23 +0000
Subject: [PATCH 2/2] More on pos

---
 doc/stringio/putc.rdoc | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/doc/stringio/putc.rdoc b/doc/stringio/putc.rdoc
index 9d73254f..4636ffa0 100644
--- a/doc/stringio/putc.rdoc
+++ b/doc/stringio/putc.rdoc
@@ -1,27 +1,34 @@
 Replaces one or more bytes at position +pos+
 with bytes of the given argument;
+advances the position by the count of bytes written;
 returns the argument.
 
 \StringIO object for 1-byte characters.
 
   strio = StringIO.new('foo')
+  strio.pos # => 0
 
 With 1-byte argument, replaces one byte:
 
   strio.putc('b')
   strio.string    # => "boo"
+  strio.pos       # => 1
   strio.putc('a') # => "a"
   strio.string    # => "bao"
+  strio.pos       # => 2
   strio.putc('r') # => "r"
   strio.string    # => "bar"
+  strio.pos       # => 3
   strio.putc('n') # => "n"
   strio.string    # => "barn"
+  strio.pos       # => 4
 
 Fills with null characters if necessary:
 
   strio.pos = 6
   strio.putc('x') # => "x"
   strio.string    # => "barn\u0000\u0000x"
+  strio.pos       # => 7
 
 With integer argument, replaces one byte with the low-order byte of the integer:
 
@@ -46,6 +53,7 @@ With integer argument, replaces one byte with the low-order byte of the integer:
 With 1-byte argument, replaces one byte of the string:
 
   strio.putc(' ')       # 1-byte ascii space.
+  strio.pos             # => 1
   strio.string          # => " \xB1βγδε"
   strio.string.b        # => " \xB1\xCE\xB2\xCE\xB3\xCE\xB4\xCE\xB5"
   strio.string.bytesize # => 10
@@ -53,6 +61,7 @@ With 1-byte argument, replaces one byte of the string:
   strio.string.size     # => 6
 
   strio.putc(' ')
+  strio.pos             # => 2
   strio.string          # => "  βγδε"
   strio.string.b        # => "  \xCE\xB2\xCE\xB3\xCE\xB4\xCE\xB5"
   strio.string.bytesize # => 10
@@ -63,6 +72,7 @@ With 2-byte argument, replaces two bytes of the string:
 
   strio.rewind
   strio.putc('α')
+  strio.pos             # => 2
   strio.string          # => "αβγδε"
   strio.string.b        # => "\xCE\xB1\xCE\xB2\xCE\xB3\xCE\xB4\xCE\xB5"
   strio.string.bytesize # => 10