[Bug #20566] Mention out-of-range argument cases in `String#<<`

Also [Bug #18973].

2 files changed, 18 insertions, 0 deletions

diff --git a/doc/format_specifications.rdoc b/doc/format_specifications.rdoc
index 1111575e74..bdfdc24953 100644
--- a/doc/format_specifications.rdoc
+++ b/doc/format_specifications.rdoc
@@ -233,6 +233,8 @@ Format +argument+ as a single character:
   sprintf('%c', 'A') # => "A"
   sprintf('%c', 65)  # => "A"
 
+This behaves like String#<<, except for raising ArgumentError instead of RangeError.
+
 === Specifier +d+
 
 Format +argument+ as a decimal integer:
diff --git a/string.c b/string.c
index acad662e4d..5b8b7cd71c 100644
--- a/string.c
+++ b/string.c
@@ -3595,6 +3595,22 @@ rb_str_concat_multi(int argc, VALUE *argv, VALUE str)
  *    s = 'foo'
  *    s << 33 # => "foo!"
  *
+ *  If that codepoint is not representable in the encoding of
+ *  _string_, RangeError is raised.
+ *
+ *    s = 'foo'
+ *    s.encoding              # => <Encoding:UTF-8>
+ *    s << 0x00110000         # 1114112 out of char range (RangeError)
+ *    s = 'foo'.encode('EUC-JP')
+ *    s << 0x00800080         # invalid codepoint 0x800080 in EUC-JP (RangeError)
+ *
+ *  If the encoding is US-ASCII and the codepoint is 0..0xff, _string_
+ *  is automatically promoted to ASCII-8BIT.
+ *
+ *    s = 'foo'.encode('US-ASCII')
+ *    s << 0xff
+ *    s.encoding              # => #<Encoding:BINARY (ASCII-8BIT)>
+ *
  *  Related: String#concat, which takes multiple arguments.
  */
 VALUE