Merge pull request #3404 from ntrel/array-docs

[spec/arrays] Improve assignment docs

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

Author: dlang-bot

spec/arrays.dd

@@ -127,6 +127,9 @@ $(H2 $(LNAME2 assignment, Array Assignment))
         the handle for these types.
         )
 
+        $(P The `.ptr` property for static and dynamic arrays will give the address
+        of the first element in the array:)
+
 $(SPEC_RUNNABLE_EXAMPLE_RUN
 ---------
 int* p;
@@ -138,24 +141,49 @@ p = a.ptr; // p points to the first element of the array a.
 
 // 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
+    $(NOTE The two error lines above can be made to copy elements
+    using pointer $(RELATIVE_LINK2 slicing, slicing), so that the number of elements
     to copy is then known.)
 
+    $(P A static array can be assigned from a dynamic array - the data is copied.
+    The lengths must match:)
+
+$(SPEC_RUNNABLE_EXAMPLE_RUN
+---
+int[3] s;
+int[] a;
+
+//s = [1, 2]; // error
+s = [1, 2, 3]; // OK
+//s = [1, 2, 3, 4]; // error
+
+a = [4, 5, 6];
+s = a; // OK
+assert(s.ptr != a.ptr);
+a = [1, 2];
+//s = a; // RangeError, length mismatch
+
+a = s;
+assert(a.ptr == s.ptr);
+//s = a; // RangeError, overlap
+---
+)
+    $(P The dynamic array data must not $(RELATIVE_LINK2 overlapping-copying, overlap)
+    with the static array memory.
+    See also $(RELATIVE_LINK2 array-copying, Copying).)
+
+
 $(H2 $(LNAME2 indexing, Indexing))
 
     $(P Indexing allows access to an element of an array:)
@@ -205,7 +233,7 @@ $(H2 $(LNAME2 slicing, Slicing))
 
         $(P $(I Slicing) an array means to specify a subarray of it.
         An array slice does not copy the data, it is only another
-        reference to it.
+        reference to it. Slicing produces a dynamic array.
         For example:
         )
 
@@ -291,18 +319,26 @@ $(H2 $(LNAME2 array-copying, Array Copying))
         right-hand side is an array of or pointer to the same type.
         )
 
-$(SPEC_RUNNABLE_EXAMPLE_FAIL
+$(SPEC_RUNNABLE_EXAMPLE_RUN
 ---------
-int[3] s;
-int[3] t;
+int[3] s, t;
+int[] a;
 
 s = t;             // the 3 elements of t are copied into s
 s[] = t;           // the 3 elements of t are copied into s
 s[] = t[];         // the 3 elements of t are copied into s
 s[1..2] = t[0..1]; // same as s[1] = t[0]
 s[0..2] = t[1..3]; // same as s[0] = t[1], s[1] = t[2]
-s[0..4] = t[0..4]; // error, only 3 elements in s
-s[0..2] = t;       // error, operands have different lengths
+//s[0..4] = t[0..4]; // error, only 3 elements in s and t
+//s[0..2] = t;       // error, operands have different lengths
+
+a = [1, 2];
+s[0..2] = a;
+assert(s == [1, 2, 0]);
+
+//a[] = s; // RangeError, lengths don't match
+a[0..2] = s[1..3];
+assert(a == [2, 0]);
 ---------
 )
 
@@ -347,19 +383,28 @@ $(H2 $(LNAME2 array-setting, Array Setting))
         left-hand side are set to the right-hand side.
         )
 
-$(SPEC_RUNNABLE_EXAMPLE_COMPILE
+$(SPEC_RUNNABLE_EXAMPLE_RUN
 ---------
 int[3] s;
+int[] a;
 int* p;
 
-s[] = 3;     // same as s[0] = 3, s[1] = 3, s[2] = 3
-p[0..2] = 3; // same as p[0] = 3, p[1] = 3
+s[] = 3;
+assert(s == [3, 3, 3]);
+
+a = s;
+a[] = 1;
+assert(s == [1, 1, 1]);
+
+p = s.ptr;
+p[0..2] = 2;
+assert(s == [2, 2, 1]);
 ---------
 )
 
 $(H2 $(LNAME2 array-concatenation, Array Concatenation))
 
-        $(P The binary operator ~ is the $(I cat) operator. It is used
+        $(P The binary operator `~` is the $(I cat) operator. It is used
         to concatenate arrays:
         )
 
@@ -373,19 +418,19 @@ assert(b == [1, 2, 3, 4]); // concatenate two arrays
 ---
 )
 
-        $(P Many languages overload the + operator for concatenation.
+        $(P Many languages overload the `+` operator for concatenation.
         This confusingly leads to a dilemma - does:
         )
 
 ---------
 "10" + 3 + 4
 ---------
 
-        $(P produce the number 17, the string "1034" or the string "107" as the
+        $(P produce the number `17`, the string `"1034"` or the string `"107"` as the
         result? It isn't obvious, and the language designers wind up carefully
         writing rules to disambiguate it - rules that get incorrectly
         implemented, overlooked, forgotten, and ignored. It's much better to
-        have + mean addition, and a separate operator to be array
+        have `+` mean addition, and a separate operator to be array
         concatenation.
         )
 
@@ -409,7 +454,7 @@ assert(a == b);
 
 $(H2 $(LNAME2 array-appending, Array Appending))
 
-        $(P Similarly, the ~= operator means append, as in:
+        $(P Similarly, the `~=` operator means append, as in:
         )
 
 ---------
@@ -588,7 +633,7 @@ a.dup;    // creates an array of a.length elements, copies
 $(H3 $(LNAME2 resize, Setting Dynamic Array Length))
 
         $(P The $(D .length) property of a dynamic array can be set
-        as the left-hand side of an = operator:
+        as the left-hand side of an `=` operator:
         )
 
 ---------
@@ -827,7 +872,7 @@ $(H3 $(LNAME2 default-initialization, Default Initialization))
 $(H3 $(LNAME2 length-initialization, Length Initialization))
         $(P The $(D new) expression can be used to start a dynamic array
         with a specified length by specifying its type and then using the
-        () syntax:
+        `(size)` syntax:
         )
 
 $(SPEC_RUNNABLE_EXAMPLE_COMPILE
@@ -846,36 +891,40 @@ $(H3 $(LNAME2 void-initialization, Void Initialization))
         Void initializations are an advanced technique and should only be used
         when profiling indicates that it matters.
         )
-        $(P to void initialise the elements of dynamic array use
+        $(P To void initialise the *elements* of a dynamic array use
         $(REF uninitializedArray, std,array).
         )
 
 
 $(H3 $(LNAME2 static-init-static, Static Initialization of Statically Allocated Arrays))
 
         $(P Static initalizations are supplied by a list of array
-        element values enclosed in [ ]. The values can be optionally
-        preceded by an index and a :.
+        element values enclosed in `[ ]`. The values can be optionally
+        preceded by an index and a `:`.
         If an index is not supplied, it is set to the previous index
         plus 1, or 0 if it is the first value.
         )
 
-$(SPEC_RUNNABLE_EXAMPLE_COMPILE
+$(SPEC_RUNNABLE_EXAMPLE_RUN
 ---------
 int[3] a = [ 1:2, 3 ]; // a[0] = 0, a[1] = 2, a[2] = 3
+
+assert(a == [0, 2, 3]);
 ---------
 )
 
-        $(P This is most handy when the array indices are given by enums:)
+        $(P This is most handy when the array indices are given by $(DDLINK spec/enum, Enums, enums):)
 
-$(SPEC_RUNNABLE_EXAMPLE_COMPILE
+$(SPEC_RUNNABLE_EXAMPLE_RUN
 ---------
 enum Color { red, blue, green }
 
 int[Color.max + 1] value =
   [ Color.blue :6,
     Color.green:2,
     Color.red  :5 ];
+
+assert(value == [5, 6, 2]);
 ---------
 )