Merge pull request #2204 from ntrel/ct-seq

Improve Compile-time sequences docs

Author: wilzbach

articles/ctarguments.dd

@@ -1,33 +1,35 @@
 Ddoc
 
-$(D_S Compile-time Argument Lists,
+$(D_S $(TITLE),
 
 $(HEADERNAV_TOC)
 
-    $(P Compile-time lists is an important metaprogramming concept that comes naturally
+    $(H2 $(LNAME2 Background, Background))
+
+    $(P Compile-time sequences are an important metaprogramming concept that comes naturally
         from D support for $(LINK2 variadic-function-templates.html, variadic templates). They
-        allow a programmer to operate on types, symbols and expressions enabling the ability to define
-        compile-time algorithms that operate on types, symbols and expressions.
+        allow a programmer to operate on types, symbols and values, enabling the ability to define
+        compile-time algorithms that operate on types, symbols and values.
     )
 
-    $(P For historical reasons those sometimes can be called tuples in documentation or compiler
-        internals but don't get confused : this doesn't have much in common with tuples that
+    $(P $(B Note:) For historical reasons these sequences can sometimes be called tuples in documentation or compiler
+        internals, but don't get confused - they don't have much in common with tuples that
         commonly exist in other languages. Sequences of values of different types that can be
-        returned from functions are provided by $(LINK2 phobos/std_typecons.html#.Tuple, std.typecons.Tuple).
-        Using term "tuple" to mean compile-time lists is discouraged to avoid confusion, and if encountered
+        returned from functions are provided by $(REF Tuple, std, typecons).
+        Using the term "tuple" to mean compile-time sequences is discouraged to avoid confusion, and if encountered
         should result in a $(LINK2 https://issues.dlang.org, documentation bug report).
     )
 
-    $(P Consider this simple snippet:)
+    $(P Consider this simple variadic template:)
 
     ---
     template Variadic(T...) { /* ... */ }
     ---
 
-    $(P `T` here is variadic $(LINK2 spec/template.html#TemplateArgumentList, template argument list)
+    $(P `T` here is a $(DDSUBLINK spec/template, variadic-templates, TemplateParameterSequence),
         which is a core language feature. It has its own special semantics,
         and, from the programmer's point of view, is most similar to an array of compile-time entities - types,
-        symbols (names) and expressions (values). One can check the length of this list
+        symbols (names) and values. One can check the length of this sequence
         and access any individual element:
     )
 
@@ -39,34 +41,36 @@ $(HEADERNAV_TOC)
         pragma(msg, T[1]);
     }
 
-    alias Dummy = Variadic!(int, 42);
+    alias dummy = Variadic!(int, 42);
     // prints during compilation:
     // int
     // 42
     ---
 
-    $(P However, the language itself does not provide any means to define such lists outside of
+    $(H2 $(LNAME2 AliasSeq, AliasSeq))
+
+    $(P The language itself does not provide any means to define such sequences outside of
         a template parameter declaration. Instead, there is a
-        $(MREF_ALTTEXT simple utility, std, meta) provided by the D standard
+        $(MREF_ALTTEXT simple utility, std, meta) provided by the standard
         library:
     )
 
     ---
     alias AliasSeq(T...) = T;
     ---
 
-    $(P All it does is give a specific variadic argument list an externally accessible name so
+    $(P All it does is give a specific variadic argument sequence an externally accessible name so
         that it can be worked with in any other context:
     )
 
     ---
     import std.meta;
     // can alias to some other name
     alias Name = AliasSeq!(int, 42);
-    pragma(msg, Name[0]);
-    pragma(msg, Name[1]);
-    // or work with a list directly
-    pragma(msg, AliasSeq!("aaa", 0, double)[2]);
+    pragma(msg, Name[0]);   // int
+    pragma(msg, Name[1]);   // 42
+    // or work with a sequence directly
+    pragma(msg, AliasSeq!("aaa", 0, double)[2]);    // double
     ---
 
 $(H2 $(LNAME2 available-operations, Available operations))
@@ -92,27 +96,27 @@ $(H2 $(LNAME2 available-operations, Available operations))
 
     $(H3 $(LNAME2 assignment, Assignment))
 
-        $(P Works only if the list element is a symbol that refers to a mutable variable)
+        $(P Works only if the sequence element is a symbol that refers to a mutable variable)
 
         ---
         import std.meta;
 
         void main()
         {
             int x;
-            alias List = AliasSeq!(10, x);
-            List[1] = 42;
+            alias seq = AliasSeq!(10, x);
+            seq[1] = 42;
             assert (x == 42);
-            // List[0] = 42; // won't compile, can't assign to a constant
+            // seq[0] = 42; // won't compile, can't assign to a constant
         }
         ---
 
     $(H3 $(LNAME2 loops, Loops))
 
         $(P D's $(LINK2 spec/statement.html#ForeachStatement, foreach statement) has special
-            semantics when iterating over compile-time lists. It repeats the body of the loop
-            for each of the list elements, with the loop iteration "variable" becoming an alias
-            for each compile-time list element in turn.
+            semantics when iterating over compile-time sequences. It repeats the body of the loop
+            for each of the sequence elements, with the loop iteration symbol being an alias
+            for each compile-time sequence element in turn.
         )
 
         ---
@@ -130,17 +134,19 @@ $(H2 $(LNAME2 available-operations, Available operations))
         }
 
         /* Prints:
-
         int
         string
         void()
         */
         ---
 
+        $(P $(B Note:) $(DDSUBLINK version, staticforeach, Static foreach)
+        should be preferred in new code.)
+
 $(H2 $(LNAME2 auto-expansion, Auto-expansion))
 
-    $(P One less obvious property of compile-time argument lists is that when used
-        as an argument to a function or template, they are automatically treated as a list
+    $(P One less obvious property of compile-time argument sequences is that when used
+        as an argument to a function or template, they are automatically treated as a sequence
         of comma-separated arguments:
     )
 
@@ -158,25 +164,29 @@ $(H2 $(LNAME2 auto-expansion, Auto-expansion))
     $(P This will only print `int` during compilation because the last line gets rewritten
         as `alias Dummy = Print0!(int, double)`. If auto-expansion didn't happen,
         `AliasSeq!(int, double)` would be printed instead. This is an inherent part of
-        the language semantics for variadic lists, and thus also preserved by `AliasSeq`.
+        the language semantics for variadic sequences, and thus also preserved by `AliasSeq`.
     )
 
-$(H2 $(LNAME2 homogenous-lists, Homogenous lists))
+$(H2 $(LEGACY_LNAME2 homogenous-lists, homogenous-sequences, Homogenous sequences))
 
-    $(P An `AliasSeq` that consist of only type or expression (value) elements are
-        commonly called "type lists" or "expression lists" respectively. The concept of
-        a "symbol list" is rarely mentioned explicitly but fits the same pattern.
+    $(P An $(ALOCAL AliasSeq, AliasSeq) that consists of only type or value elements are
+        commonly called "type sequences" or "value sequences" respectively. The concept of
+        a "symbol sequence" is used less frequently but fits the same pattern.
     )
 
-    $(P It is possible to use homogenous type lists in declarations:)
+$(H3 $(LNAME2 type-seq, Type sequences))
+
+    $(P It is possible to use homogenous type sequences in declarations:)
 
     ---
     import std.meta;
     alias Params = AliasSeq!(int, double, string);
     void foo(Params); // void foo(int, double, string);
     ---
 
-    $(P D supports a special variable declaration syntax where a type list acts as a type:)
+$(H4 $(LNAME2 type-seq-instantiation, Type sequence instantiation))
+
+    $(P D supports a special variable declaration syntax where a type sequence acts as a type:)
 
     ---
     import std.meta;
@@ -188,35 +198,72 @@ $(H2 $(LNAME2 homogenous-lists, Homogenous lists))
         variables[1] = 42.0;
         variables[2] = "just a normal variable";
     }
-
-    /* The compiler will rewrite such a declaration to something like this:
-
+    ---
+    $(P The compiler will rewrite such a declaration to something like this:)
+    ---
     int __var1;
     double __var2;
     string __var3;
     alias variables = AliasSeq!(__var1, __var2, __var3);
-    */
     ---
 
-    $(P This is also what happens when declaring a variadic template function:)
+    $(P So a type sequence instance is a kind of symbol sequence that only aliases
+    variables, known as an $(I lvalue sequence).)
+
+    $(P $(DDSUBLINK spec/template, variadic-templates, Variadic template functions)
+    use a type sequence instance for a function parameter:)
 
     ---
     void foo(T...)(T args)
     {
-        // 'args' here is a compile-time list of symbols that
-        // refer to underlying compiler-generated arguments
+        // 'T' is a type sequence of argument types.
+        // 'args' is an instance of T whose elements are the function parameters
+        static assert(is(typeof(args) == T));
+        args[0] = T[0].init;
     }
     ---
 
-    $(P It is possible to use expression lists with values of the same type to declare array literals:)
+    $(P $(B Note:) $(REF Tuple, std, typecons) wraps a type sequence instance,
+    preventing auto-expansion, and allowing it to be returned from functions.)
+
+$(H3 $(LNAME2 value-seq, Value sequences))
+
+    $(P It is possible to use a sequence of values of the same type to declare an array literal:)
 
     ---
     import std.meta;
-    static assert ([ AliasSeq!(1, 2, 3) ] == [ 1, 2, 3 ]);
+    enum e = 3;
+    enum arr = [ AliasSeq!(1, 2, e) ];
+    static assert(arr == [ 1, 2, 3 ]);
+    ---
+
+    $(P The above sequence is an $(I rvalue sequence), as it is comprised only of literal values
+    and manifest constants. Each element's value is known at compile-time.)
+
+    $(P The following demonstrates use of an $(I lvalue sequence):)
     ---
+    import std.meta, std.algorithm;
+    auto x = 3, y = 7;
+    alias pair = AliasSeq!(x, y);
+    swap(pair);
+    assert(x == 7 && y == 3);
+    ---
+    $(P As above, such sequences may use $(ALOCAL assignment, assignment).)
+
+$(H4 $(LNAME2 tupleof, Aggregate field sequences))
+
+    $(P $(DDSUBLINK spec/class, class_properties, `.tupleof`) is a
+    class/struct instance property that provides an lvalue sequence
+    of each field.)
+
+$(H3 $(LNAME2 symbol-seq, Symbol sequences))
+
+$(P A symbol sequence aliases any named symbol - types, variables, functions and templates -
+but not literals.
+Like an alias sequence, the kind of elements can be mixed.)
 
 )
 
 Macros:
-    TITLE=Compile-time Argument Lists
+    TITLE=Compile-time Sequences
     SUBNAV=$(SUBNAV_ARTICLES)

articles/index.dd

@@ -129,10 +129,9 @@ $(D_S Articles,
                     templates.)
             )
             $(DIVC item,
-                $(H4 $(LINK2 $(ROOT_DIR)articles/ctarguments.html, Compile-time Argument
-                    Lists))
-                $(P A compile-time list is a list of compile-time entities -
-                    types, symbols (names) and expressions (values). This
+                $(H4 $(LINK2 $(ROOT_DIR)articles/ctarguments.html, Compile-time Sequences))
+                $(P A compile-time sequence is a sequence of compile-time entities -
+                    types, symbols (names) and values. This
                     article shows how to work with them.)
             )
         )

dlang.org.ddoc

@@ -475,7 +475,7 @@ $(SUBNAV_TEMPLATE
         $(ROOT_DIR)articles/regular-expression.html, Regular Expressions,
         $(ROOT_DIR)articles/safed.html, SafeD,
         $(ROOT_DIR)articles/templates-revisited.html, Templates Revisited,
-        $(ROOT_DIR)articles/ctarguments.html, Compile-time Argument Lists,
+        $(ROOT_DIR)articles/ctarguments.html, Compile-time Sequences,
         $(ROOT_DIR)articles/variadic-function-templates.html, Variadic Templates,
         $(ROOT_DIR)articles/d-array-article.html, D Slices,
         $(ROOT_DIR)articles/cppcontracts.html, D's Contract Programming,

tuple.dd

@@ -3,7 +3,7 @@ Ddoc
 For documentation on tuples that are commonly present in other languages (anonymous runtime entity that groups
 different values) refer to $(LINK2 phobos/std_typecons.html#tuple, Phobos documentation on std.typecons.tuple)
 
-You may be also looking for documentation for built-in $(LINK2 ctarguments.html, compile-time argument lists)
+You may be also looking for documentation for built-in $(LINK2 ctarguments.html, compile-time sequences)
 which can be sometimes referred as "tuples" too (though it is discouraged).
 
 Macros: