[spec/expression] Add array literal heap allocation section (#3885)

* [spec/expression] Add array literal heap allocation section

Also tweak `@nogc` items.

* Add 3 more cases

Author: ntrel

spec/expression.dd

@@ -2143,7 +2143,9 @@ $(GNAME ArrayLiteral):
         are inserted as expressions in place of the sequence.
     )
 
-    $(P Escaping array literals are allocated on the memory managed heap.
+$(H4 $(LNAME2 array-literal-heap, GC Allocation))
+
+    $(P Escaping array literals are always allocated on the memory managed heap.
         Thus, they can be returned safely from functions:)
 
         ---
@@ -2153,6 +2155,36 @@ $(GNAME ArrayLiteral):
         }
         ---
 
+    $(P An array literal is not GC allocated if:)
+
+    * It initializes or assigns to a static array.
+    * It initializes a $(DDSUBLINK spec/attribute, scope, `scope`) slice.
+    * It is used on one side of a $(GLINK EqualExpression) or $(GLINK RelExpression).
+    * It is immediately $(RELATIVE_LINK2 index_operations, indexed) and used as an rvalue.
+    * It is used as a `foreach` aggregate where the element variable is not `ref`.
+
+    $(SPEC_RUNNABLE_EXAMPLE_COMPILE
+    ---
+    void f(scope int[] a, int[2] sa) @nogc
+    {
+        sa = [7, 8];
+    }
+    void g(int[] b) @nogc; // `b` is not scope, so may escape
+
+    void main() @nogc
+    {
+        int[3] sa = [1, 2, 3];
+        f([1, 2], [3, 4]);
+        //scope int[] a = [5, 6]; // requires `-preview=dip1000`
+        //g([1, 2]); // error, array literal heap allocated
+        assert([1, 2] < [3, 2]);
+        assert([1, 2][1] == 2);
+        foreach (e; [4, 2, 9])
+            assert(e > 0);
+    }
+    ---
+    )
+
 $(H4 $(LNAME2 cast_array_literal, Casting))
 
     $(P When array literals are cast to another array type, each

spec/function.dd

@@ -3723,16 +3723,17 @@ $(H2 $(LNAME2 nogc-functions, No-GC Functions))
         )
 
         $(OL
-        $(LI $(DDSUBLINK spec/expression, ArrayLiteral, constructing an array) on the heap)
+        $(LI $(DDSUBLINK spec/expression, array-literal-heap, constructing an array) on the heap)
         $(LI resizing an array by writing to its $(D .length) property)
         $(LI $(DDSUBLINK spec/expression, CatExpression, array concatenation))
         $(LI $(DDSUBLINK spec/expression, simple_assignment_expressions, array appending))
         $(LI $(DDSUBLINK spec/expression, AssocArrayLiteral, constructing an associative array))
         $(LI $(DDSUBLINK spec/expression, IndexOperation, indexing) an associative array
-            $(NOTE because it may throw $(D RangeError) if the specified key is not present))
+            $(RATIONALE Indexing may throw a $(D RangeError) if the specified key is not present.))
         $(LI $(DDSUBLINK spec/expression, NewExpression, allocating an object with `new`) on the heap
-            $(NOTE `new` declarations of $(D class types) in function scopes are compatible with
-            $(D @nogc) if used for $(D scope) variables, as they result in allocations on the stack))
+            $(NOTE `new` declarations of $(D class) types in function scopes are compatible with
+            $(D @nogc) if used to initialize a $(DDSUBLINK spec/attribute, scope-class-var, $(D scope) variable),
+            as they result in allocations on the stack.))
         $(LI calling functions that are not `@nogc`, unless the call is
             in a $(GLINK2 version, ConditionalStatement)
             controlled by a $(GLINK2 version, DebugCondition))