diff options
author | Robert Griesemer <gri@golang.org> | 2013-10-16 16:16:54 -0700 |
---|---|---|
committer | Robert Griesemer <gri@golang.org> | 2013-10-16 16:16:54 -0700 |
commit | 15da997c7eab0ce461e6daa8cdb8e8a495dde074 (patch) | |
tree | a672900c50954b879e1d4503554f2f97afa06ef2 | |
parent | 37db8804691f0a5e618cbc041909895c9709263c (diff) | |
download | go-15da997c7eab0ce461e6daa8cdb8e8a495dde074.tar.gz go-15da997c7eab0ce461e6daa8cdb8e8a495dde074.zip |
spec: clarify re-use of underlying arrays in slice operations
Please note the slight rewording for append: The spec now
requires that append reuses the underlying array if it is
sufficiently large. Per majority sentiment.
This is technically a language change but the current
implementation always worked this way.
Fixes #5818.
Fixes #5180.
R=rsc, iant, r, ken, minux.ma, dan.kortschak, rogpeppe, go.peter.90
CC=golang-dev
https://golang.org/cl/14419054
-rw-r--r-- | doc/go_spec.html | 35 |
1 files changed, 14 insertions, 21 deletions
diff --git a/doc/go_spec.html b/doc/go_spec.html index 4ed5f4d175..87ee7459ff 100644 --- a/doc/go_spec.html +++ b/doc/go_spec.html @@ -1,6 +1,6 @@ <!--{ "Title": "The Go Programming Language Specification", - "Subtitle": "Version of Oct 7, 2013", + "Subtitle": "Version of Oct 16, 2013", "Path": "/ref/spec" }--> @@ -839,7 +839,7 @@ multi-dimensional types. <h3 id="Slice_types">Slice types</h3> <p> -A slice is a descriptor for a contiguous segment of an array and +A slice is a descriptor for a contiguous segment of an <i>underlying array</i> and provides access to a numbered sequence of elements from that array. A slice type denotes the set of all slices of arrays of its element type. The value of an uninitialized slice is <code>nil</code>. @@ -879,26 +879,18 @@ A new, initialized slice value for a given element type <code>T</code> is made using the built-in function <a href="#Making_slices_maps_and_channels"><code>make</code></a>, which takes a slice type -and parameters specifying the length and optionally the capacity: +and parameters specifying the length and optionally the capacity. +A slice created with <code>make</code> always allocates a new, hidden array +to which the returned slice value refers. That is, executing </p> <pre> -make([]T, length) make([]T, length, capacity) </pre> <p> -A call to <code>make</code> allocates a new, hidden array to which the returned -slice value refers. That is, executing -</p> - -<pre> -make([]T, length, capacity) -</pre> - -<p> -produces the same slice as allocating an array and slicing it, so these two examples -result in the same slice: +produces the same slice as allocating an array and <a href="#Slice_expressions">slicing</a> +it, so these two expressions are equivalent: </p> <pre> @@ -910,8 +902,8 @@ new([100]int)[0:50] Like arrays, slices are always one-dimensional but may be composed to construct higher-dimensional objects. With arrays of arrays, the inner arrays are, by construction, always the same length; -however with slices of slices (or arrays of slices), the lengths may vary dynamically. -Moreover, the inner slices must be allocated individually (with <code>make</code>). +however with slices of slices (or arrays of slices), the inner lengths may vary dynamically. +Moreover, the inner slices must be initialized individually. </p> <h3 id="Struct_types">Struct types</h3> @@ -2707,7 +2699,8 @@ and the result of the slice operation is a slice with the same element type as t <p> If the sliced operand of a valid slice expression is a <code>nil</code> slice, the result -is a <code>nil</code> slice. +is a <code>nil</code> slice. Otherwise, the result shares its underlying array with the +operand. </p> <h4>Full slice expressions</h4> @@ -5361,9 +5354,9 @@ append(s S, x ...T) S // T is the element type of S <p> If the capacity of <code>s</code> is not large enough to fit the additional -values, <code>append</code> allocates a new, sufficiently large slice that fits -both the existing slice elements and the additional values. Thus, the returned -slice may refer to a different underlying array. +values, <code>append</code> allocates a new, sufficiently large underlying +array that fits both the existing slice elements and the additional values. +Otherwise, <code>append</code> re-uses the underlying array. </p> <pre> |