Add slice example & rationale; mention assumeSafeAppend

Author: ntrel

spec/arrays.dd

@@ -763,14 +763,32 @@ $(H3 $(LNAME2 capacity-reserve, `capacity` and `reserve`))
         GC-allocated memory, the capacity will be zero.
         The spare capacity for an array *a* is `a.capacity - a.length`.)
 
+        $(P By default, `capacity` will be zero if an element has been stored after the slice.)
+
+        $(SPEC_RUNNABLE_EXAMPLE_RUN
+        ---
+        int[] a;
+        assert(a.capacity == 0);
+        a.length = 3; // may allocate spare capacity too
+        assert(a.capacity >= 3);
+        auto b = a[1..3];
+        assert(b.capacity >= 2); // either a or b can append into any spare capacity
+        b = a[0..2];
+        assert(b.capacity == 0);
+        ---
+        )
+
+        $(RATIONALE This behaviour helps prevent accidental overwriting of
+        elements in another slice. It is also necessary to protect immutable
+        elements from being overwritten.)
+
         $(P The $(D reserve)
         function expands an array's capacity for use by the
         $(RELATIVE_LINK2 array-appending, append operator) or `.length` assignment.)
 
 $(SPEC_RUNNABLE_EXAMPLE_RUN
 ---------
 int[] array;
-assert(array.capacity == 0);
 const size_t cap = array.reserve(10); // request
 assert(cap >= 10); // allocated may be more than request
 assert(array.ptr != null);
@@ -791,21 +809,24 @@ assert(copy.ptr != array.ptr);
         is the address of `array[0]`. So `copy.capacity` will be zero to
         prevent any appending to `copy` from overwriting elements in `array`.)
 
-        $(NOTE The runtime uses the number of elements appended to track the
+        $(NOTE The runtime uses the number of appended elements to track the
         start of the spare capacity for the memory allocation.)
 
         $(P When an array with spare capacity has its length reduced, or is
         assigned a slice of itself that ends before the previous last element,
         the capacity will be zero.)
 
+        $(P The `@system` function $(REF1 assumeSafeAppend, object) allows the
+        capacity to be regained, but care must be taken not to overwrite
+        immutable elements that may exist in a longer slice.)
+
         $(SPEC_RUNNABLE_EXAMPLE_RUN
         ---
         int[] a = [1, 2, 3];
-        a.reserve(2);
-        a = a[];
-        assert(a.capacity > 0);
-        a = a[0..2];
+        a.length--;
         assert(a.capacity == 0);
+        a.assumeSafeAppend();
+        assert(a.capacity >= 3);
         ---
         )