[spec] Improve array docs

Improve *Array Usage* example and link to *Slicing*.
Add *Array Literals* section.
Add example for *Indexing*.
Remove unnecessary variables in *Pointer Arithmetic* example.

[expression.dd] Simplify literal -> static array example.

[hash-map.dd] Add AA *Literals* section.

Author: ntrel

spec/arrays.dd

@@ -124,35 +124,66 @@ int[]* e;     // pointer to dynamic array of ints
 $(H2 $(LNAME2 usage, Array Usage))
 
         $(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.
+        those affecting the handle to the array,
+        and those affecting the contents of the array.
         )
 
         $(P The handle to an array is specified by naming the array, as
         in p, s or a:
         )
 
-$(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
+// 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
+
+//a = p;   // error, length unknown
 a = s;     // a is initialized to point to the s array
+assert(a.ptr == s.ptr);
+
+int[] b;
 a = b;     // a points to the same array as b does
+assert(a.ptr == b.ptr);
 ---------
 )
+    $(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 literals, Array Literals))
+
+---
+auto a1 = [1,2,3];  // type is int[], with elements 1, 2 and 3
+a1 = []; // a1 is now empty
+auto a2 = [1u,2,3]; // type is uint[], with elements 1u, 2u, and 3u
+int[2] = [1, 2];
+---
+
+    $(P See $(DDSUBLINK expression, array_literals, Array Literals).)
 
 $(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]);
+---------
+)
+
     $(P See also $(GLINK2 expression, IndexExpression).)
 
 $(H2 $(LNAME2 slicing, Slicing))
@@ -181,7 +212,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 +286,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 +443,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,7 +724,7 @@ $(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
+        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
         example, the following program is incorrect:

spec/expression.dd

@@ -1554,8 +1554,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)
         {
@@ -1564,11 +1566,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()
         {
@@ -1580,16 +1580,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:)
 
         ---
@@ -1623,7 +1624,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))
 

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