unicode/utf8: document the handling of runes out of range in EncodeRune

Document the way EncodeRune currently handles runes which are
out of range.  Also add an example showing that behaviour.

Change-Id: I0f8e7645ae053474ec319085a2bb6d7f73bc137c
Reviewed-on: https://go-review.googlesource.com/c/go/+/255998
Reviewed-by: Rob Pike <r@golang.org>
Reviewed-by: Giovanni Bajo <rasky@develer.com>
Trust: Giovanni Bajo <rasky@develer.com>
Run-TryBot: Giovanni Bajo <rasky@develer.com>
TryBot-Result: Go Bot <gobot@golang.org>

diff --git a/src/unicode/utf8/example_test.go b/src/unicode/utf8/example_test.go
index 7b3e7ac742570cab11d311d5dbc958673e43ab6c..5cd931d24279ff27eb4a1343dc9a306998f32020 100644 (file)
--- a/src/unicode/utf8/example_test.go
+++ b/src/unicode/utf8/example_test.go
@@ -107,6 +107,26 @@ func ExampleEncodeRune() {
        // 3
 }
 
+func ExampleEncodeRune_outOfRange() {
+       runes := []rune{
+               // Less than 0, out of range.
+               -1,
+               // Greater than 0x10FFFF, out of range.
+               0x110000,
+               // The Unicode replacement character.
+               utf8.RuneError,
+       }
+       for i, c := range runes {
+               buf := make([]byte, 3)
+               size := utf8.EncodeRune(buf, c)
+               fmt.Printf("%d: %d %[2]s %d\n", i, buf, size)
+       }
+       // Output:
+       // 0: [239 191 189] � 3
+       // 1: [239 191 189] � 3
+       // 2: [239 191 189] � 3
+}
+
 func ExampleFullRune() {
        buf := []byte{228, 184, 150} // 世
        fmt.Println(utf8.FullRune(buf))

diff --git a/src/unicode/utf8/utf8.go b/src/unicode/utf8/utf8.go
index ef0d74096029224833c51a3b9c3ca5d0371326b7..557e8a7770c7dd9fc70e4e60baf18fd093f19e35 100644 (file)
--- a/src/unicode/utf8/utf8.go
+++ b/src/unicode/utf8/utf8.go
@@ -337,6 +337,7 @@ func RuneLen(r rune) int {
 }
 
 // EncodeRune writes into p (which must be large enough) the UTF-8 encoding of the rune.
+// If the rune is out of range, it writes the encoding of RuneError.
 // It returns the number of bytes written.
 func EncodeRune(p []byte, r rune) int {
        // Negative values are erroneous. Making it unsigned addresses the problem.