Documents encoding

And all new options included in March, including `replacement`. Closes #1233

doc/Type/Str.pod6

@@ -135,6 +135,21 @@ are going to be replaced in the case they are not available in the current
 encoding, while C<$strict> indicates whether unmapped codepoints will still
 decode; for instance, codepoint 129 which does not exist in C<windows-1252>.
 
+    my $str = "Þor is mighty";
+    say $str.encode("ascii", :replacement( 'Th') ).decode("ascii");
+    # OUTPUT: «Thor is mighty␤»
+
+In this case, any unknown character is going to be substituted by C<Th>. We know
+in advance that the character that is not known in the C<ascii> encoding is
+C<Þ>, so we substitute it by its latin equivalent, C<Th>. In the absence of any
+replacement set of characters, C<:replacement> is understood as a C<Bool>:
+
+=for code :preamble<my $str = "Þor is mighty";>
+say $str.encode("ascii", :replacement).decode("ascii"); # OUTPUT: «?or is mighty␤»
+
+If C<:replacement> is not set or assigned a value, the error C<Error encoding
+ASCII string: could not encode codepoint 222> will be issued.
+
 =head2 routine index
 
     multi sub    index(Cool $s, Str:D $needle, Cool $startpos = 0 --> Int)