# 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.
COMPILE_TIME_ASSERT((is_same_type<T,char>::value || is_same_type<T,wchar_t>::value));

Objects
is_pointer_type
is_const_type
is_reference_type
is_same_type
is_float_type
is_convertible
is_complex
is_function
is_signed_type
is_unsigned_type
static_switch
noncopyable
enable_if
is_array2d
is_array
is_graph
is_rand
is_matrix
is_config_reader
is_std_vector
is_pair
is_directed_graph
is_built_in_scalar_type
promote
basic_type
unsigned_type
tabs
tmin
tmax
compile_time_integer_list
make_compile_time_integer_range
Global Functions
DLIB_ASSERT
DLIB_STACK_TRACE
DLIB_STACK_TRACE_NAMED
get_stack_trace
DLIB_CASSERT
COMPILE_TIME_ASSERT
ASSERT_ARE_SAME_TYPE
DLIB_ASSERT_HAS_STANDARD_LAYOUT
ASSERT_ARE_NOT_SAME_TYPE
_dT
is_same_object
assign_zero_if_built_in_scalar_type
wrap_function
DLIB_MAKE_HAS_MEMBER_FUNCTION_TEST
Other
portability_macros
tmin
dlib/algs.h
dlib/algs.h
This is a template to compute the min of two values at compile time.
tmax
dlib/algs.h
dlib/algs.h
This is a template to compute the max of two values at compile time.
compile_time_integer_list
dlib/metaprogramming.h
dlib/metaprogramming.h
This is a variadic template that can represent a list of integers.
make_compile_time_integer_range
dlib/metaprogramming.h
dlib/metaprogramming.h
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.
tabs
dlib/algs.h
dlib/algs.h
This is a template to compute the absolute value a number at compile time.
unsigned_type
dlib/uintn.h
dlib/uintn.h
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.
static_switch
dlib/algs.h
dlib/algs.h
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.
enable_if
dlib/enable_if.h
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.
noncopyable
dlib/noncopyable.h
dlib/noncopyable.h
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.
is_convertible
dlib/algs.h
dlib/algs.h
This is a template that can be used to determine if one type is convertible into another type.
is_complex
dlib/matrix.h
dlib/matrix/matrix_utilities.h
This is a template that can be used to determine if a type is a specialization of std::complex.
is_same_type
dlib/algs.h
dlib/algs.h
This is a template where is_same_type<T,U>::value == true when T and U are the same type and false otherwise.
is_float_type
dlib/algs.h
dlib/algs.h
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.
is_same_object
dlib/algs.h
dlib/algs.h
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.
is_function
dlib/algs.h
dlib/algs.h
This is a template where is_function<T>::value == true when T is a function type.
is_signed_type
dlib/algs.h
dlib/algs.h
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.
is_unsigned_type
dlib/algs.h
dlib/algs.h
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.
is_directed_graph
dlib/is_kind.h
dlib/is_kind.h
This is a template where is_directed_graph<T>::value == true when T is a directed_graph object.
is_built_in_scalar_type
dlib/algs.h
dlib/algs.h
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.
promote
dlib/algs.h
dlib/algs.h
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

basic_type
dlib/algs.h
dlib/algs.h
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, promote<const int&>::type == int

is_std_vector
dlib/is_kind.h
dlib/is_kind.h
This is a template where is_std_vector<T>::value == true when T is a std_vector_c or std::vector object.
is_pair
dlib/is_kind.h
dlib/is_kind.h
This is a template where is_pair<T>::value == true when T is a std::pair object.
is_matrix
dlib/is_kind.h
dlib/is_kind.h
This is a template where is_matrix<T>::value == true when T is a matrix object or some kind of matrix expression.
is_config_reader
dlib/is_kind.h
dlib/is_kind.h
This is a template where is_config_reader<T>::value == true when T is a config_reader or config_reader_thread_safe object.
is_graph
dlib/is_kind.h
dlib/is_kind.h
This is a template where is_graph<T>::value == true when T is a graph object.
is_array2d
dlib/is_kind.h
dlib/is_kind.h
This is a template where is_array2d<T>::value == true when T is an array2d object.
is_array
dlib/is_kind.h
dlib/is_kind.h
This is a template where is_array<T>::value == true when T is an array object.
is_rand
dlib/is_kind.h
dlib/is_kind.h
This is a template where is_rand<T>::value == true when T is a rand object.
is_reference_type
dlib/algs.h
dlib/algs.h
This is a template where is_reference_type<T>::value == true when T is a reference type and false otherwise.
is_const_type
dlib/algs.h
dlib/algs.h
This is a template where is_const_type<T>::value == true when T is a const type and false otherwise.
is_pointer_type
dlib/algs.h
dlib/algs.h
This is a template where is_pointer_type<T>::value == true when T is a pointer type and false otherwise.
ASSERT_ARE_NOT_SAME_TYPE
dlib/assert.h
dlib/assert.h

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.

ASSERT_ARE_SAME_TYPE
dlib/assert.h
dlib/assert.h

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.

DLIB_ASSERT_HAS_STANDARD_LAYOUT
dlib/assert.h
dlib/assert.h

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
COMPILE_TIME_ASSERT
dlib/assert.h
dlib/assert.h

This is a macro function for debugging. Its form is COMPILE_TIME_ASSERT(condition that should be true). The condition must be a compile time constant and if it is false then the compile will fail.

DLIB_MAKE_HAS_MEMBER_FUNCTION_TEST
dlib/algs.h
dlib/algs.h

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.

DLIB_CASSERT
dlib/assert.h
dlib/assert.h

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().

DLIB_ASSERT
dlib/assert.h
dlib/assert.h

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().

DLIB_STACK_TRACE
dlib/assert.h
dlib/stack_trace.h

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.

DLIB_STACK_TRACE_NAMED
dlib/assert.h
dlib/stack_trace.h
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.

get_stack_trace
dlib/assert.h
dlib/stack_trace.h
This function allows you to query the current stack trace.

This macro is only enabled if DLIB_ENABLE_STACK_TRACE is defined.

_dT
dlib/algs.h
dlib/algs.h
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)
assign_zero_if_built_in_scalar_type
dlib/algs.h
dlib/algs.h

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.

wrap_function
dlib/algs.h
dlib/algs.h
This is a template that allows you to turn a global function into a function object. See the specs for more details.
portability_macros
dlib/platform.h
dlib/platform.h
This file #defines various macros depending on the platform being compiled under. See the file itself for the specifics.