[DOC] Doc for StringIO#putc (#196)

Previous doc merely linked to `IO#putc`. The new doc stays local,
provides examples using `StringIO` objects.

Author: BurdetteLamar

doc/stringio/putc.rdoc

@@ -0,0 +1,82 @@
+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:
+
+  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.pos             # => 1
+  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.pos             # => 2
+  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.pos             # => 2
+  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.

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)