Merge pull request #3225 from ntrel/seq-param

[spec/template.dd] Improve TemplateSequenceParameter docs

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

Author: dlang-bot

spec/template.dd

@@ -830,60 +830,124 @@ $(GNAME TemplateSequenceParameter):
 
     $(P If the last template parameter in the $(I TemplateParameterList)
         is declared as a $(I TemplateSequenceParameter),
-        it is a match with any trailing template arguments.
-        Such a sequence of arguments can be defined using the template
-        $(REF AliasSeq, std,meta) and will thus henceforth
+        it is a match with zero or more trailing template arguments.
+        Any argument that can be passed to a $(GLINK TemplateAliasParameter)
+        can be passed to a sequence parameter.
+    )
+    $(P Such a sequence of arguments can itself be aliased for use outside
+        a template. The $(REF AliasSeq, std,meta) template simply
+        aliases its sequence parameter:)
+    ---
+    alias AliasSeq(Args...) = Args;
+    ---
+    $(P A *TemplateSequenceParameter* will thus henceforth
         be referred to by that name for clarity.
-        An $(I AliasSeq) is not itself a type, value, or symbol.
-        It is a compile-time sequence of any mix of types, values or symbols.
+        An $(I AliasSeq) is not itself a type, value, or symbol. It is a
+        $(DDLINK articles/ctarguments, Compile-time Sequences, compile-time sequence)
+        of any mix of types, values or symbols, or none.
     )
-
-    $(P An $(I AliasSeq) whose elements consist entirely of types is
-        called a type sequence or $(I TypeSeq).
-        An $(I AliasSeq) whose elements consist entirely of values is
-        called a value sequence or $(I ValueSeq).
+    $(UL
+    $(LI An $(I AliasSeq) whose elements consist entirely of types is
+        called a type sequence or $(I TypeSeq).)
+    $(LI An $(I AliasSeq) whose elements consist entirely of values is
+        called a value sequence or $(I ValueSeq).)
+    $(LI `typeof` can be used on a *ValueSeq* to obtain a *TypeSeq*.)
     )
 
-    $(P An $(I AliasSeq) can be used as an argument list to instantiate
-        another template, or as the list of parameters for a function.)
+    $(P The elements of an $(I AliasSeq) are automatically expanded
+        when it is referenced in a declaration or expression.
+        An $(I AliasSeq) can be used as arguments to instantiate a
+        template. A *ValueSeq* can be used as arguments to call a
+        function:)
 
         $(SPEC_RUNNABLE_EXAMPLE_RUN
         ---
-        import std.stdio;
+        import std.stdio : writeln;
 
-        template print(args...)
+        template print(args...) // args must be a ValueSeq
         {
             void f()
             {
-                writeln("args are ", args); // args is a ValueSeq
+                writeln("args are ", args);
             }
         }
 
-        template write(Args...) // Args is a TypeSeq
+        void main()
+        {
+            print!(1, 'a', 6.8).f(); // prints: args are 1a6.8
+        }
+        ---
+        )
+
+        $(P A *TypeSeq* can be used to declare parameters for a function:)
+
+        $(SPEC_RUNNABLE_EXAMPLE_RUN
+        ---
+        import std.stdio : writeln;
+
+        template print(Types...) // Types must be a TypeSeq
         {
-            void f(Args args) // args is a ValueSeq
+            void f(Types args) // args is a ValueSeq
             {
                 writeln("args are ", args);
             }
         }
 
         void main()
         {
-            print!(1,'a',6.8).f();                    // prints: args are 1a6.8
-            write!(int, char, double).f(1, 'a', 6.8); // prints: args are 1a6.8
+            print!(int, char, double).f(1, 'a', 6.8); // prints: args are 1a6.8
         }
         ---
         )
 
-    $(P The number of elements in an $(I AliasSeq) can be retrieved with
-        the $(D .length) property. The $(I n)th element can be retrieved
-        by indexing the $(I AliasSeq) with [$(I n)],
-        and sub-sequences are denoted by the slicing syntax.
+    $(P A *TypeSeq* can similarly be used to
+        $(DDSUBLINK articles/ctarguments, type-seq-instantiation, declare variables).
+        Parameters or variables declared with a *TypeSeq* are called an
+        *lvalue sequence*.)
+
+$(H4 $(LNAME2 seq-ops, Sequence Operations))
+
+    $(UL
+    $(LI The number of elements in an $(I AliasSeq) can be retrieved with
+        the $(D .length) property.)
+    $(LI The $(I n)th element can be retrieved by
+        $(DDSUBLINK spec/expression, index_expressions, indexing) an
+        $(I AliasSeq) with `Seq[n]`. Indexes must be known at compile-time.
+        The result is an lvalue when the element is a variable.)
+    $(LI $(DDSUBLINK spec/expression, slice_expressions, Slicing)
+        produces a new sequence with a subset of the elements of the original sequence.)
+    )
+
+    $(SPEC_RUNNABLE_EXAMPLE_RUN
+    ---
+    import std.meta : AliasSeq;
+
+    int v = 4;
+    alias nums = AliasSeq!(1, 2, 3, v);
+    static assert(nums.length == 4);
+    static assert(nums[1] == 2);
+
+    // nums[3] is bound to v, an lvalue
+    nums[3]++;
+    assert(v == 5);
+
+    // slice first 3 elements
+    alias trio = nums[0 .. $-1];
+    // expand into an array literal
+    static assert([trio] == [1, 2, 3]);
+    ---
     )
 
-    $(P $(I AliasSeq)-s are static compile-time entities, there is no way
+    $(P $(I AliasSeq)s are static compile-time entities, there is no way
         to dynamically change, add, or remove elements either at compile-time or run-time.
+        Instead, either:)
+    $(UL
+    $(LI Construct a new sequence using the original sequence (or a slice of it) and additional elements before or after it.)
+    $(LI Use $(DDSUBLINK spec/declaration, AliasAssign, Alias Assignment)
+        to build new sequences iteratively.)
     )
+    $(P Sequences can 'unroll' code for each element using a
+        $(DDSUBLINK spec/statement, foreach_over_tuples, `foreach` statement).)
 
 $(H4 $(LNAME2 typeseq_deduction, Type Sequence Deduction))
 

spec/type.dd

@@ -468,6 +468,10 @@ $(GNAME Typeof):
         }
         --------------------
 
+        $(P If *Expression* is a
+        $(DDSUBLINK spec/template, variadic-templates, $(I ValueSeq))
+        it will produce a *TypeSeq* containing the types of each element.)
+
         $(P Special cases: )
     $(OL
         $(LI $(D typeof(this)) will generate the type of what $(D this)