Menu

- Learn
- Documentation
  - Language Reference
  - Library Reference
  - Command-line Reference
  - Feature Overview
  - Articles
- Downloads
- Packages
- Community
  - Blog
  - Orgs using D
  - Twitter
  - Calendar
  - Forums
  - IRC
  - Community Discord
  - Wiki
  - GitHub
  - Issues
  - Get involved
  - Contributors
  - Foundation
  - Security Team
  - Donate
  - Sponsors
- Resources
  - Tour
  - Books
  - Tutorials
  - Tools
  - Editors
  - IDEs
  - run.dlang.io
  - Visual D
  - Acknowledgments
  - D Style
  - Glossary
  - Sitemap

Search
Report a bug
If you spot a problem with this page, click here to create a Bugzilla issue.
Improve this page
Quickly fork, edit online, and submit a pull request for this page. Requires a signed-in GitHub account. This works well for small changes. If you'd like to make larger changes you may want to consider using a local clone.

# Template Constraints

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 argument must match particular type patterns. Similarly, template value arguments can be constrained to match particular types.

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:

- more finely discriminate about which template gets instantiated for given arguments
- provides better self-documentation about what characteristics template parameters must have
- can 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

Constraints address this by simply providing an expression that must evaluate at compile time to true 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.

The constraint expression follows the template declaration and the if keyword:

    template Foo(int N)
        if (N & 1)
    {
        ...
    }

which constrains the template Foo to match only if its argument is an odd integer. 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:

    bool isPrime(int n)
    {
        if (n == 2)
            return true;
        if (n < 1 || (n & 1) == 0)
            return false;
        if (n > 3)
        {
            for (auto i = 3; i * i <= n; i += 2)
            {
                if ((n % i) == 0)
                    return false;
            }
        }
        return true;
    }

    template Foo(int N)
        if (isPrime(N))
    {
        ...
    }

    Foo!(5)    // ok, 5 is prime
    Foo!(6)    // no match for Foo

Type constraints can be complex, too. For example, a template Bar that will accept any floating point type using the traditional type specializations:

    template Bar(T:float)
    {
        ...
    }
    template Bar(T:double)
    {
        ...
    }
    template Bar(T:real)
    {
        ...
    }

and the template implementation body must be duplicated three times. But with constraints, this can be specified with one template:

    template Bar(T)
        if (is(T == float) || is(T == double) || is(T == real))
    {
        ...
    }

This can be simplified by using the isFloatingPoint template in library module std.traits:

    import std.traits;
    template Bar(T)
        if (isFloatingPoint!(T))
    {
        ...
    }

Characteristics of types can be tested, such as if a type can be added:

    // 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; });
    }

    int Foo(T)(T t)
        if (isAddable!(T))
    {
        return 3;
    }

    struct S
    {
        void opAdd(S s) { }   // an addable struct type
    }

    void main()
    {
        Foo(4);   // succeeds
        S s;
        Foo(s);   // succeeds
        Foo("a"); // fails to match
    }

Since any expression that can be computed at compile time is allowed as a constraint, constraints can be composed:

    int Foo(T)(T t)
        if (isAddable!(T) && isMultipliable!(T))
    {
        return 3;
    }

A more complex constraint can specify a list of operations that must be doable with the type, such as isStack which specifies the constraints that a stack type must have:

    template isStack(T)
    {
        const isStack =
            __traits(compiles,
                (T t)
                {
                    T.value_type v = top(t);
                    push(t, v);
                    pop(t);
                    if (empty(t)) { }
                });
    }

    template Foo(T)
        if (isStack!(T))
    {
        ...
    }

and constraints can deal with multiple parameters:

    template Foo(T, int N)
        if (isAddable!(T) && isprime(N))
    {
        ...
    }

## Overloading based on Constraints

Given a list of overloaded templates with the same name, constraints act as a yes/no filter to determine the list of candidates for a match. Overloading based on constraints can thus be achieved by setting up constraint expressions that are mutually exclusive. For example, overloading template Foo so that one takes odd integers and the other even:

    template Foo(int N) if (N & 1)    { ... } // A
    template Foo(int N) if (!(N & 1)) { ... } // B
    ...
    Foo!(3)    // instantiates A
    Foo!(64)   // instantiates B

Constraints are not involved with determining which template is more specialized than another.

    void foo(T, int N)()        if (N & 1) { ... } // A
    void foo(T : int, int N)()  if (N > 3) { ... } // B
    ...
    foo!(int, 7)();   // picks B, more specialized
    foo!(int, 1)();   // picks A, as it fails B's constraint
    foo!("a", 7)();   // picks A
    foo!("a", 4)();   // error, no match

## References

- Concepts (Revision 1) by Douglas Gregor and Bjarne Stroustrup

Copyright © 1999-2021 by the D Language Foundation | Page generated by Ddoc on Fri Jan 1 12:57:24 2021