Merge pull request #3161 from ntrel/array-tweaks

[spec] Improve array docs

Signed-off-by: Max Haughton <maxhaton@users.noreply.github.com>
Merged-on-behalf-of: Dennis <dkorpel@users.noreply.github.com>

Author: dlang-bot

spec/arrays.dd

@@ -121,38 +121,75 @@ int[]* e;     // pointer to dynamic array of ints
 ---------
 )
 
-$(H2 $(LNAME2 usage, Array Usage))
+$(H2 $(LNAME2 literals, Array Literals))
 
-        $(P There are two broad kinds of operations to do on an array -
-        affecting
-        the handle to the array,
-        and affecting the contents of the array.
-        )
+---
+auto a1 = [1,2,3];  // type is int[], with elements 1, 2 and 3
+auto a2 = [1u,2,3]; // type is uint[], with elements 1u, 2u, and 3u
+int[2] = [1, 2];
+---
+    $(P `[]` is an empty array literal.)
 
-        $(P The handle to an array is specified by naming the array, as
-        in p, s or a:
+    $(P See $(DDSUBLINK expression, array_literals, Array Literals).)
+
+$(LEGACY_LNAME2 usage)
+$(H2 $(LNAME2 assignment, Array Assignment))
+
+        $(P There are two broad kinds of operations to do on dynamic arrays and
+        pointer arrays - those affecting the handle to the array,
+        and those affecting the contents of the array. Assignment only affects
+        the handle for these types.
         )
 
-$(SPEC_RUNNABLE_EXAMPLE_FAIL
+$(SPEC_RUNNABLE_EXAMPLE_RUN
 ---------
 int* p;
 int[3] s;
 int[] a;
 
-int[] b;
-
 p = s.ptr; // p points to the first element of the array s.
 p = a.ptr; // p points to the first element of the array a.
 
-a = p;     // error, since the length of the array pointed
-           // to by p is unknown
-a = s;     // a is initialized to point to the s array
+// error, since the length of the array pointed to by p is unknown
+//s = p;
+//s = a; // error, as a's length is not known at compile-time
+s = [1,2,3];
+
+//a = p;   // error, length unknown
+a = s;     // a points to the elements of s
+assert(a.ptr == s.ptr);
+assert(a == [1,2,3]);
+
+int[] b;
 a = b;     // a points to the same array as b does
+assert(a.ptr == b.ptr);
+assert(a == []);
 ---------
 )
+    $(P Each of the three error lines above can be made to copy elements
+    using $(RELATIVE_LINK2 slicing, slicing), so that the number of elements
+    to copy is then known.)
 
 $(H2 $(LNAME2 indexing, Indexing))
 
+    $(P Indexing allows access to an element of an array:)
+
+$(SPEC_RUNNABLE_EXAMPLE_RUN
+---------
+auto a = [1,2,3];
+assert(a[0] == 1);
+assert(a[2] == 3);
+a[2] = 4;
+assert(a[2] == 4);
+assert(a == [1,2,4]);
+//writeln(a[3]); // runtime error (unless bounds checks turned off)
+
+int[2] b = [1,2];
+assert(b[1] == 2);
+//writeln(b[2]); // compile-time error, index out of bounds
+---------
+)
+
     $(P See also $(GLINK2 expression, IndexExpression).)
 
 $(H2 $(LNAME2 slicing, Slicing))
@@ -181,7 +218,7 @@ foo(b[1]);   // equivalent to foo(3)
 ---------
 )
 
-        $(P The [] is shorthand for a slice of the entire array.
+        $(P $(I Identifier)[] is shorthand for a slice of the entire array.
         For example, the assignments to b:
         )
 
@@ -255,8 +292,10 @@ $(H3 $(LNAME2 overlapping-copying, Overlapping Copying))
 
         $(P Overlapping copies are an error:)
 
-$(SPEC_RUNNABLE_EXAMPLE_FAIL
+$(SPEC_RUNNABLE_EXAMPLE_COMPILE
 ---------
+int[3] s;
+
 s[0..2] = s[1..3]; // error, overlapping copy
 s[1..3] = s[0..2]; // error, overlapping copy
 ---------
@@ -410,9 +449,6 @@ $(H2 $(LNAME2 pointer-arithmetic, Pointer Arithmetic))
 
 $(SPEC_RUNNABLE_EXAMPLE_FAIL
 ---------
-int[3] abc;              // static array of 3 ints
-int[] def = [ 1, 2, 3 ]; // dynamic array of 3 ints
-
 void dibb(int* array)
 {
     array[2];     // means same thing as *(array + 2)
@@ -694,9 +730,9 @@ $(H2 $(LNAME2 bounds, Array Bounds Checking))
 
         $(P It is an error to index an array with an index that is less than
         0 or greater than or equal to the array length. If an index is
-        out of bounds, a RangeError exception is
-        raised if detected at runtime, and an error if detected at compile
-        time.  A program may not rely on array bounds checking happening, for
+        out of bounds, an `ArrayIndexError` is thrown
+        if detected at runtime, and an error is raised if detected at compile
+        time. A program may not rely on array bounds checking happening, for
         example, the following program is incorrect:
         )
 
@@ -711,7 +747,7 @@ try
         array[i] = 5;
     }
 }
-catch (RangeError)
+catch (ArrayIndexError)
 {
     // terminate loop
 }

spec/expression.dd

@@ -1577,8 +1577,10 @@ $(GNAME ArrayLiteral):
 
     $(P By default, an array literal is typed as a dynamic array, but the element
         count is known at compile time. So all array literals can be
-        implicitly converted to static array types.)
+        implicitly converted to static array types. Slicing a dynamic array with
+        statically known bounds also allows conversion to a static array.)
 
+        $(SPEC_RUNNABLE_EXAMPLE_RUN
         -------------
         void foo(long[2] a)
         {
@@ -1587,11 +1589,9 @@ $(GNAME ArrayLiteral):
         void bar(ref long[2] a)
         {
             assert(a == [2, 3]);
-            a[0] = 4;
-            a[1] = 5;
+            a = [4, 5];
             assert(a == [4, 5]);
         }
-        void baz(const char[3] a) {}
 
         void main()
         {
@@ -1603,16 +1603,17 @@ $(GNAME ArrayLiteral):
             bar(arr[1 .. 3]);
             assert(arr == [1, 4, 5]);
 
-          //baz(arr[1 .. 3]); // cannot match length
+            //foo(arr[0 .. 3]); // cannot match length
         }
         -------------
+        )
 
     $(P If any of the arguments in the $(GLINK ArgumentList) are
         a $(I ValueSeq), then the elements of the $(I ValueSeq)
         are inserted as arguments in place of the sequence.
     )
 
-    $(P Array literals are allocated on the memory managed heap.
+    $(P Escaping array literals are allocated on the memory managed heap.
         Thus, they can be returned safely from functions:)
 
         ---
@@ -1646,7 +1647,7 @@ $(GNAME ArrayLiteral):
         }
         ---
 
-        In other words, casting literal expression will change the literal type.
+        In other words, casting an array literal will change the type of each initializer element.
 
 $(H3 $(LNAME2 associative_array_literals, Associative Array Literals))
 
@@ -1682,7 +1683,7 @@ $(GNAME ValueExpression):
         anything.)
 
         ---
-        [21u:"he", 38:"ho", 2:"hi"];  // type is string[uint],
+        [21u: "he", 38: "ho", 2: "hi"]; // type is string[uint],
                                       // with keys 21u, 38u and 2u
                                       // and values "he", "ho", and "hi"
         ---

spec/hash-map.dd

@@ -12,6 +12,7 @@ $(HEADERNAV_TOC)
         within the $(D [ ]) of an array declaration:
         )
 
+        $(SPEC_RUNNABLE_EXAMPLE_RUN
         ---------
         int[string] aa;   // Associative array of ints that are
                           // indexed by string keys.
@@ -20,6 +21,7 @@ $(HEADERNAV_TOC)
         int value = aa["hello"];  // lookup value from a key
         assert(value == 3);
         ---------
+        )
 
         $(P Neither the $(I KeyType)s nor the element types of an associative
         array can be function types or $(D void).
@@ -29,6 +31,17 @@ $(HEADERNAV_TOC)
         of the keys inserted into the array. In particular, in a $(D foreach) loop the
         order in which the elements are iterated is typically unspecified.)
 
+$(H2 $(LNAME2 literals, Literals))
+
+$(SPEC_RUNNABLE_EXAMPLE_RUN
+---
+auto aa = [21u: "he", 38: "ho", 2: "hi"];
+static assert(is(typeof(aa) == string[uint]));
+assert(aa[2] == "hi");
+---
+)
+    $(P See $(DDSUBLINK expression, associative_array_literals, Associative Array Literals).)
+
 $(H2 $(LNAME2 removing_keys, Removing Keys))
 
         $(P Particular keys in an associative array can be removed with the