Merge remote-tracking branch 'upstream/master' into stable

Author: ibuclaw

.circleci/config.yml

@@ -4,6 +4,7 @@ jobs:
     working_directory: ~/dlang.org
     docker:
       - image: cimg/base:current-20.04
+    resource_class: medium+
     parallelism: 1
     steps:
       - checkout

.htaccess

@@ -71,6 +71,7 @@ Redirect 301 /donate.html https://dlang.org/foundation/donate.html
 Redirect 301 /articles.html /articles/index.html
 Redirect 301 /builtin.html /articles/builtin.html
 Redirect 301 /code_coverage.html /articles/code_coverage.html
+Redirect 301 /concepts.html /articles/constraints.html
 Redirect 301 /const-faq.html /articles/const-faq.html
 Redirect 301 /cppcontracts.html /articles/cppcontracts.html
 Redirect 301 /cpptod.html /articles/cpptod.html

ads.txt

@@ -0,0 +1 @@
+google.com, pub-7775438694241734, DIRECT, f08c47fec0942fa0

concepts.dd renamed to articles/constraints.dd

@@ -4,33 +4,44 @@ $(D_S Template Constraints,
 
         $(P Templates are normally overloaded and matched based on the
         template arguments being matched to the template parameters.
-        The template parameters can specify specializations, so that
+        The template parameters can specify
+        $(DDSUBLINK spec/template, parameters_specialization, specializations), so that
         the template argument must match particular type patterns.
         Similarly, template value arguments can be constrained to
         match particular types.)
 
+---
+template Foo(T) { ... }
+template Foo(T : T*) { ... }
+template Foo(T : T[]) { ... }
+
+alias f1 = Foo!(int);   // picks Foo(T)
+alias f2 = Foo!(int*);  // picks Foo(T : T*)
+alias f3 = Foo!(int[]); // picks Foo(T : T[])
+---
+
         $(P But this has its limitations. Many times there are
         arbitrarily more
         complex criteria for what should be accepted by the template.
-        This can be used to:
+        Such criteria could be to:
         )
 
         $(UL
         $(LI more finely discriminate about which
          template gets instantiated for given arguments)
-        $(LI provides better self-documentation about what
+        $(LI provide better self-documentation about what
          characteristics template parameters must have)
-        $(LI can provide better diagnostics when arguments don't match,
+        $(LI provide better diagnostics when arguments don't match,
          rather than an obscure error message based on the irrelevant
          (to the user) internal details of the template implementation)
         )
 
-        $(P Constraints address this by simply providing an
-        expression that must evaluate at compile time to true
+        $(P Constraints address this by simply providing a boolean
+        expression that is evaluated at compile-time,
         after the arguments are matched to the parameters.
-        If it is true, then that template is a valid match for
-        the arguments, if not, then it is not and is passed over
-        during overload matching.)
+        If that boolean is true, then the template is a valid match for
+        the arguments, if not, then the template does not match and
+        is passed over during overload matching.)
 
         $(P The constraint expression follows the template declaration
         and the $(CODE if) keyword:)
@@ -45,20 +56,27 @@ template Foo(int N)
 
         $(P which constrains the template $(CODE Foo) to match only if its
         argument
-        is an odd integer. Arbitrarily complex criteria can be used, as
+        is an odd integer.)
+
+$(H2 $(LNAME2 predicates, Predicate Functions))
+
+        $(P Arbitrarily complex criteria can be used, as
         long as it can be computed at compile time. For example, here's
         a template that only accepts prime numbers:
         )
 
+$(RUNNABLE_EXAMPLE_COMPILE
 ---
 bool isPrime(int n)
 {
     if (n == 2)
         return true;
+    // 0, negative and even numbers are not prime
     if (n < 1 || (n & 1) == 0)
         return false;
     if (n > 3)
     {
+        // check possible odd integer denominators
         for (auto i = 3; i * i <= n; i += 2)
         {
             if ((n % i) == 0)
@@ -71,16 +89,22 @@ bool isPrime(int n)
 template Foo(int N)
     if (isPrime(N))
 {
-    ...
+    // ...
 }
 
-Foo!(5)    // ok, 5 is prime
-Foo!(6)    // no match for Foo
+alias f1 = Foo!(5);    // ok, 5 is prime
+//alias f2 = Foo!(6);    // error: no match for Foo
+//alias f3 = Foo!(9);    // error: no match for Foo
 ---
+)
+
+        $(NOTE `isPrime` is called using $(DDSUBLINK spec/function, interpretation, Compile-Time Function Evaluation).)
 
-        $(P Type constraints can be complex, too. For example, a template
-        Bar that will accept any floating point type using the traditional
-        type specializations:
+$(H2 $(LNAME2 is, `is` Expressions))
+
+        $(P Type constraints can be complex, too. With type specialization alone, a template
+        `Bar` that will accept any type that implicitly converts to a built-in floating
+        point type must use template overloads:
         )
 ---
 template Bar(T:float)
@@ -102,84 +126,127 @@ template Bar(T:real)
         )
 ---
 template Bar(T)
-    if (is(T == float) || is(T == double) || is(T == real))
+    if (is(T : float) || is(T : double) || is(T : real))
 {
     ...
 }
 ---
-        $(P This can be simplified by using the $(CODE isFloatingPoint)
-        template in library module $(CODE std.traits):
+        $(P Unlike with parameter specialization, types with implicit conversion to
+        floating point can be ruled out with a different constraint:)
+
+$(RUNNABLE_EXAMPLE_COMPILE
+---
+template Bar(T)
+    if (is(T == float) || is(T == double) || is(T == real))
+{
+    // ...
+}
+
+alias b1 = Bar!float; // OK
+//alias b2 = Bar!int;   // error
+---
+)
+        $(P See $(GLINK2 expression, IsExpression) for more tests.)
+
+        $(P The above example can be simplified by using the $(CODE isFloatingPoint)
+        template in library module $(MREF std, traits):
         )
 ---
 import std.traits;
+
 template Bar(T)
     if (isFloatingPoint!(T))
 {
     ...
 }
 ---
 
+$(H2 $(LNAME2 traits, `__traits`))
+
         $(P Characteristics of types can be tested, such as if
-        a type can be added:
+        a type instance can be added:
         )
 
+$(RUNNABLE_EXAMPLE
 ---
 // Returns true if instances of type T can be added
-template isAddable(T)
-{
-    // Works by attempting to add two instances of type T
-    const isAddable = __traits(compiles, (T t) { return t + t; });
-}
+// Works by attempting to add two instances of type T
+const isAddable(T) = __traits(compiles, (T t) { return t + t; });
 
-int Foo(T)(T t)
+auto twice(T)(T t)
     if (isAddable!(T))
 {
-    return 3;
+    return t + t;
 }
 
+// an addable struct type
 struct S
 {
-    void opAdd(S s) { }   // an addable struct type
+    int i;
+
+    S opBinary(string op : "+")(S s)
+    {
+        return S(i + s.i);
+    }
 }
 
 void main()
 {
-    Foo(4);   // succeeds
-    S s;
-    Foo(s);   // succeeds
-    Foo("a"); // fails to match
+    assert(twice(4) == 8);
+    S s = {2};
+    assert(twice(s).i == 4);
+    //twice("a"); // fails to match
 }
 ---
+)
+
+        $(P $(DDSUBLINK spec/traits, compiles, `__traits(compiles)`) is
+        used to check if a function literal successfully compiles. Other
+        expressions can be used instead of a function literal. The expression
+        is not evaluated.
+        Other compile-time `__traits` $(DDLINK spec/traits, Traits, are available).)
+
+        $(NOTE The function literal above declares an argument of type
+        `T` to obtain an instance of `T` without having to construct it.)
 
         $(P Since any expression that can be computed at compile time
         is allowed as a constraint, constraints can be composed:
         )
 
 ---
-int Foo(T)(T t)
+T foo(T)(T t)
     if (isAddable!(T) && isMultipliable!(T))
 {
-    return 3;
+    return t + t * t;
 }
 ---
 
-        $(P A more complex constraint can specify a list of operations
-        that must be doable with the type, such as $(CODE isStack) which
-        specifies the constraints that a stack type must have:)
+        $(P Constraints can deal with multiple parameters:)
 
-----
-template isStack(T)
+---
+template Foo(T, int N)
+    if (isAddable!(T) && isPrime(N))
 {
-    const isStack =
-        __traits(compiles,
-            (T t)
-            {
-                T.value_type v = top(t);
-                push(t, v);
-                pop(t);
-                if (empty(t)) { }
-            });
+    ...
 }
+---
+
+        $(P A more complex constraint can specify a list of operations
+        that must be doable with the type, such as evaluating template $(CODE isStack) which
+        requires that the type has a type property `ValueType`, and that 4 functions
+        exist which take an instance of the type, 2 of which return certain
+        values:)
+
+----
+const isStack(T) =
+    __traits(compiles,
+        (T t)
+        {
+            T.ValueType v = top(t);
+            push(t, v);
+            pop(t);
+            if (empty(t)) { }
+        });
 
 template Foo(T)
     if (isStack!(T))
@@ -188,17 +255,7 @@ template Foo(T)
 }
 ----
 
-        $(P and constraints can deal with multiple parameters:)
-
----
-template Foo(T, int N)
-    if (isAddable!(T) && isprime(N))
-{
-    ...
-}
----
-
-$(H2 Overloading based on Constraints)
+$(H2 $(LNAME2 overloading, Overloading based on Constraints))
 
         $(P Given a list of overloaded templates with the same name,
         constraints act as a yes/no filter to determine the list
@@ -216,6 +273,17 @@ Foo!(3)    // instantiates A
 Foo!(64)   // instantiates B
 ---
 
+        $(P Note the above 2 templates could be combined using
+        $(DDSUBLINK spec/version, staticif, `static if`):)
+---
+template Foo(int N)
+{
+    static if (N & 1)
+        // body of A
+    else
+        // body of B
+}
+---
         $(P Constraints are not involved with determining which
         template is more specialized than another.
         )

articles/index.dd

@@ -128,20 +128,35 @@ $(D_S Articles,
                 $(P Walter Bright writes about how D improves upon C++
                     templates.)
             )
+            $(DIVC item,
+                $(H4 $(LINK2 $(ROOT_DIR)articles/constraints.html,
+                    Template Constraints))
+                $(P A template can be constrained to only apply when a compile-time
+                    evaluable boolean expression is true.)
+            )
+        )
+        $(DIVC row,
             $(DIVC item,
                 $(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.)
             )
-        )
-        $(DIVC row,
             $(DIVC item,
                 $(H4 $(LINK2 $(ROOT_DIR)articles/variadic-function-templates.html,
                     Variadic Templates))
                 $(P This article is about the D idiom of implementing variadic
                    functions with variadic templates.)
             )
+        )
+        $(DIVC row,
+            $(DIVC item,
+                $(H4 $(LINK2 $(ROOT_DIR)articles/template-comparison.html,
+                    Template Comparison))
+                $(P
+                    A comparison between D's and C++'s templates.
+                )
+            )
             $(DIVC item,
                 $(H4 $(LINK2 $(ROOT_DIR)articles/d-array-article.html, D Slices))
                 $(P Steven Schveighoffer writes about slices and dynamic arrays
@@ -162,15 +177,6 @@ $(D_S Articles,
                     A comparison between D's and C++'s contract programming.
                 )
             )
-            $(DIVC item,
-                $(H4 $(LINK2 $(ROOT_DIR)articles/template-comparison.html,
-                    Template Comparison))
-                $(P
-                    A comparison between D's and C++'s templates.
-                )
-            )
-        )
-        $(DIVC row,
             $(DIVC item,
                 $(H4 $(LINK2 $(ROOT_DIR)articles/dll-linux.html,
                     Writing Shared Libraries on Linux))