1 files changed, 47 insertions, 0 deletions
diff --git a/doc/string/encode.rdoc b/doc/string/encode.rdoc
new file mode 100644
index 0000000000..65872fdfd4
--- /dev/null
+++ b/doc/string/encode.rdoc
@@ -0,0 +1,47 @@
+Returns a copy of +self+ transcoded as determined by +dst_encoding+.
+By default, raises an exception if +self+
+contains an invalid byte or a character not defined in +dst_encoding+;
+that behavior may be modified by encoding options; see below.
+
+With no arguments:
+
+- Uses the same encoding if <tt>Encoding.default_internal</tt> is +nil+
+  (the default):
+
+    Encoding.default_internal # => nil
+    s = "Ruby\x99".force_encoding('Windows-1252')
+    s.encoding                # => #<Encoding:Windows-1252>
+    s.bytes                   # => [82, 117, 98, 121, 153]
+    t = s.encode              # => "Ruby\x99"
+    t.encoding                # => #<Encoding:Windows-1252>
+    t.bytes                   # => [82, 117, 98, 121, 226, 132, 162]
+
+- Otherwise, uses the encoding <tt>Encoding.default_internal</tt>:
+
+    Encoding.default_internal = 'UTF-8'
+    t = s.encode              # => "Ruby™"
+    t.encoding                # => #<Encoding:UTF-8>
+
+With only argument +dst_encoding+ given, uses that encoding:
+
+  s = "Ruby\x99".force_encoding('Windows-1252')
+  s.encoding            # => #<Encoding:Windows-1252>
+  t = s.encode('UTF-8') # => "Ruby™"
+  t.encoding            # => #<Encoding:UTF-8>
+
+With arguments +dst_encoding+ and +src_encoding+ given,
+interprets +self+ using +src_encoding+, encodes the new string using +dst_encoding+:
+
+  s = "Ruby\x99"
+  t = s.encode('UTF-8', 'Windows-1252') # => "Ruby™"
+  t.encoding                            # => #<Encoding:UTF-8>
+
+Optional keyword arguments +enc_opts+ specify encoding options;
+see {Encoding Options}[rdoc-ref:encodings.rdoc@Encoding+Options].
+
+Please note that, unless <code>invalid: :replace</code> option is
+given, conversion from an encoding +enc+ to the same encoding +enc+
+(independent of whether +enc+ is given explicitly or implicitly) is a
+no-op, i.e. the string is simply copied without any changes, and no
+exceptions are raised, even if there are invalid bytes.
+