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_same_type is_function is_signed_type is_unsigned_type static_switch noncopyable enable_if is_graph is_matrix is_std_vector is_directed_graph is_built_in_scalar_type unsigned_type

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 assign_zero_if_built_in_scalar_type wrap_function

Other portability_macros

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 specilization. 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_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_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... 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_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 ane 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 ane false otherwise. ASSERT_ARE_NOT_SAME_TYPE dlib/assert.h dlib/assert.h

This is a macro function for debuging. 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 debuging. 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 debuging. 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 identicial 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 breakpoing on dlib_assert_breakpoint().

DLIB_ASSERT dlib/assert.h dlib/assert.h

This is a macro function for debuging. 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.

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.