dlib C++ Library - Metaprogramming

The Library

- Algorithms
- API Wrappers
- Compression
- Containers
- Imaging
- Metaprogramming
- Miscellaneous
- Network
- Parsing

Help/Info

- Examples
  - Base64_Encoder
  - Bayesian_Network
  - Bayesian_Network_From_Disk
  - Bayesian_Network_GUI
  - Cmd_Line_Parser
  - Compress_Stream
  - Directory_Navigation
  - GUI
  - HTTP_Server
  - Image
  - Kernel_Centroid
  - Kernel_K-Means_Clustering
  - Kernel_RLS_Filtering
  - Kernel_RLS_Regression
  - Logger
  - Logger_Advanced
  - Matrix
  - Member_Function_Pointer
  - Multithreaded_Object
  - Neural_Network
  - Pipe
  - Queue
  - Rank_Features
  - Relevance_Vector_Classification
  - Relevance_Vector_Regression
  - Sockets
  - Sockets_2
  - Sockstreambuf
  - Std_C++_Allocator
  - Support_Vector_Machine
  - Threaded_Object
  - Threads
  - Thread_Function
  - Thread_Pool
  - Timer
  - XML_Parser
- Home
- How to compile
- Index
- Introduction
- License

Current Release

- Change Log
- Release Notes
- Version: 17.12

Last Modified: Nov 10, 2008

# 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

- enable_if
- is_built_in_scalar_type
- is_const_type
- is_directed_graph
- is_function
- is_graph
- is_matrix
- is_pointer_type
- is_same_type
- is_signed_type
- is_std_vector
- is_unsigned_type
- noncopyable
- static_switch
- unsigned_type

Global Functions

- ASSERT_ARE_NOT_SAME_TYPE
- ASSERT_ARE_SAME_TYPE
- assign_zero_if_built_in_scalar_type
- COMPILE_TIME_ASSERT
- DLIB_ASSERT
- DLIB_CASSERT
- DLIB_STACK_TRACE
- DLIB_STACK_TRACE_NAMED
- get_stack_trace
- TIME_THIS
- wrap_function
- _dT

Other

- portability_macros

[top]

# ASSERT_ARE_NOT_SAME_TYPE

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.

Specification: dlib/assert.h
File to include: dlib/assert.h
[top]

# ASSERT_ARE_SAME_TYPE

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.

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]

# COMPILE_TIME_ASSERT

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.

Specification: dlib/assert.h
File to include: dlib/assert.h
[top]

# DLIB_ASSERT

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.

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

Specification: dlib/assert.h
File to include: dlib/assert.h
[top]

# DLIB_CASSERT

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

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 specilization. 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_const_type

This is a template where is_const_type<T>::value == true when T is a const type ane false otherwise.
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 ane 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]

# 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]

# 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]

# 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