# 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_convertible
is_complex
is_function
is_signed_type
is_unsigned_type
static_switch
noncopyable
enable_if
is_graph
is_rand
is_matrix
is_std_vector
is_directed_graph
is_built_in_scalar_type
promote
unsigned_type
tabs
tmin
tmax
Global Functions
DLIB_ASSERT
DLIB_STACK_TRACE
DLIB_STACK_TRACE_NAMED
get_stack_trace
DLIB_CASSERT
COMPILE_TIME_ASSERT
ASSERT_ARE_SAME_TYPE
ASSERT_ARE_NOT_SAME_TYPE
_dT
TIME_THIS
is_same_object
assign_zero_if_built_in_scalar_type
wrap_function
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.
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_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 integral type and false when it is an unsigned integral 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 integral type and false when it is a signed integral 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

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_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_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_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.

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_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). 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.
TIME_THIS
dlib/time_this.h
dlib/time_this.h

This is a macro function for timing blocks of code. Its form is TIME_THIS(whatever you want to time) It's pretty straight forward. It just prints the time it took to std::cout.

There is another version of this function called TIME_THIS_TO which takes as a parameter an ostream object to write its output to. Its form is TIME_THIS_TO(what you want to time, the output stream);

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.