The Library
Help/Info
Current Release









Last Modified:
Jan 03, 2011

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
Global Functions
Other
[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.



Specification: dlib/assert.h
File to 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.



Specification: dlib/assert.h
File to 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.



Specification: dlib/algs.h
File to include: dlib/algs.h

[top]

basic_type



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



Specification: dlib/algs.h
File to include: dlib/algs.h

[top]

COMPILE_TIME_ASSERT



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.



Specification: dlib/assert.h
File to include: dlib/assert.h

[top]

DLIB_ASSERT



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



Specification: dlib/assert.h
File to 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().



Specification: dlib/assert.h
File to include: dlib/assert.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.



Specification: dlib/stack_trace.h
File to 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.



Specification: dlib/stack_trace.h
File to 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.

File to 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.



Specification: dlib/stack_trace.h
File to include: dlib/assert.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.

Specification: dlib/algs.h
File to include: dlib/algs.h

[top]

is_complex



This is a template that can be used to determine if a type is a specialization of std::complex.

Specification: dlib/matrix/matrix_utilities.h
File to include: dlib/matrix.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.

Specification: dlib/algs.h
File to include: dlib/algs.h

[top]

is_convertible



This is a template that can be used to determine if one type is convertible into another type.

Specification: dlib/algs.h
File to include: dlib/algs.h

[top]

is_directed_graph



This is a template where is_directed_graph<T>::value == true when T is a directed_graph object.

Specification: dlib/is_kind.h
File to include: dlib/is_kind.h

[top]

is_function



This is a template where is_function<T>::value == true when T is a function type.

Specification: dlib/algs.h
File to include: dlib/algs.h

[top]

is_graph



This is a template where is_graph<T>::value == true when T is a graph object.

Specification: dlib/is_kind.h
File to 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.

Specification: dlib/is_kind.h
File to 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.

Specification: dlib/algs.h
File to include: dlib/algs.h

[top]

is_rand



This is a template where is_rand<T>::value == true when T is a rand object.

Specification: dlib/is_kind.h
File to 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.

Specification: dlib/algs.h
File to include: dlib/algs.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.

Specification: dlib/algs.h
File to 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.

Specification: dlib/algs.h
File to include: dlib/algs.h

[top]

is_signed_type



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.

Specification: dlib/algs.h
File to include: dlib/algs.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.

Specification: dlib/is_kind.h
File to include: dlib/is_kind.h

[top]

is_unsigned_type



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.

Specification: dlib/algs.h
File to include: dlib/algs.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.

Specification: dlib/noncopyable.h
File to include: dlib/noncopyable.h

[top]

portability_macros



This file #defines various macros depending on the platform being compiled under. See the file itself for the specifics.

Specification: dlib/platform.h
File to 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



Specification: dlib/algs.h
File to include: dlib/algs.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.

Specification: dlib/algs.h
File to include: dlib/algs.h

[top]

tabs



This is a template to compute the absolute value a number at compile time.

Specification: dlib/algs.h
File to include: dlib/algs.h

[top]

TIME_THIS



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);



Specification: dlib/time_this.h
File to include: dlib/time_this.h

[top]

tmax



This is a template to compute the max of two values at compile time.

Specification: dlib/algs.h
File to include: dlib/algs.h

[top]

tmin



This is a template to compute the min of two values at compile time.

Specification: dlib/algs.h
File to include: dlib/algs.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.

Specification: dlib/uintn.h
File to include: dlib/uintn.h

[top]

wrap_function



This is a template that allows you to turn a global function into a function object. See the specs for more details.

Specification: dlib/algs.h
File to include: dlib/algs.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)

Specification: dlib/algs.h
File to include: dlib/algs.h