doc: document Go 1.17 language changes

Fixes #46020.

Change-Id: Iadf9a0ac4a8863e17155d6ba1af2cc497634a634
Reviewed-on: https://go-review.googlesource.com/c/go/+/325870
Trust: Matthew Dempsky <mdempsky@google.com>
Reviewed-by: Ian Lance Taylor <iant@golang.org>
Reviewed-by: Dmitri Shuralyov <dmitshur@golang.org>

diff --git a/doc/go1.17.html b/doc/go1.17.html
index 7438d894fe3feacf50e116d4a17abafd94640c77..c1978ff1c1528f1944d72539cd1fc63c02bd2d6e 100644 (file)
--- a/doc/go1.17.html
+++ b/doc/go1.17.html
@@ -25,12 +25,46 @@ Do not send CLs removing the interior tags from such phrases.
 
 <h2 id="language">Changes to the language</h2>
 
-<p><!-- CL 216424 -->
-  TODO: <a href="https://golang.org/cl/216424">https://golang.org/cl/216424</a>: allow conversion from slice to array ptr
-</p>
+<p>
+  Go 1.17 includes three small enhancements to the language.
+</p>
+
+<ul>
+  <li><!-- CL 216424; issue 395 -->
+    <a href="/ref/spec#Conversions_from_slice_to_array_pointer">Conversions
+    from slice to array pointer</a>: An expression <code>s</code> of
+    type <code>[]T</code> may now be converted to array pointer type
+    <code>*[N]T</code>. If <code>a</code> is the result of such a
+    conversion, then corresponding indices that are in range refer to
+    the same underlying elements: <code>&amp;a[i] == &amp;s[i]</code>
+    for <code>0 &lt;= i &lt; N</code>. The conversion panics if
+    <code>len(s)</code> is less than <code>N</code>.
+  </li>
+
+  <li><!-- CL 312212; issue 40481 -->
+    <a href="/pkg/unsafe#Add"><code>unsafe.Add</code></a>:
+    <code>unsafe.Add(ptr, len)</code> adds <code>len</code>
+    to <code>ptr</code> and returns the updated pointer
+    <code>unsafe.Pointer(uintptr(ptr) + uintptr(len))</code>.
+  </li>
+
+  <li><!-- CL 312212; issue 19367 -->
+    <a href="/pkg/unsafe#Slice"><code>unsafe.Slice</code></a>:
+    For expression <code>ptr</code> of type <code>*T</code>,
+    <code>unsafe.Slice(ptr, len)</code> returns a slice of
+    type <code>[]T</code> whose underlying array starts
+    at <code>ptr</code> and whose length and capacity
+    are <code>len</code>.
+  </li>
+</ul>
 
-<p><!-- CL 312212 -->
-  TODO: <a href="https://golang.org/cl/312212">https://golang.org/cl/312212</a>: add unsafe.Add and unsafe.Slice
+<p>
+  These enhancements were added to simplify writing code that conforms
+  to <code>unsafe.Pointer</code>'s <a href="/pkg/unsafe/#Pointer">safety
+  rules</a>, but the rules remain unchanged. In particular, existing
+  programs that correctly use <code>unsafe.Pointer</code> remain
+  valid, and new programs must still follow the rules when
+  using <code>unsafe.Add</code> or <code>unsafe.Slice</code>.
 </p>
 
 <h2 id="ports">Ports</h2>