From 0dffda13834545317569052a9de7dfbf27b62c5d Mon Sep 17 00:00:00 2001
From: Robert Griesemer <gri@golang.org>
Date: Mon, 13 Jun 2022 18:44:44 -0700
Subject: [PATCH] spec: clarify "slice of bytes" and "slice of runes" through
 examples

The spec section on conversions uses the terms "slice of bytes" and
"slice of runes". While not obviously clear, what is meant are slice
types whose element types are byte or rune types; specifically the
underlying types of the slices' element types must be byte or rune.

Some of this was evident from the examples, but not all of it. Made
this clearer by adding more examples illustrating various permitted
conversions.

Note that the 1.17 compiler did not accept the following conversions:

        string([]myByte{...})
        string([]myRune{...})
        myString([]myByte{...})
        myString([]myRune{...})

(where myByte, myRune, and myString have underlying types of byte,
rune, and string respectively) - it reported an internal error.
But it did accept the inverse conversions:

        []myByte("...")
        []myRune("...")
        []myByte(myString("..."))
        []myRune(myString("..."))

The 1.18 compiler made those conversions symmetric and they are now
permitted in both directions.

The extra examples reflect this reality.

Fixes #23814.

Change-Id: I5a1c200b45ddd0e8c0dc0d11da3a6c39cb2dc848
Reviewed-on: https://go-review.googlesource.com/c/go/+/412094
Reviewed-by: Robert Griesemer <gri@google.com>
Reviewed-by: Ian Lance Taylor <iant@google.com>
---
 doc/go_spec.html | 43 +++++++++++++++++++++++++++++--------------
 1 file changed, 29 insertions(+), 14 deletions(-)

diff --git a/doc/go_spec.html b/doc/go_spec.html
index b5f6c5fd6571c4..cc77fd12a9470d 100644
--- a/doc/go_spec.html
+++ b/doc/go_spec.html
@@ -1,6 +1,6 @@
 <!--{
 	"Title": "The Go Programming Language Specification",
-	"Subtitle": "Version of June 13, 2022",
+	"Subtitle": "Version of June 14, 2022",
 	"Path": "/ref/spec"
 }-->
 
@@ -5245,7 +5245,7 @@ <h3 id="Conversions">Conversions</h3>
 float64(-1e-1000)        // 0.0 of type float64
 string('x')              // "x" of type string
 string(0x266c)           // "♬" of type string
-MyString("foo" + "bar")  // "foobar" of type MyString
+myString("foo" + "bar")  // "foobar" of type myString
 string([]byte{'a'})      // not a constant: []byte{'a'} is not a constant
 (*int)(nil)              // not a constant: nil is not a constant, *int is not a boolean, numeric, or string type
 int(1.2)                 // illegal: 1.2 cannot be represented as an int
@@ -5428,8 +5428,9 @@ <h4 id="Conversions_to_and_from_a_string_type">Conversions to and from a string
 string('a')       // "a"
 string(-1)        // "\ufffd" == "\xef\xbf\xbd"
 string(0xf8)      // "\u00f8" == "ø" == "\xc3\xb8"
-type MyString string
-MyString(0x65e5)  // "\u65e5" == "日" == "\xe6\x97\xa5"
+
+type myString string
+myString(0x65e5)  // "\u65e5" == "日" == "\xe6\x97\xa5"
 </pre>
 </li>
 
@@ -5442,8 +5443,12 @@ <h4 id="Conversions_to_and_from_a_string_type">Conversions to and from a string
 string([]byte{})                                     // ""
 string([]byte(nil))                                  // ""
 
-type MyBytes []byte
-string(MyBytes{'h', 'e', 'l', 'l', '\xc3', '\xb8'})  // "hellø"
+type bytes []byte
+string(bytes{'h', 'e', 'l', 'l', '\xc3', '\xb8'})    // "hellø"
+
+type myByte byte
+string([]myByte{'w', 'o', 'r', 'l', 'd', '!'})       // "world!"
+myString([]myByte{'\xf0', '\x9f', '\x8c', '\x8d'})   // "🌍"
 </pre>
 </li>
 
@@ -5457,8 +5462,12 @@ <h4 id="Conversions_to_and_from_a_string_type">Conversions to and from a string
 string([]rune{})                         // ""
 string([]rune(nil))                      // ""
 
-type MyRunes []rune
-string(MyRunes{0x767d, 0x9d6c, 0x7fd4})  // "\u767d\u9d6c\u7fd4" == "白鵬翔"
+type runes []rune
+string(runes{0x767d, 0x9d6c, 0x7fd4})    // "\u767d\u9d6c\u7fd4" == "白鵬翔"
+
+type myRune rune
+string([]myRune{0x266b, 0x266c})         // "\u266b\u266c" == "♫♬"
+myString([]myRune{0x1F30E})              // "\U0001f30e" == "🌎"
 </pre>
 </li>
 
@@ -5467,10 +5476,13 @@ <h4 id="Conversions_to_and_from_a_string_type">Conversions to and from a string
 yields a slice whose successive elements are the bytes of the string.
 
 <pre>
-[]byte("hellø")   // []byte{'h', 'e', 'l', 'l', '\xc3', '\xb8'}
-[]byte("")        // []byte{}
+[]byte("hellø")             // []byte{'h', 'e', 'l', 'l', '\xc3', '\xb8'}
+[]byte("")                  // []byte{}
 
-MyBytes("hellø")  // []byte{'h', 'e', 'l', 'l', '\xc3', '\xb8'}
+bytes("hellø")              // []byte{'h', 'e', 'l', 'l', '\xc3', '\xb8'}
+
+[]myByte("world!")          // []myByte{'w', 'o', 'r', 'l', 'd', '!'}
+[]myByte(myString("🌏"))    // []myByte{'\xf0', '\x9f', '\x8c', '\x8f'}
 </pre>
 </li>
 
@@ -5479,10 +5491,13 @@ <h4 id="Conversions_to_and_from_a_string_type">Conversions to and from a string
 yields a slice containing the individual Unicode code points of the string.
 
 <pre>
-[]rune(MyString("白鵬翔"))  // []rune{0x767d, 0x9d6c, 0x7fd4}
-[]rune("")                 // []rune{}
+[]rune(myString("白鵬翔"))   // []rune{0x767d, 0x9d6c, 0x7fd4}
+[]rune("")                  // []rune{}
+
+runes("白鵬翔")              // []rune{0x767d, 0x9d6c, 0x7fd4}
 
-MyRunes("白鵬翔")           // []rune{0x767d, 0x9d6c, 0x7fd4}
+[]myRune("♫♬")              // []myRune{0x266b, 0x266c}
+[]myRune(myString("🌐"))    // []myRune{0x1f310}
 </pre>
 </li>
 </ol>