Merge pull request #3160 from ntrel/expr-slice

[expression.dd] Improve IndexExpression & SliceExpression docs

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

Author: dlang-bot

spec/expression.dd

@@ -1341,22 +1341,30 @@ $(GNAME IndexExpression):
     $(GLINK PostfixExpression) $(D [) $(GLINK ArgumentList) $(D ])
 )
 
-$(P $(I PostfixExpression) is evaluated. If $(I PostfixExpression) is an
-expression of type static array or dynamic array, the symbol $(DOLLAR) is set to
-be the number of elements in the array. If $(I PostfixExpression) is a $(I
-ValueSeq), the symbol $(DOLLAR) is set to be the number of elements
-in the sequence. A new declaration scope is created for the evaluation of the
-$(GLINK ArgumentList) and $(DOLLAR) appears in that scope only.)
-
-    $(P If $(I PostfixExpression) is a $(I ValueSeq),
-        then the $(GLINK ArgumentList) must consist of only one argument,
+    $(P $(I PostfixExpression) is evaluated.
+        If $(I PostfixExpression) is an expression of static or
+        dynamic array type, the result of the indexing is an lvalue
+        of the *i*th element in the array, where `i` is an integer
+        evaluated from $(I ArgumentList).
+        If $(I PostfixExpression) is a pointer `p`, the result is
+        `*(p + i)` (see $(RELATIVE_LINK2 pointer_arithmetic, Pointer Arithmetic)).
+    )
+
+    $(P If $(I PostfixExpression) is a $(DDSUBLINK spec/template, variadic-templates, $(I ValueSeq))
+        then the $(I ArgumentList) must consist of only one argument,
         and that must be statically evaluatable to an integral constant.
         That integral constant $(I n) then selects the $(I n)th
         expression in the $(I ValueSeq), which is the result
         of the $(I IndexExpression).
         It is an error if $(I n) is out of bounds of the $(I ValueSeq).
     )
 
+    $(P The special variable `$` is declared and set to be the number
+        of elements in the $(I PostfixExpression) (when available).
+        A new declaration scope is created for the evaluation of the
+        $(I ArgumentList) and `$` appears in that scope only.
+    )
+
 $(H2 $(LNAME2 slice_expressions, Slice Expressions))
 
 $(GRAMMAR
@@ -1372,43 +1380,59 @@ $(GNAME Slice):
 )
 
     $(P $(I PostfixExpression) is evaluated.
-        if $(I PostfixExpression) is an expression of type
-        static array or dynamic array, the special variable $(DOLLAR)
-        is declared and set to be the length of the array.
-        A new declaration scope is created for the evaluation of the
-        $(GLINK AssignExpression)..$(GLINK AssignExpression)
-        and $(DOLLAR) appears in that scope only.
+        If $(I PostfixExpression) is a static or dynamic
+        array `a`, the result of the slice is a dynamic array
+        referencing elements `a[i]` to `a[j-1]` inclusive, where `i`
+        and `j` are integers evaluated from the first and second $(I
+        AssignExpression) respectively.
+    )
+
+    $(P If $(I PostfixExpression) is a pointer `p`, the result
+        will be a dynamic array referencing elements from `p[i]` to `p[j-1]`
+        inclusive, where `i` and `j` are integers evaluated from the
+        first and second $(I AssignExpression) respectively.
+    )
+
+    $(P If $(I PostfixExpression) is a $(DDSUBLINK spec/template, variadic-templates, $(I ValueSeq)), then
+        the result of the slice is a new $(I ValueSeq) formed
+        from the upper and lower bounds, which must statically evaluate
+        to integral constants.
+        It is an error if those bounds are out of range.
     )
 
     $(P The first $(I AssignExpression) is taken to be the inclusive
         lower bound
         of the slice, and the second $(I AssignExpression) is the
         exclusive upper bound.
-        The result of the expression is a slice of the $(I PostfixExpression)
-        array.
+        The result of the expression is a slice of the elements in $(I PostfixExpression).
     )
 
-    $(P If the $(D [ ]) form is used, the slice is of the entire
-        array.
+    $(P The special variable `$` is declared and set to be the number
+        of elements in the $(I PostfixExpression) (when available).
+        A new declaration scope is created for the evaluation of the
+        $(I AssignExpression)`..`$(I AssignExpression) and `$` appears in
+        that scope only.
     )
 
-    $(P The type of the slice is a dynamic array of the element
-        type of the $(I PostfixExpression).
+    $(P If the $(D [ ]) form is used, the slice is of all the elements in $(I PostfixExpression).
     )
 
     $(P A $(I SliceExpression) is not a modifiable lvalue.)
 
+$(H3 $(LNAME2 slice_to_static_array, Slice Conversion to Static Array))
+
     $(P If the slice bounds can be known at compile time, the slice expression
-    is implicitly convertible to an lvalue of static array. For example:)
+    may be implicitly convertible to an lvalue of static array. For example:)
 
         -------------
         arr[a .. b]     // typed T[]
         -------------
 
-        If both $(CODE a) and $(CODE b) are integers (may be constant-folded),
+        If both $(CODE a) and $(CODE b) are integers (which may be constant-folded),
         the slice expression can be converted to a static array type
         $(D T[b - a]).
 
+        $(SPEC_RUNNABLE_EXAMPLE_RUN
         -------------
         void foo(int[2] a)
         {
@@ -1433,9 +1457,10 @@ $(GNAME Slice):
             bar(arr[1 .. 3]);
             assert(arr == [1, 4, 5]);
 
-          //baz(arr[1 .. 3]); // cannot match length
+            //baz(arr[1 .. 3]); // cannot match length
         }
         -------------
+        )
 
 $(P The following forms of slice expression can be convertible to a static array
 type:)
@@ -1456,14 +1481,6 @@ type:)
         $(TROW $(D arr[e-a .. e-b]), $(D a - b) $(I if) $(D a >= b))
         )
 
-    $(P If $(I PostfixExpression) is a $(I ValueSeq), then
-        the result of the slice is a new $(I ValueSeq) formed
-        from the upper and lower bounds, which must statically evaluate
-        to integral constants.
-        It is an error if those
-        bounds are out of range.
-    )
-
 $(H2 $(LNAME2 primary_expressions, Primary Expressions))
 
 $(GRAMMAR