code review 2627043: go spec: append built-in

doc/go_spec.html

 <!-- title The Go Programming Language Specification -->
 <!-- subtitle Version of Oct 25, 2010 -->
 
 <!--
 TODO
 [ ] need language about function/method calls and parameter passing rules
 [ ] last paragraph of #Assignments (constant promotion) should be elsewhere
     and mention assignment to empty interface.
 [ ] need to say something about "scope" of selectors?
 [ ] clarify what a field name is in struct declarations
@@ skipping 1474 matching lines @@
 Architecture-specific convenience types:
         complex float int uint uintptr
 
 Constants:
         true false iota
 
 Zero value:
         nil
 
 Functions:
-        cap close closed cmplx copy imag len make
-        new panic print println real recover
+        append cap close closed cmplx copy imag len
+        make new panic print println real recover
 </pre>
 
 
 <h3 id="Exported_identifiers">Exported identifiers</h3>
 
 <p>
 An identifier may be <i>exported</i> to permit access to it from another package
 using a <a href="#Qualified_identifiers">qualified identifier</a>. An identifier
 is exported if both:
 </p>
@@ skipping 3013 matching lines @@
 </p>
 
 <pre>
 s := make([]int, 10, 100)        // slice with len(s) == 10, cap(s) == 100
 s := make([]int, 10)             // slice with len(s) == cap(s) == 10
 c := make(chan int, 10)          // channel with a buffer size of 10
 m := make(map[string] int, 100)  // map with initial space for 100 elements
 </pre>
 
 
-<h3 id="Copying_slices">Copying slices</h3>
+<h3 id="Appending_and_copying_slices">Appending to and copying slices</h3>
 
 <p>
-The built-in function <code>copy</code> copies slice elements from
+Two built-in functions assist in common slice operations.
+</p>
+
+<p>
+The function <code>append</code> appends zero or more values <code>x</code>
+to a slice <code>s</code> and returns the resulting slice. Each value must be
+<a href="#Assignability">assignable</a> to the slice's element type.
+</p>
+
+<pre class="grammar">
+append(s []T, x ...T) []T
+</pre>
+
+<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.·
+</p>
+
+<pre>
+s0 := []int{0, 0}
+s1 := append(s0, 2)        // append a single element     s1 == []int{0, 0, 2}
+s2 := append(s1, 3, 5, 7)  // append multiple elements    s2 == []int{0, 0, 2, 3, 5, 7}
+s3 := append(s2, s0...)    // append a slice              s3 == []int{0, 0, 2, 3, 5, 7, 0, 0}
+</pre>
+
+<p>
+The function <code>copy</code> copies slice elements from
 a source <code>src</code> to a destination <code>dst</code> and returns the
 number of elements copied. Source and destination may overlap.
 Both arguments must have <a href="#Type_identity">identical</a> element type <code>T</code> and must be
 <a href="#Assignability">assignable</a> to a slice of type <code>[]T</code>.
 The number of arguments copied is the minimum of
 <code>len(src)</code> and <code>len(dst)</code>.
 As a special case, <code>copy</code> also accepts a destination argument assignable
 to type <code>[]byte</code> with a source argument of a string type.
 This form copies the bytes from the string into the byte slice.
 </p>
@@ skipping 652 matching lines @@
    <code>unsafe.Alignof(x[0])</code>, but at least 1.
 </li>
 </ol>
 
 <h2 id="Implementation_differences"><span class="alert">Implementation differences - TODO</span></h2>
 <ul>
         <li><span class="alert">Implementation does not honor the restriction on goto statements and targets (no intervening declarations).</span></li>
         <li><span class="alert">Gccgo: Method expressions are partially implemented.</span></li>
         <li><span class="alert">Gccgo: allows only one init() function per source file.</span></li>
 </ul>