dlib C++ Library - Metaprogramming

Metaprogramming

This page documents library components that provide metaprogramming sorts of functionality. For the most part they are useful for putting design by contract checks into code or doing various kinds of clever things with templates.

For example, you might have a templated function that is templated on a type T and you want to make sure that T is either a char or wchar_t type. You could place the following into your code and it would cause the compile to error out when T was set to something other than char or wchar_t.
`static_assert(is_same_type<T,char>::value || is_same_type<T,wchar_t>::value, "Should be a char type");`

[top]

# And

This template takes a list of bool values and yields their logical and. E.g. And<true,true,true>::value == true And<true,false,true>::value == false
More Details...
#include <dlib/type_traits.h>
[top]

# are_nothrow_copy_assignable

A type trait class telling you if all the types given to it are no-throw copy assignable.
More Details...
#include <dlib/type_traits.h>
[top]

# are_nothrow_copy_constructible

A type trait class telling you if all the types given to it are no-throw copy constructable.
More Details...
#include <dlib/type_traits.h>
[top]

# are_nothrow_move_assignable

A type trait class telling you if all the types given to it are no-throw move assignable.
More Details...
#include <dlib/type_traits.h>
[top]

# are_nothrow_move_constructible

A type trait class telling you if all the types given to it are no-throw move constructable.
More Details...
#include <dlib/type_traits.h>
[top]

# are_nothrow_swappable

A type trait telling you if a list of types are all no-throw swappable.
More Details...
#include <dlib/type_traits.h>
[top]

# ASSERT_ARE_NOT_SAME_TYPE

This is a macro function for debugging. Its form is `ASSERT_ARE_NOT_SAME_TYPE(type1, type2)`. If type1 and type2 are the same type then the compile will fail. This is sometimes useful in validating template arguments.

More Details...
#include <dlib/assert.h>
[top]

# ASSERT_ARE_SAME_TYPE

This is a macro function for debugging. Its form is `ASSERT_ARE_SAME_TYPE(type1, type2)`. If type1 and type2 are not the same type then the compile will fail. This is sometimes useful in validating template arguments.

More Details...
#include <dlib/assert.h>
[top]

# assign_zero_if_built_in_scalar_type

This function assigns its argument the value of 0 if it is a built in scalar type according to the is_built_in_scalar_type template. If it isn't a built in scalar type then it does nothing.

This function is useful for suppressing compiler warnings about uninitialized types inside of templates that are designed to accept the built in types as well as user defined classes.

More Details...
#include <dlib/algs.h>
[top]

# callable_traits

This traits class gives will tell you about the various properties of a function or otherwise callable type. Like what it returns, how many arguments it has, and so forth.
More Details...
#include <dlib/type_traits.h>
[top]

# compile_time_integer_list

This is a variadic template that can represent a list of integers.
More Details...
#include <dlib/metaprogramming.h>
[top]

# conjunction

Takes a list of type traits and gives you the logical AND of them.
More Details...
#include <dlib/type_traits.h>
[top]

# DLIB_ASSERT

This is a macro function for debugging. Its form is

    DLIB_ASSERT(condition that should be true, error message)

or you can omit the error message and call it like:

    DLIB_ASSERT(condition that should be true)

If the condition is false DLIB_ASSERT throws an exception of type dlib::fatal_error with fatal_error::type == EBROKEN_ASSERT. An error message detailing the nature of the problem is stored in the member variable info which is of type std::string. Look in the following file for more details. The exception classes are defined here.

This macro is only enabled if _DEBUG, DEBUG or ENABLE_ASSERTS is defined. Also, if this macro is enabled then ENABLE_ASSERTS will be defined even if you didn't define it.

Note that when this macro fails and throws an exception it also calls the global C function dlib_assert_breakpoint(). This behavior makes it easy to set a debugging tool to break when DLIB_ASSERT fails by setting a breakpoint on dlib_assert_breakpoint().

More Details...
#include <dlib/assert.h>
[top]

# DLIB_ASSERT_HAS_STANDARD_LAYOUT

This macro is meant to cause a compiler error if a type doesn't have a simple memory layout (like a C struct). In particular, types with simple layouts are ones which can be copied via memcpy().

This was called a POD type in C++03 and in C++0x we are looking to check if it is a "standard layout type". Once we can use C++0x we can change this macro to something that uses the std::is_standard_layout type_traits class. See: http://www2.research.att.com/~bs/C++0xFAQ.html#PODs
More Details...
#include <dlib/assert.h>
[top]

# DLIB_CASSERT

This is a macro function that is identical to the DLIB_ASSERT macro except that it is always enabled. Even if _DEBUG, DEBUG and ENABLE_ASSERTS are not defined.

Note that when this macro fails and throws an exception it also calls the global C function dlib_assert_breakpoint(). This behavior makes it easy to set a debugging tool to break when DLIB_CASSERT fails by setting a breakpoint on dlib_assert_breakpoint().

More Details...
#include <dlib/assert.h>
[top]

# DLIB_MAKE_HAS_MEMBER_FUNCTION_TEST

The DLIB_MAKE_HAS_MEMBER_FUNCTION_TEST() macro is used to define traits templates that tell you if a class has a certain member function. For example, to make a test to see if a class has a public method with the signature void print(int) you would say:

> `DLIB_MAKE_HAS_MEMBER_FUNCTION_TEST(has_print, void, print, (int))`

Then you can check if a class, T, has this method by looking at the boolean value:

> `has_print<T>::value`

which will be true if the member function is in the T class.
More Details...
#include <dlib/algs.h>
[top]

# DLIB_STACK_TRACE

This is a preprocessor macro that allows you to tag a function so that dlib will keep track of it in a function call stack. That is, you will be able to see a stack trace by calling get_stack_trace if you put this macro at the top of your functions.

This macro is only enabled if DLIB_ENABLE_STACK_TRACE is defined. If it isn't defined then this macro doesn't do anything. Also note that when this macro is defined it will cause DLIB_ASSERT and DLIB_CASSERT to include a stack trace in their error messages.

More Details...
#include <dlib/assert.h>
[top]

# DLIB_STACK_TRACE_NAMED

This is a preprocessor macro just like DLIB_STACK_TRACE except that it allows you to supply your own string to use as the function name in the stack trace instead of the one deduced by DLIB_STACK_TRACE.

This macro is only enabled if DLIB_ENABLE_STACK_TRACE is defined.

More Details...
#include <dlib/assert.h>
[top]

# enable_if

This is a family of templates from the Boost C++ libraries that makes it somewhat easier to control template specialization. For the details see this page. Note that the header `dlib/enable_if.h` brings these templates into the dlib namespace.
#include <dlib/enable_if.h>
[top]

# get_stack_trace

This function allows you to query the current stack trace.

This macro is only enabled if DLIB_ENABLE_STACK_TRACE is defined.

More Details...
#include <dlib/assert.h>
[top]

# is_any_type

This is a template that tells you if a type appears in a list of other types.
More Details...
#include <dlib/type_traits.h>
[top]

# is_array

This is a template where is_array<T>::value == true when T is an array object.
More Details...
#include <dlib/is_kind.h>
[top]

# is_array2d

This is a template where is_array2d<T>::value == true when T is an array2d object.
More Details...
#include <dlib/is_kind.h>
[top]

# is_built_in_scalar_type

This is a template where is_built_in_scalar_type<T>::value == true when T is a built in scalar type such as int, char, float, etc.
More Details...
#include <dlib/type_traits.h>
[top]

# is_byte

Tells you if a type is one of the C++ byte types (e.g. is is T a char?).
More Details...
#include <dlib/type_traits.h>
[top]

# is_complete_type

Tells you if a type is a complete type.
More Details...
#include <dlib/type_traits.h>
[top]

# is_complex

This is a template that can be used to determine if a type is a specialization of std::complex.
More Details...
#include <dlib/matrix.h>
[top]

# is_config_reader

This is a template where is_config_reader<T>::value == true when T is a config_reader or config_reader_thread_safe object.
More Details...
#include <dlib/is_kind.h>
[top]

# is_const_type

This is a template where is_const_type<T>::value == true when T is a const type and false otherwise.
More Details...
#include <dlib/type_traits.h>
[top]

# is_convertible

This is a template that can be used to determine if one type is convertible into another type.
More Details...
#include <dlib/type_traits.h>
[top]

# is_detected

This is a convenient tool for testing if a type has some arbitrary property. E.g. you could check if a class type has some particular member function or not.
More Details...
#include <dlib/type_traits.h>
[top]

# is_directed_graph

This is a template where is_directed_graph<T>::value == true when T is a directed_graph object.
More Details...
#include <dlib/is_kind.h>
[top]

# is_float_type

This is a template where is_float_type<T>::value == true when T is a floating point type (i.e. float, double, or long double) and false otherwise.
More Details...
#include <dlib/type_traits.h>
[top]

# is_function

This is a template where is_function<T>::value == true when T is a function type.
More Details...
#include <dlib/type_traits.h>
[top]

# is_graph

This is a template where is_graph<T>::value == true when T is a graph object.
More Details...
#include <dlib/is_kind.h>
[top]

# is_matrix

This is a template where is_matrix<T>::value == true when T is a matrix object or some kind of matrix expression.
More Details...
#include <dlib/is_kind.h>
[top]

# is_nothrow_swappable

A type trait telling you if a type can be swapped by a global swap() function.
More Details...
#include <dlib/type_traits.h>
[top]

# is_pair

This is a template where is_pair<T>::value == true when T is a std::pair object.
More Details...
#include <dlib/is_kind.h>
[top]

# is_pointer_type

This is a template where is_pointer_type<T>::value == true when T is a pointer type and false otherwise.
More Details...
#include <dlib/type_traits.h>
[top]

# is_rand

This is a template where is_rand<T>::value == true when T is a rand object.
More Details...
#include <dlib/is_kind.h>
[top]

# is_reference_type

This is a template where is_reference_type<T>::value == true when T is a reference type and false otherwise.
More Details...
#include <dlib/type_traits.h>
[top]

# is_same_object

This is a templated function which checks if both of its arguments are actually references to the same object. It returns true if they are and false otherwise.
More Details...
#include <dlib/algs.h>
[top]

# is_same_type

This is a template where is_same_type<T,U>::value == true when T and U are the same type and false otherwise.
More Details...
#include <dlib/type_traits.h>
[top]

# is_signed_type

This is a template where is_signed_type<T>::value == true when T is a signed scalar type and false when it is an unsigned scalar type.
More Details...
#include <dlib/type_traits.h>
[top]

# is_std_vector

This is a template where is_std_vector<T>::value == true when T is a std_vector_c or std::vector object.
More Details...
#include <dlib/is_kind.h>
[top]

# is_swappable

A type trait telling you if a type can be swapped by a global swap() function that is declared noexcept.
More Details...
#include <dlib/type_traits.h>
[top]

# is_unsigned_type

This is a template where is_unsigned_type<T>::value == true when T is an unsigned scalar type and false when it is a signed scalar type.
More Details...
#include <dlib/type_traits.h>
[top]

# make_compile_time_integer_range

This is a variadic template that takes one number, MAX, as input and creates a compile_time_integer_list representing the range of integers [1,MAX] inclusive.
More Details...
#include <dlib/metaprogramming.h>
[top]

# noncopyable

This is a simple class that makes it easy to declare a non-copyable object. To use it to make your own class non-copyable just inherit from it.
More Details...
#include <dlib/noncopyable.h>
[top]

# nth_type

This is a type trait for getting the n'th argument of a parameter pack. In particular, nth_type<n, some_types...>::type is the nth type in some_types.
More Details...
#include <dlib/type_traits.h>
[top]

# Or

This template takes a list of bool values and yields their logical or. E.g. Or<true,true,true>::value == true Or<true,false,true>::value == true Or<false,false,false>::value == false
More Details...
#include <dlib/type_traits.h>
[top]

# portability_macros

This file #defines various macros depending on the platform being compiled under. See the file itself for the specifics.
More Details...
#include <dlib/platform.h>
[top]

# promote

This is a template that takes one of the built in scalar types and gives you another scalar type that should be big enough to hold sums of values from the original scalar type. The new scalar type will also always be signed.

For example, promote<uint16>::type == int32

More Details...
#include <dlib/algs.h>
[top]

# remove_cvref_t

This is a template that takes a type and strips off any const, volatile, or reference qualifiers and gives you back the basic underlying type.

For example, remove_cvref_t<const int&>::type == int

More Details...
#include <dlib/type_traits.h>
[top]

# size_

This is a shorthand for making std::integral_constant of type size_t.
More Details...
#include <dlib/type_traits.h>
[top]

# static_switch

To use this template you give it some number of boolean expressions and it tells you which one of them is true. If more than one of them is true then it causes a compile time error. It is useful for cases where you want to specialize a template and you want to specialize it not by the type of object it gets per say but instead according to the values of some type traits associated with the various template arguments. A simple example of this can be seen in the assign_pixel's implementation which can be found at the bottom of the dlib/pixel.h file.
More Details...
#include <dlib/algs.h>
[top]

# switch_

This function allows you to do compile time dispatch similar to what you can do with constexpr if in C++17, but only requires a C++14 compiler.
More Details...
#include <dlib/constexpr_if.h>
[top]

# tabs

This is a template to compute the absolute value a number at compile time.
More Details...
#include <dlib/algs.h>
[top]

# tmax

This is a template to compute the max of two values at compile time.
More Details...
#include <dlib/algs.h>
[top]

# tmin

This is a template to compute the min of two values at compile time.
More Details...
#include <dlib/algs.h>
[top]

# types_

Just a list of types.
More Details...
#include <dlib/type_traits.h>
[top]

# unsigned_type

This is a template that allows you to obtain the unsigned version of any integral type. For example, unsigned_type<signed short>::type == unsigned short.
More Details...
#include <dlib/uintn.h>
[top]

# void_t

Just always the void type. Is useful in SFINAE expressions when the resulting type doesn't matter and you just need a place to put an expression where SFINAE can take effect.
More Details...
#include <dlib/type_traits.h>
[top]

# _dT

This is a macro function for converting a string/character literal to either a char or wchar_t literal. Its form is `_dT(target character type,string or character literal)`
More Details...
#include <dlib/algs.h>