Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/pfultz2/tick
Trait introspection and concept creator for C++11
https://github.com/pfultz2/tick
c-plus-plus c-plus-plus-11 concepts cpp cpp11 cpp14 modern
Last synced: 3 months ago
JSON representation
Trait introspection and concept creator for C++11
- Host: GitHub
- URL: https://github.com/pfultz2/tick
- Owner: pfultz2
- License: bsl-1.0
- Created: 2014-05-20T21:01:07.000Z (over 10 years ago)
- Default Branch: master
- Last Pushed: 2017-12-04T15:51:47.000Z (about 7 years ago)
- Last Synced: 2024-07-31T22:52:51.114Z (6 months ago)
- Topics: c-plus-plus, c-plus-plus-11, concepts, cpp, cpp11, cpp14, modern
- Language: C++
- Homepage: http://tickcpp.readthedocs.io/en/latest/doc/
- Size: 595 KB
- Stars: 183
- Watchers: 23
- Forks: 18
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
Tick
====
Trait introspection and concept creator for C++11
Getting Started
===============
Tick provides a mechanism for easily defining and using traits in C++11. For example, if we defined a generic `increment` function, like this:
```cpp
template
void increment(T& x)
{
x++;
}
```
If we pass something that does not have the `++` operator to `increment`, we will get an error inside of the `increment` function. This can make it unclear whether the error is due to a mistake by the user of the function or by the implementor of the function. Instead we want to check the type requirements of the function.
Using Tick we can create an `is_incrementable` trait, like this:
```cpp
TICK_TRAIT(is_incrementable)
{
template
auto require(T&& x) -> valid<
decltype(x++),
decltype(++x)
>;
};
```
And then we can use a simple requires clause in our function to check the type requirements:
```cpp
template())>
void increment(T& x)
{
x++;
}
```
So, now, if we pass something that is not incrementable to `increment`:
```cpp
struct foo {};
foo f;
increment(f);
```
Then we get an error like this in clang:
demo.cpp:25:2: error: no matching function for call to 'increment'
increment(f);
^~~~~~~~~
demo.cpp:14:19: note: candidate template ignored: disabled by 'enable_if' [with T = foo]
template())>
^
This gives an error at the call to `increment` rather than inside the function, and then pointes to the type requirements of the function. This gives enough information for most commons cases, however, sometimes we may want more information. In that case the `TICK_TRAIT_CHECK` can be used. For example, say we had the `is_incrementable` trait defined like this:
```cpp
TICK_TRAIT(is_incrementable, std::is_integral<_>)
{
template
auto require(T&& x) -> valid<
decltype(x++),
decltype(++x)
>;
};
```
Then if we use `TICK_TRAIT_CHECK`, we can see why `int*` is not incrementable:
```cpp
TICK_TRAIT_CHECK(is_incrementable);
```
Which will produce this error:
../tick/trait_check.h:95:38: error: implicit instantiation of undefined template 'tick::TRAIT_CHECK_FAILURE, is_incrementable >'
Which shows the traits that failed including any refinements. So we can see that it failed because `std::is_integral` is not true.
Building traits
===============
This macro will build a boolean type trait for you. Each trait has a `require` member function of the form:
```cpp
TICK_TRAIT(my_trait)
{
template
auto require(T&& x) -> valid<
...
>;
};
```
This will essentially build a class that inherits from `integral_constant`, so the above is equivalent to this:
```cpp
template
struct my_trait
: integral_constant
{};
```
The parameters to the trait are based on the parameters passed to the `require` function.
The trait will be either true or false if the expressions given are valid. Each expression in `valid` needs a `decltype` around it. If one of the expressions is not valid, the the trait will return false. For example,
```cpp
TICK_TRAIT(my_trait)
{
template
auto require(T&& x) -> valid<
decltype(x++)
>;
};
```
The trait above will check that `x++` is a valid expression.
Refinements
-----------
Refinements can be expressed after the name. Each refinement is a [placeholder expression](http://www.boost.org/doc/libs/1_55_0/libs/mpl/doc/refmanual/placeholder-expression.html), where each placeholder(ie `_1`, `_2`, etc) are replaced by their corresponding type passed into the trait. In the case of traits that accept a single parameter the unnamed placeholder(`_`) can be used, for example:
```cpp
TICK_TRAIT(is_incrementable, std::is_default_constructible<_>)
{
template
auto require(T&& x) -> valid<
decltype(x++),
decltype(++x)
>;
};
```
This trait will be true when `x++` and `++x` are valid expressions and `x` is default constructible.
When a trait has multiple parameters, its best to use named placeholders. For example:
```cpp
TICK_TRAIT(is_equality_comparable,
std::is_default_constructible<_1>,
std::is_default_constructible<_2>)
{
template
auto require(T&& x, U&& y) -> valid<
decltype(x == y),
decltype(x != y)
>;
};
```
This trait will be true when `x == y` and `x != y` are valid expressions and both `x` and `y` are default constructible.
In addition `quote` can be used to pass all the args from the trait to the refinement:
```cpp
TICK_TRAIT(is_comparable,
quote)
{
template
auto require(T&& x, U&& y) -> valid<
decltype(x < y),
decltype(x <= y),
decltype(x >= y),
decltype(x > y)
>;
};
```
Query operations
================
These can be used to query more information about the types then just valid expressions.
Type matching
-------------
When a type is matched, it can either be convertible to the type given, or the evaluated placeholder expression must be true. Placeholder expressions can be given so the type can be matched against other traits.
returns
-------
The `returns` query can check if the result of the expressions matches the type. For example,
```cpp
TICK_TRAIT(is_incrementable)
{
template
auto require(T&& x) -> valid<
decltype(returns(x++))
>;
};
```
This trait will be true if the expressions `x++` is valid and is convertible to `int`.
Here's an example using placeholder expressions as well:
```cpp
TICK_TRAIT(is_incrementable)
{
template
auto require(T&& x) -> valid<
decltype(returns>(x++))
>;
};
```
This trait will be true if the expressions `x++` is valid and returns a type that `is_integral`.
Note: The `TICK_RETURNS` macro can be used instead to improve compatability with older compilers(such as gcc 4.6):
```cpp
TICK_TRAIT(is_incrementable)
{
template
auto require(T&& x) -> valid<
TICK_RETURNS(x++, int)
>;
};
```
Also, `returns` is prohibited.
```cpp
TICK_TRAIT(is_incrementable)
{
template
auto require(T&& x) -> valid<
decltype(returns(x++)) // Compiler error
>;
};
```
Instead, use either `decltype` directly without `returns`, or if there is a possibility of `void` from a computed type, use `TICK_RETURNS` or `has_type` instead.
has_type
--------
The `has_type` query can check if a type exist and if the type matches. For example:
```cpp
TICK_TRAIT(has_nested_type)
{
template
auto require(const T& x) -> valid<
has_type
>;
};
```
This trait will be true if `T` has a nested type called `type`.
Now `has_type` used as above is not quite as useful since the above example, can also be simply written without `has_type` like this:
```cpp
TICK_TRAIT(has_nested_type)
{
template
auto require(const T& x) -> valid<
typename T::type
>;
};
```
So, an optional second parameter can be provided to check if the type matches. Here's an example:
```cpp
TICK_TRAIT(has_nested_int_type)
{
template
auto require(const T& x) -> valid<
has_type>
>;
};
```
This trait will be true if `T` has a nested type called `type` which is an integral type.
has_template
------------
The `has_template` query can check if a template exist. For example:
```cpp
TICK_TRAIT(has_nested_result)
{
template
auto require(const T& x) -> valid<
has_template
>;
};
```
This trait will be true if `T` has a nested template called `result`.
Trait evaluation
----------------
The `is_true` and `is_false` queries can check if a trait is true or false. Using refinements is the preferred way of checking for additional traits, but this can be useful if the evaluation of some trait can't be used lazily with placeholder expressions. So the `is_true` and `is_false` can be used instead, for example:
```cpp
TICK_TRAIT(is_2d_array)
{
template
auto require(const T& x) -> valid<
is_true::type, std::integral_constant> >
>;
};
```
Helper functions
----------------
The library also provides `as_const` and `as_mutable` functions to ensure lvalues are either `const` or `mutable` respectively:
```cpp
TICK_TRAIT(is_copy_assignable)
{
template
auto require(T&& x) -> valid<
decltype(x = as_const(x))
>;
};
```
Build traits without macros
===========================
The traits can be built without using the `TICK_TRAIT` macros. However, it may introduce problems with portability. So if only one platform is needed to be supported, then here's how to build them. First, build a class for the `require` functions and inherit from `tick::ops` to bring in all the query operations:
```cpp
struct is_incrementable_r : tick::ops
{
template
auto require(T&& x) -> valid<
decltype(x++),
decltype(++x)
>;
};
```
Next, turn it into a trait using `tick::models`:
```cpp
template
struct is_incrementable
: tick::models
{};
```
Refinements
-----------
Refinements can be used by using the `tick::refines` class:
```cpp
struct is_incrementable_r
: tick::ops, tick::refines>
{
template
auto require(T&& x) -> valid<
decltype(x++),
decltype(++x)
>;
};
```
Notice, the placeholders have to be fully qualified here.
Template constraints
====================
Three macros are provided to help improve the readability of template constraints.
TICK_REQUIRES
-------------
The `TICK_REQUIRES` can be used on template parameters. For example,
```cpp
template())>
void increment(T& x)
{
x++;
}
```
TICK_CLASS_REQUIRES
-------------------
The `TICK_CLASS_REQUIRES` can be used when template specialization is done on classes. For example,
```cpp
template
struct foo
{
...
};
template
struct foo() and not std::is_integral())>
{
...
};
template
struct foo())>
{
...
};
```
TICK_MEMBER_REQUIRES
--------------------
The `TICK_MEMBER_REQUIRES` can be used for member function inside of classes, that are not templated. For example,
```cpp
template
struct foo
{
T x;
TICK_MEMBER_REQUIRES(is_incrementable())
void up()
{
x++;
}
};
```
TICK_PARAM_REQUIRES
--------------------
The `TICK_PARAM_REQUIRES` can be used in the paramater of the function. This is useful for lambdas:
```cpp
auto increment = [](auto& x, TICK_PARAM_REQUIRES(is_incrementable()))
{
x++;
};
```
Also, the `trait` function is provided which can be used to deduce the type of the parameters:
```cpp
auto increment = [](auto& x, TICK_PARAM_REQUIRES(trait(x)))
{
x++;
};
```
Note: The `trait` function always deduces the type without references. So `trait(x)` will always be false.
TICK_FUNCTION_REQUIRES
----------------------
The `TICK_FUNCTION_REQUIRES` can be used on functions. This requires placing parenthesis around the return type:
```cpp
template
TICK_FUNCTION_REQUIRES(is_incrementable())
(void) increment(T& x)
{
x++;
}
```
Note: The `TICK_REQUIRES` should be preferred.
Trait checking
==============
The `TICK_TRAIT_CHECK` macro will statically assert the list of traits that are true but it will show what traits failed including base traits. This can be useful to show more informative messages about why a trait is false.
Requirements
============
This requires a C++11 compiler. There a no third-party dependencies. This has been tested on clang 3.4, gcc 4.6-4.9, and Visual Studio 2015.
ZLang support
=============
[ZLang](https://github.com/pfultz2/ZLang) is supported for some of the macros. The macros are in the `tick` namespace. For example,
```cpp
$(trait is_incrementable)
{
template
auto require(T&& x) -> valid<
decltype(x++),
decltype(++x)
>;
};
```
Acknowledgments
===============
* Eric Niebler for the idea of using a `requires` member function to check concept traits.[http://ericniebler.com/2013/11/23/concept-checking-in-c11/]
* Jamboree for the idea of using a template class to place expressions.[https://github.com/ericniebler/range-v3/issues/29#issuecomment-51016277]