Merge pull request #3215 from ntrel/arr-lit

Move ArrayInitializer grammar to expression.dd & improve docs

Signed-off-by: Dennis <[email protected]>
Merged-on-behalf-of: Dennis <[email protected]>

Author: dlang-bot

spec/declaration.dd

@@ -104,22 +104,12 @@ $(GNAME Initializer):
 
 $(GNAME NonVoidInitializer):
     $(GLINK2 expression, AssignExpression)$(LEGACY_LNAME2 ExpInitializer)
-    $(GLINK ArrayInitializer)
+    $(GLINK2 expression, ArrayLiteral)$(LEGACY_LNAME2 ArrayInitializer)
     $(GLINK2 struct, StructInitializer)$(LEGACY_LNAME2 StructInitializer)
-
-$(GNAME ArrayInitializer):
-    $(D [) $(GLINK ArrayMemberInitializations)$(OPT) $(D ])
-
-$(GNAME ArrayMemberInitializations):
-    $(GLINK ArrayMemberInitialization)
-    $(GLINK ArrayMemberInitialization) $(D ,)
-    $(GLINK ArrayMemberInitialization) $(D ,) $(GSELF ArrayMemberInitializations)
-
-$(GNAME ArrayMemberInitialization):
-    $(GLINK NonVoidInitializer)
-    $(GLINK2 expression, AssignExpression) $(D :) $(GLINK NonVoidInitializer)
 )
 
+$(P See also $(GLINK VoidInitializer).)
+
 $(H2 $(LNAME2 declaration_syntax, Declaration Syntax))
 
 $(P Declaration syntax generally reads right to left, including arrays:)

spec/expression.dd

@@ -1690,15 +1690,24 @@ $(H3 $(LNAME2 array_literals, Array Literals))
 
 $(GRAMMAR
 $(GNAME ArrayLiteral):
-    $(D [) $(GLINK ArgumentList)$(OPT) $(D ])
+    $(D [) $(I ArrayMemberInitializations)$(OPT) $(D ])
+
+$(GNAME ArrayMemberInitializations):
+    $(I ArrayMemberInitialization)
+    $(I ArrayMemberInitialization) $(D ,)
+    $(I ArrayMemberInitialization) $(D ,) $(GSELF ArrayMemberInitializations)
+
+$(GNAME ArrayMemberInitialization):
+    $(GLINK2 declaration, NonVoidInitializer)
+    $(GLINK AssignExpression) $(D :) $(GLINK2 declaration, NonVoidInitializer)
 )
 
-    $(P Array literals are a comma-separated list of $(GLINK AssignExpression)s
+    $(P An array literal is a comma-separated list of expressions
         between square brackets $(D [) and $(D ]).
-        The $(I AssignExpression)s form the elements of a dynamic array,
-        the length of the array is the number of elements.
-        The common type of the all elements is taken to be the type of
-        the array element, and all elements are implicitly converted
+        The expressions form the elements of a dynamic array.
+        The length of the array is the number of elements.
+        The common type of all the elements is taken to be the
+        array element type, and each expression is implicitly converted
         to that type.)
 
         ---
@@ -1707,41 +1716,20 @@ $(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. Slicing a dynamic array with
-        statically known bounds also allows conversion to a static array.)
+        count is known at compile time. Therefore, an array literal can be
+        implicitly converted to a static array of the same length.)
 
-        $(SPEC_RUNNABLE_EXAMPLE_RUN
         -------------
-        void foo(long[2] a)
-        {
-            assert(a == [2, 3]);
-        }
-        void bar(ref long[2] a)
-        {
-            assert(a == [2, 3]);
-            a = [4, 5];
-            assert(a == [4, 5]);
-        }
-
-        void main()
-        {
-            long[] arr = [1, 2, 3];
-
-            foo(arr[1 .. 3]);
-            assert(arr == [1, 2, 3]);
-
-            bar(arr[1 .. 3]);
-            assert(arr == [1, 4, 5]);
-
-            //foo(arr[0 .. 3]); // cannot match length
-        }
+        int[2] sa = [1, 2];
         -------------
-        )
 
-    $(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.
+    $(NOTE Slicing a dynamic array with a statically known slice length also
+        $(RELATIVE_LINK2 slice_to_static_array, allows conversion) to a static array.)
+
+    $(P If any $(I ArrayMemberInitialization) is a
+        $(DDSUBLINK spec/template, TemplateParameterSequence, ValueSeq),
+        then the elements of the $(I ValueSeq)
+        are inserted as expressions in place of the sequence.
     )
 
     $(P Escaping array literals are allocated on the memory managed heap.
@@ -1754,6 +1742,27 @@ $(GNAME ArrayLiteral):
         }
         ---
 
+    $(P To initialize an element at a particular index, use the
+        *AssignExpression* `:` *NonVoidInitializer* syntax.
+        The *AssignExpression* must be known at compile-time.
+        Any missing elements will be initialized to the default value
+        of the element type.
+        Note that if the array type is not specified, the literal will
+        be parsed as an
+        $(RELATIVE_LINK2 associative_array_literals, associative array).)
+
+        $(SPEC_RUNNABLE_EXAMPLE_COMPILE
+        ---
+        int n = 4;
+        auto aa = [0:1, 3:n]; // associative array `int[int]`
+
+        int[] a = [1, 3:n, 5];
+        assert(a == [1, 0, 0, n, 5]);
+
+        //int[] e = [n:2]; // error, n not known at compile-time
+        ---
+        )
+
 $(H3 $(LNAME2 cast_array_literal, Casting))
 
     $(P When array literals are cast to another array type, each