Make creating UTF-8 surrogates a punishable act.

p4raw-id: //depot/perl@13707

2 files changed, 14 insertions, 0 deletions

diff --git a/pod/perldiag.pod b/pod/perldiag.pod
index 34be2580c0..c10d56c9b1 100644
--- a/pod/perldiag.pod
+++ b/pod/perldiag.pod
@@ -3998,6 +3998,14 @@ C<< @foo->[23] >> or C<< @$ref->[99] >>.  Versions of perl <= 5.6.1 used to
 allow this syntax, but shouldn't have. It is now deprecated, and will be
 removed in a future version.
 
+=item UTF-16 surrogate %s
+
+(F) You tried to generate half of an UTF-16 surrogate by requesting
+a Unicode character between the code points 0xD800 and 0xDFFF (inclusive).
+That range is reserved exclusively for the use of UTF-16 encoding
+(by having two 16-bit UCS-2 characters); but Perl encodes its characters
+in UTF-8, so what you got is a very illegal character.
+
 =item Value of %s can be "0"; test with defined()
 
 (W misc) In a conditional expression, you used <HANDLE>, <*> (glob),
diff --git a/pod/perlunicode.pod b/pod/perlunicode.pod
index 4102fc42a6..103b33b69a 100644
--- a/pod/perlunicode.pod
+++ b/pod/perlunicode.pod
@@ -740,6 +740,12 @@ and the decoding is
 
 	$uni = 0x10000 + ($hi - 0xD8000) * 0x400 + ($lo - 0xDC00);
 
+If you try to generate surrogates (for example by using chr()), you
+will get an error because firstly a surrogate on its own is
+meaningless, and secondly because Perl encodes its Unicode characters
+in UTF-8 (not 16-bit numbers), which makes the encoded character doubly
+illegal.
+
 Because of the 16-bitness, UTF-16 is byteorder dependent.  UTF-16
 itself can be used for in-memory computations, but if storage or
 transfer is required, either UTF-16BE (Big Endian) or UTF-16LE