ruby · BurdetteLamar · Jul 14, 2025 · Jul 16, 2025 · Jul 18, 2025 · peterzhu2118
diff --git a/doc/string.rb b/doc/string.rb
@@ -458,8 +458,7 @@
 #
 # _Substitution_
 #
-# - #dump: Returns a copy of +self+ with all non-printing characters replaced by \xHH notation
-#   and all special characters escaped.
+# - #dump: Returns a printable version of +self+, enclosed in double-quotes.
 # - #undump: Returns a copy of +self+ with all <tt>\xNN</tt> notations replaced by <tt>\uNNNN</tt> notations
 #   and all escaped characters unescaped.
 # - #sub: Returns a copy of +self+ with the first substring matching a given pattern

diff --git a/doc/string/dump.rdoc b/doc/string/dump.rdoc
@@ -0,0 +1,45 @@
+Returns a printable version of +self+, enclosed in double-quotes:
+
+  'hello'.dump     # => "\"hello\""
+  'тест'.dump      # => "\"\\u0442\\u0435\\u0441\\u0442\""
+  'こんにちは'.dump # => "\"\\u3053\\u3093\\u306B\\u3061\\u306F\""
+
+The format of the result depends on the encoding of the string:
+
+  s = 'hello'
+  s.encoding                # => #<Encoding:UTF-8>
+  s.dump                    # => "\"hello\""
+  s.encode('utf-16').dump   # => "\"\\xFE\\xFF\\x00h\\x00e\\x00l\\x00l\\x00o\".dup.force_encoding(\"UTF-16\")"
+  s.encode('utf-16le').dump # => "\"h\\x00e\\x00l\\x00l\\x00o\\x00\".dup.force_encoding(\"UTF-16LE\")"
+
+  s = 'тест'
+  s.encoding                # => #<Encoding:UTF-8>
+  s.dump                    # => "\"\\u0442\\u0435\\u0441\\u0442\""
+  s.encode('utf-16').dump   # => "\"\\xFE\\xFF\\x04B\\x045\\x04A\\x04B\".dup.force_encoding(\"UTF-16\")"
+  s.encode('utf-16le').dump # => "\"B\\x045\\x04A\\x04B\\x04\".dup.force_encoding(\"UTF-16LE\")"
+
+  s = 'こんにちは'
+  s.encoding                # => #<Encoding:UTF-8>
+  s.dump                    # => "\"\\u3053\\u3093\\u306B\\u3061\\u306F\""
+  s.encode('utf-16').dump   # => "\"\\xFE\\xFF0S0\\x930k0a0o\".dup.force_encoding(\"UTF-16\")"
+  s.encode('utf-16le').dump # => "\"S0\\x930k0a0o0\".dup.force_encoding(\"UTF-16LE\")"
+
+Certain special characters are rendered with escapes:
+
+  '"'.dump  # => "\"\\\"\""
+  '\\'.dump # => "\"\\\\\""
+
+Non-printing characters are rendered with escapes:
+
+  s = ''
+  s << 7   # Alarm (bell).
+  s << 8   # Back space.
+  s << 9   # Horizontal tab.
+  s << 10  # Line feed.
+  s << 11  # Vertical tab.
+  s << 12  # Form feed.
+  s << 13  # Carriage return.
+  s        # => "\a\b\t\n\v\f\r"
+  s.dump   # => "\"\\a\\b\\t\\n\\v\\f\\r\""
+
+Related: see {Converting to New String}[rdoc-ref:String@Converting+to+New+String].
diff --git a/string.c b/string.c
@@ -7412,16 +7412,9 @@ rb_str_inspect(VALUE str)
 
 /*
  *  call-seq:
- *    dump -> string
+ *    dump -> new_string
  *
- *  Returns a printable version of +self+, enclosed in double-quotes,
- *  with special characters escaped, and with non-printing characters
- *  replaced by hexadecimal notation:
- *
- *    "hello \n ''".dump    # => "\"hello \\n ''\""
- *    "\f\x00\xff\\\"".dump # => "\"\\f\\x00\\xFF\\\\\\\"\""
- *
- *  Related: String#undump (inverse of String#dump).
+ *  :include: doc/string/dump.rdoc
  *
  */