## Latest stable version: 3.5.1 Current pre-release: 3.5.2 (2025/01/28)

- Home
- Download
- Screenshots
- Tutorial
- Documentation
- Report Issue
- Links
- Book

Reference

Functions | Variables
cimg_library::cimg Namespace Reference

Contains low-level functions and variables of the CImg Library. More...

## Functions

std::FILE * | output (std::FILE *file)
| Get/set default output stream for the CImg library messages.
void | info ()
| Print information about CImg environment variables.
template<typename T>
void | unused (const T &,...)
| Avoid warning messages due to unused parameters. Do nothing actually.
unsigned int & | exception_mode (const unsigned int mode)
| Set current CImg exception mode.
unsigned int & | exception_mode ()
| Return current CImg exception mode.
unsigned int | openmp_mode (const unsigned int mode)
| Set current CImg openmp mode.
unsigned int | openmp_mode ()
| Return current CImg openmp mode.
int | dialog (const char *const title, const char *const msg, const char *const button1_label, const char *const button2_label, const char *const button3_label, const char *const button4_label, const char *const button5_label, const char *const button6_label, const bool is_centered)
| Display a simple dialog box, and wait for the user's response [specialization].
double | eval (const char *const expression, const double x, const double y, const double z, const double c)
| Evaluate math expression.
void | warn (const char *const format,...)
| Display a warning message on the default output stream.
int | system (const char *const command, const char *const module_name=0, const bool is_verbose=false)
template<typename T>
T & | temporary (const T &)
| Return a reference to a temporary variable of type T.
template<typename T>
void | swap (T &a, T &b)
| Exchange values of variables `a` and `b`.
template<typename T1, typename T2>
void | swap (T1 &a1, T1 &b1, T2 &a2, T2 &b2)
| Exchange values of variables (`a1`,`a2`) and (`b1`,`b2`).
template<typename T1, typename T2, typename T3>
void | swap (T1 &a1, T1 &b1, T2 &a2, T2 &b2, T3 &a3, T3 &b3)
| Exchange values of variables (`a1`,`a2`,`a3`) and (`b1`,`b2`,`b3`).
template<typename T1, typename T2, typename T3, typename T4>
void | swap (T1 &a1, T1 &b1, T2 &a2, T2 &b2, T3 &a3, T3 &b3, T4 &a4, T4 &b4)
| Exchange values of variables (`a1`,`a2`,...,`a4`) and (`b1`,`b2`,...,`b4`).
template<typename T1, typename T2, typename T3, typename T4, typename T5>
void | swap (T1 &a1, T1 &b1, T2 &a2, T2 &b2, T3 &a3, T3 &b3, T4 &a4, T4 &b4, T5 &a5, T5 &b5)
| Exchange values of variables (`a1`,`a2`,...,`a5`) and (`b1`,`b2`,...,`b5`).
template<typename T1, typename T2, typename T3, typename T4, typename T5, typename T6>
void | swap (T1 &a1, T1 &b1, T2 &a2, T2 &b2, T3 &a3, T3 &b3, T4 &a4, T4 &b4, T5 &a5, T5 &b5, T6 &a6, T6 &b6)
| Exchange values of variables (`a1`,`a2`,...,`a6`) and (`b1`,`b2`,...,`b6`).
template<typename T1, typename T2, typename T3, typename T4, typename T5, typename T6, typename T7>
void | swap (T1 &a1, T1 &b1, T2 &a2, T2 &b2, T3 &a3, T3 &b3, T4 &a4, T4 &b4, T5 &a5, T5 &b5, T6 &a6, T6 &b6, T7 &a7, T7 &b7)
| Exchange values of variables (`a1`,`a2`,...,`a7`) and (`b1`,`b2`,...,`b7`).
template<typename T1, typename T2, typename T3, typename T4, typename T5, typename T6, typename T7, typename T8>
void | swap (T1 &a1, T1 &b1, T2 &a2, T2 &b2, T3 &a3, T3 &b3, T4 &a4, T4 &b4, T5 &a5, T5 &b5, T6 &a6, T6 &b6, T7 &a7, T7 &b7, T8 &a8, T8 &b8)
| Exchange values of variables (`a1`,`a2`,...,`a8`) and (`b1`,`b2`,...,`b8`).
bool | endianness ()
| Return the endianness of the current architecture.
template<typename T>
void | invert_endianness (T *const buffer, const unsigned long size)
| Reverse endianness of all elements in a memory buffer.
template<typename T>
T & | invert_endianness (T &a)
| Reverse endianness of a single variable.
unsigned long long | time ()
| Return the value of a system timer, with a millisecond precision.
unsigned long long | tic ()
| Start tic/toc timer for time measurement between code instructions.
unsigned long long | toc ()
| End tic/toc timer and displays elapsed time from last call to tic().
void | sleep (const unsigned int milliseconds)
| Sleep for a given numbers of milliseconds.
unsigned int | wait (const unsigned int milliseconds)
| Wait for a given number of milliseconds since the last call to wait().
template<typename T>
T | rol (const T &a, const unsigned int n=1)
| Bitwise-rotate value on the left.
template<typename T>
T | ror (const T &a, const unsigned int n=1)
| Bitwise-rotate value on the right.
template<typename T>
T | abs (const T &a)
| Return absolute value of a value.
double | acosh (const double x)
| Return hyperbolic arcosine of a value.
double | asinh (const double x)
| Return hyperbolic arcsine of a value.
double | atanh (const double x)
| Return hyperbolic arctangent of a value.
double | sinc (const double x)
| Return the sinc of a given value.
double | log2 (const double x)
| Return base-2 logarithm of a value.
template<typename T>
T | sqr (const T &val)
| Return square of a value.
template<typename T>
double | cbrt (const T &x)
| Return cubic root of a value.
template<typename t>
t | min (const t &a, const t &b, const t &c)
| Return the minimum between three values.
template<typename t>
t | min (const t &a, const t &b, const t &c, const t &d)
| Return the minimum between four values.
template<typename t>
t | minabs (const t &a, const t &b)
| Return the minabs between two values.
template<typename t>
t | max (const t &a, const t &b, const t &c)
| Return the maximum between three values.
template<typename t>
t | max (const t &a, const t &b, const t &c, const t &d)
| Return the maximum between four values.
template<typename t>
t | maxabs (const t &a, const t &b)
| Return the maxabs between two values.
template<typename T>
T | sign (const T &x)
| Return the sign of a value.
template<typename T>
T | cut (const T &val, const T &val_min, const T &val_max)
| Cut (i.e. clamp) value in specified interval.
template<typename T>
T | abscut (const T &val, const T &val_min, const T &val_max, const T &offset)
| Cut (i.e. clamp) absolute value in specified interval.
template<typename T>
unsigned long long | nearest_pow2 (const T &x)
| Return the nearest power of 2 higher than given value.
template<typename T>
T | mod (const T &x, const T &m)
| Return the modulo of a value.
template<typename T>
T | minmod (const T &a, const T &b)
| Return the min-mod of two values.
template<typename T>
T | round (const T &x, const double y, const int rounding_type=0)
| Return rounded value.
template<typename T>
T | hypot (const T x, const T y)
| Return sqrt(x^2 + y^2).
template<typename T>
T | hypot (const T x, const T y, const T z)
| Return sqrt(x^2 + y^2 + z^2).
double | factorial (const int n)
| Return the factorial of n.
double | permutations (const int k, const int n, const bool with_order)
| Return the number of permutations of k objects in a set of n objects.
double | fibonacci (const int n)
| Calculate fibonacci number.
template<typename T>
T | gcd (T a, T b)
| Calculate greatest common divisor of two integers.
template<typename T>
T | lcm (T a, T b)
| Calculate least common multiple of two integers.
char | lowercase (const char x)
| Convert character to lower case.
void | lowercase (char *const str)
| Convert C-string to lower case.
char | uppercase (const char x)
| Convert character to upper case.
void | uppercase (char *const str)
| Convert C-string to upper case.
bool | is_blank (const char c)
| Return `true` if input character is blank (space, tab, or non-printable character).
bool | is_varname (const char *const str, const unsigned int length=~0U)
| Return `true` if argument `str` can be considered as a regular variable name.
double | atof (const char *const str)
| Read value in a C-string.
int | strncasecmp (const char *const str1, const char *const str2, const int length)
| Compare the first `length` characters of two C-strings, ignoring the case.
int | strcasecmp (const char *const str1, const char *const str2)
| Compare two C-strings, ignoring the case.
char * | strellipsize (char *const str, const unsigned int l=64, const bool is_ending=true)
| Ellipsize a string.
char * | strellipsize (const char *const str, char *const res, const unsigned int l=64, const bool is_ending=true)
| Ellipsize a string.
bool | strpare (char *const str, const char delimiter, const bool is_symmetric, const bool is_iterative)
| Remove delimiters on the start and/or end of a C-string.
bool | strpare (char *const str, const bool is_symmetric, const bool is_iterative)
| Remove white spaces on the start and/or end of a C-string.
void | strwindows_reserved (char *const str, const char c='_')
| Replace reserved characters (for Windows filename) by another character.
void | strunescape (char *const str)
| Replace escape sequences in C-strings by character values.
const char * | basename (const char *const s, const char separator='/')
| Return the basename of a filename.
std::FILE * | fopen (const char *const path, const char *const mode)
| Open a file.
int | fclose (std::FILE *file)
| Close a file.
int | fseek (FILE *stream, long offset, int origin)
| Version of 'fseek()' that supports >=64bits offsets everywhere (for Windows).
long | ftell (FILE *stream)
| Version of 'ftell()' that supports >=64bits offsets everywhere (for Windows).
bool | is_directory (const char *const path)
| Check if a path is a directory.
bool | is_file (const char *const path)
| Check if a path is a file.
long long | fsize (std::FILE *const file)
| Get file size.
template<typename T>
int | fdate (const char *const path, T *attr, const unsigned int nb_attr)
| Get last write time of a given file or directory (multiple-attributes version).
int | fdate (const char *const path, unsigned int attr)
| Get last write time of a given file or directory (single-attribute version).
template<typename T>
int | date (T *attr, const unsigned int nb_attr)
| Get current local time (multiple-attributes version).
int | date (unsigned int attr)
| Get current local time (single-attribute version).
const char * | curl_path (const char *const user_path, const bool reinit_path)
| Search path of an executable.
const char * | dcraw_path (const char *const user_path, const bool reinit_path)
| Get/set path to the `dcraw` binary.
const char * | ffmpeg_path (const char *const user_path, const bool reinit_path)
| Get/set path to the FFMPEG's `ffmpeg` binary.
const char * | graphicsmagick_path (const char *const user_path, const bool reinit_path)
| Get/set path to the GraphicsMagick's `gm` binary.
const char * | gunzip_path (const char *const user_path, const bool reinit_path)
| Get/set path to the `gunzip` binary.
const char * | gzip_path (const char *const user_path, const bool reinit_path)
| Get/set path to the `gzip` binary.
const char * | imagemagick_path (const char *const user_path, const bool reinit_path)
| Get/set path to the ImageMagick's `convert` binary.
const char * | medcon_path (const char *const user_path, const bool reinit_path)
| Get/set path to the Medcon's `medcon` binary.
const char * | temporary_path (const char *const user_path, const bool reinit_path)
| Get/set path to store temporary files.
const char * | wget_path (const char *const user_path, const bool reinit_path)
| Get/set path to the `wget` binary.
const char * | split_filename (const char *const filename, char *const body=0)
| Split filename into two C-strings `body` and `extension`.
char * | number_filename (const char *const filename, const int number, const unsigned int digits, char *const str)
| Generate a numbered version of a filename.
template<typename T>
size_t | fread (T *const ptr, const size_t nmemb, std::FILE *stream)
| Read data from file.
template<typename T>
size_t | fwrite (const T *ptr, const size_t nmemb, std::FILE *stream)
| Write data to file.
void | fempty (std::FILE *const file, const char *const filename)
| Create an empty file.
const char * | ftype (std::FILE *const file, const char *const filename)
| Try to guess format from an image file.
char * | load_network (const char *const url, char *const filename_local, const unsigned int timeout, const bool try_fallback, const char *const referer, const char *const user_agent)
| Load file from network as a local temporary file.
const char * | option (const char *const name, const int argc, const char *const *const argv, const char *const _default, const char *const usage, const bool reset_static)
| Return options specified on the command line.
CImgList< char > | files (const char *const path, const bool is_pattern=false, const unsigned int mode=2, const bool include_path=false)
| Return list of files/directories in specified directory.
template<typename t>
int | dialog (const char *const title, const char *const msg, const char *const button1_label, const char *const button2_label, const char *const button3_label, const char *const button4_label, const char *const button5_label, const char *const button6_label, const CImg< t > &logo, const bool is_centered=false)
| Display a simple dialog box, and wait for the user's response.

## Variables

const unsigned int | keyESC = 1U
| Keycode for the `ESC` key (architecture-dependent).
const unsigned int | keyF1 = 2U
| Keycode for the `F1` key (architecture-dependent).
const unsigned int | keyF2 = 3U
| Keycode for the `F2` key (architecture-dependent).
const unsigned int | keyF3 = 4U
| Keycode for the `F3` key (architecture-dependent).
const unsigned int | keyF4 = 5U
| Keycode for the `F4` key (architecture-dependent).
const unsigned int | keyF5 = 6U
| Keycode for the `F5` key (architecture-dependent).
const unsigned int | keyF6 = 7U
| Keycode for the `F6` key (architecture-dependent).
const unsigned int | keyF7 = 8U
| Keycode for the `F7` key (architecture-dependent).
const unsigned int | keyF8 = 9U
| Keycode for the `F8` key (architecture-dependent).
const unsigned int | keyF9 = 10U
| Keycode for the `F9` key (architecture-dependent).
const unsigned int | keyF10 = 11U
| Keycode for the `F10` key (architecture-dependent).
const unsigned int | keyF11 = 12U
| Keycode for the `F11` key (architecture-dependent).
const unsigned int | keyF12 = 13U
| Keycode for the `F12` key (architecture-dependent).
const unsigned int | keyPAUSE = 14U
| Keycode for the `PAUSE` key (architecture-dependent).
const unsigned int | key1 = 15U
| Keycode for the `1` key (architecture-dependent).
const unsigned int | key2 = 16U
| Keycode for the `2` key (architecture-dependent).
const unsigned int | key3 = 17U
| Keycode for the `3` key (architecture-dependent).
const unsigned int | key4 = 18U
| Keycode for the `4` key (architecture-dependent).
const unsigned int | key5 = 19U
| Keycode for the `5` key (architecture-dependent).
const unsigned int | key6 = 20U
| Keycode for the `6` key (architecture-dependent).
const unsigned int | key7 = 21U
| Keycode for the `7` key (architecture-dependent).
const unsigned int | key8 = 22U
| Keycode for the `8` key (architecture-dependent).
const unsigned int | key9 = 23U
| Keycode for the `9` key (architecture-dependent).
const unsigned int | key0 = 24U
| Keycode for the `0` key (architecture-dependent).
const unsigned int | keyBACKSPACE = 25U
| Keycode for the `BACKSPACE` key (architecture-dependent).
const unsigned int | keyINSERT = 26U
| Keycode for the `INSERT` key (architecture-dependent).
const unsigned int | keyHOME = 27U
| Keycode for the `HOME` key (architecture-dependent).
const unsigned int | keyPAGEUP = 28U
| Keycode for the `PAGEUP` key (architecture-dependent).
const unsigned int | keyTAB = 29U
| Keycode for the `TAB` key (architecture-dependent).
const unsigned int | keyQ = 30U
| Keycode for the `Q` key (architecture-dependent).
const unsigned int | keyW = 31U
| Keycode for the `W` key (architecture-dependent).
const unsigned int | keyE = 32U
| Keycode for the `E` key (architecture-dependent).
const unsigned int | keyR = 33U
| Keycode for the `R` key (architecture-dependent).
const unsigned int | keyT = 34U
| Keycode for the `T` key (architecture-dependent).
const unsigned int | keyY = 35U
| Keycode for the `Y` key (architecture-dependent).
const unsigned int | keyU = 36U
| Keycode for the `U` key (architecture-dependent).
const unsigned int | keyI = 37U
| Keycode for the `I` key (architecture-dependent).
const unsigned int | keyO = 38U
| Keycode for the `O` key (architecture-dependent).
const unsigned int | keyP = 39U
| Keycode for the `P` key (architecture-dependent).
const unsigned int | keyDELETE = 40U
| Keycode for the `DELETE` key (architecture-dependent).
const unsigned int | keyEND = 41U
| Keycode for the `END` key (architecture-dependent).
const unsigned int | keyPAGEDOWN = 42U
| Keycode for the `PAGEDOWN` key (architecture-dependent).
const unsigned int | keyCAPSLOCK = 43U
| Keycode for the `CAPSLOCK` key (architecture-dependent).
const unsigned int | keyA = 44U
| Keycode for the `A` key (architecture-dependent).
const unsigned int | keyS = 45U
| Keycode for the `S` key (architecture-dependent).
const unsigned int | keyD = 46U
| Keycode for the `D` key (architecture-dependent).
const unsigned int | keyF = 47U
| Keycode for the `F` key (architecture-dependent).
const unsigned int | keyG = 48U
| Keycode for the `G` key (architecture-dependent).
const unsigned int | keyH = 49U
| Keycode for the `H` key (architecture-dependent).
const unsigned int | keyJ = 50U
| Keycode for the `J` key (architecture-dependent).
const unsigned int | keyK = 51U
| Keycode for the `K` key (architecture-dependent).
const unsigned int | keyL = 52U
| Keycode for the `L` key (architecture-dependent).
const unsigned int | keyENTER = 53U
| Keycode for the `ENTER` key (architecture-dependent).
const unsigned int | keySHIFTLEFT = 54U
| Keycode for the `SHIFTLEFT` key (architecture-dependent).
const unsigned int | keyZ = 55U
| Keycode for the `Z` key (architecture-dependent).
const unsigned int | keyX = 56U
| Keycode for the `X` key (architecture-dependent).
const unsigned int | keyC = 57U
| Keycode for the `C` key (architecture-dependent).
const unsigned int | keyV = 58U
| Keycode for the `V` key (architecture-dependent).
const unsigned int | keyB = 59U
| Keycode for the `B` key (architecture-dependent).
const unsigned int | keyN = 60U
| Keycode for the `N` key (architecture-dependent).
const unsigned int | keyM = 61U
| Keycode for the `M` key (architecture-dependent).
const unsigned int | keySHIFTRIGHT = 62U
| Keycode for the `SHIFTRIGHT` key (architecture-dependent).
const unsigned int | keyARROWUP = 63U
| Keycode for the `ARROWUP` key (architecture-dependent).
const unsigned int | keyCTRLLEFT = 64U
| Keycode for the `CTRLLEFT` key (architecture-dependent).
const unsigned int | keyAPPLEFT = 65U
| Keycode for the `APPLEFT` key (architecture-dependent).
const unsigned int | keyALT = 66U
| Keycode for the `ALT` key (architecture-dependent).
const unsigned int | keySPACE = 67U
| Keycode for the `SPACE` key (architecture-dependent).
const unsigned int | keyALTGR = 68U
| Keycode for the `ALTGR` key (architecture-dependent).
const unsigned int | keyAPPRIGHT = 69U
| Keycode for the `APPRIGHT` key (architecture-dependent).
const unsigned int | keyMENU = 70U
| Keycode for the `MENU` key (architecture-dependent).
const unsigned int | keyCTRLRIGHT = 71U
| Keycode for the `CTRLRIGHT` key (architecture-dependent).
const unsigned int | keyARROWLEFT = 72U
| Keycode for the `ARROWLEFT` key (architecture-dependent).
const unsigned int | keyARROWDOWN = 73U
| Keycode for the `ARROWDOWN` key (architecture-dependent).
const unsigned int | keyARROWRIGHT = 74U
| Keycode for the `ARROWRIGHT` key (architecture-dependent).
const unsigned int | keyPAD0 = 75U
| Keycode for the `PAD0` key (architecture-dependent).
const unsigned int | keyPAD1 = 76U
| Keycode for the `PAD1` key (architecture-dependent).
const unsigned int | keyPAD2 = 77U
| Keycode for the `PAD2` key (architecture-dependent).
const unsigned int | keyPAD3 = 78U
| Keycode for the `PAD3` key (architecture-dependent).
const unsigned int | keyPAD4 = 79U
| Keycode for the `PAD4` key (architecture-dependent).
const unsigned int | keyPAD5 = 80U
| Keycode for the `PAD5` key (architecture-dependent).
const unsigned int | keyPAD6 = 81U
| Keycode for the `PAD6` key (architecture-dependent).
const unsigned int | keyPAD7 = 82U
| Keycode for the `PAD7` key (architecture-dependent).
const unsigned int | keyPAD8 = 83U
| Keycode for the `PAD8` key (architecture-dependent).
const unsigned int | keyPAD9 = 84U
| Keycode for the `PAD9` key (architecture-dependent).
const unsigned int | keyPADADD = 85U
| Keycode for the `PADADD` key (architecture-dependent).
const unsigned int | keyPADSUB = 86U
| Keycode for the `PADSUB` key (architecture-dependent).
const unsigned int | keyPADMUL = 87U
| Keycode for the `PADMUL` key (architecture-dependent).
const unsigned int | keyPADDIV = 88U
| Keycode for the `PADDDIV` key (architecture-dependent).
const double | PI = 3.14159265358979323846
| Value of the mathematical constant PI.

## Detailed Description

Contains low-level functions and variables of the CImg Library.

Most of the functions and variables within this namespace are used by the CImg library for low-level operations. You may use them to access specific const values or environment variables internally used by CImg.

Warning
  Never write using namespace cimg_library::cimg; in your source code. Lot of functions in the cimg:: namespace have the same names as standard C functions that may be defined in the global namespace ::.

## Function Documentation

## ◆ output()

std::FILE * output | ( | std::FILE * | file | ) |

Get/set default output stream for the CImg library messages.

Parameters

  file | Desired output stream. Set to `0` to get the currently used output stream only.

Returns
  Currently used output stream.

## ◆ info()

void info | ( |  | ) |

Print information about CImg environment variables.

Note
  Output is done on the default output stream.

## ◆ exception_mode() [1/2]

unsigned int & exception_mode | ( | const unsigned int | mode | ) |

Set current CImg exception mode.

The way error messages are handled by CImg can be changed dynamically, using this function.

Parameters

  mode

  Desired exception mode. Possible values are:
  - `0`: Hide library messages (quiet mode).
  - `1`: Print library messages on the console.
  - `2`: Display library messages on a dialog window.
  - `3`: Do as `1` + add extra debug warnings (slow down the code!).
  - `4`: Do as `2` + add extra debug warnings (slow down the code!).

## ◆ exception_mode() [2/2]

unsigned int & exception_mode | ( |  | ) |

Return current CImg exception mode.

Note
  By default, return the value of configuration macro `cimg_verbosity`

## ◆ openmp_mode()

unsigned int openmp_mode | ( | const unsigned int | mode | ) |

Set current CImg openmp mode.

The way openmp-based methods are handled by CImg can be changed dynamically, using this function.

Parameters

  mode

  Desired openmp mode. Possible values are:
  - `0`: Never parallelize.
  - `1`: Always parallelize.
  - `2`: Adaptive parallelization mode (default behavior).

## ◆ eval()

double eval | ( | const char *const | expression,
|  | const double | x,
|  | const double | y,
|  | const double | z,
|  | const double | c )

Evaluate math expression.

Parameters

  expression | C-string describing the formula to evaluate.
  x | Value of the pre-defined variable `x`.
  y | Value of the pre-defined variable `y`.
  z | Value of the pre-defined variable `z`.
  c | Value of the pre-defined variable `c`.

Returns
  Result of the formula evaluation.

Note
  Set `expression` to `0` to keep evaluating the last specified `expression`.

Example
  const double
  res1 = cimg::eval("cos(x)^2 + sin(y)^2",2,2), // will return '1'
  res2 = cimg::eval(0,1,1); // will return '1' too
  cimg_library::cimg::eval
  double eval(const char *const expression, const double x=0, const double y=0, const double z=0, const double c=0)
  Evaluate math expression.
  Definition CImg.h:69056

## ◆ warn()

void warn | ( | const char *const | format,
|  |  | ... )

Display a warning message on the default output stream.

Parameters

  format | C-string containing the format of the message, as with std::printf().

Note
  If configuration macro `cimg_strict_warnings` is set, this function throws a `CImgWarningException` instead.

Warning
  As the first argument is a format string, it is highly recommended to write
  cimg::warn("%s",warning_message);
  cimg_library::cimg::warn
  void warn(const char *const format,...)
  Display a warning message on the default output stream.
  Definition CImg.h:5772
  instead of
  cimg::warn(warning_message);
  if `warning_message` can be arbitrary, to prevent nasty memory access.

## ◆ system()

int system | ( | const char *const | command,
|  | const char *const | module_name = 0,
|  | const bool | is_verbose = false )

Parameters

  command | C-string containing the command line to execute.
  module_name | Module name.

Returns
  Status value of the executed command, whose meaning is OS-dependent.

Note
  This function is similar to std::system() but it does not open an extra console windows on Windows-based systems.

## ◆ endianness()

bool endianness | ( |  | ) |

Return the endianness of the current architecture.

Returns
  `false` for Little Endian or `true` for Big Endian.

## ◆ invert_endianness() [1/2]

template<typename T>

void invert_endianness | ( | T *const | buffer,
|  | const unsigned long | size )

Reverse endianness of all elements in a memory buffer.

Parameters

  [in,out] | buffer | Memory buffer whose endianness must be reversed.
  | size | Number of buffer elements to reverse.

## ◆ invert_endianness() [2/2]

template<typename T>

T & invert_endianness | ( | T & | a | ) |

Reverse endianness of a single variable.

Parameters

  [in,out] | a | Variable to reverse.

Returns
  Reference to reversed variable.

## ◆ time()

unsigned long long time | ( |  | ) |

Return the value of a system timer, with a millisecond precision.

Note
  The timer does not necessarily starts from `0`.

## ◆ tic()

unsigned long long tic | ( |  | ) |

Start tic/toc timer for time measurement between code instructions.

Returns
  Current value of the timer (same value as time()).

## ◆ toc()

unsigned long long toc | ( |  | ) |

End tic/toc timer and displays elapsed time from last call to tic().

Returns
  Time elapsed (in ms) since last call to tic().

## ◆ sleep()

void sleep | ( | const unsigned int | milliseconds | ) |

Sleep for a given numbers of milliseconds.

Parameters

  milliseconds | Number of milliseconds to wait for.

Note
  This function frees the CPU resources during the sleeping time. It can be used to temporize your program properly, without wasting CPU time.

## ◆ wait()

unsigned int wait | ( | const unsigned int | milliseconds | ) |

Wait for a given number of milliseconds since the last call to wait().

Parameters

  milliseconds | Number of milliseconds to wait for.

Returns
  Number of milliseconds elapsed since the last call to wait().

Note
  Same as sleep() with a waiting time computed with regard to the last call of wait(). It may be used to temporize your program properly, without wasting CPU time.

## ◆ mod()

template<typename T>

T mod | ( | const T & | x,
|  | const T & | m )

Return the modulo of a value.

Parameters

  x | Input value.
  m | Modulo value.

Note
  This modulo function accepts negative and floating-points modulo numbers, as well as variables of any type.

## ◆ minmod()

template<typename T>

T minmod | ( | const T & | a,
|  | const T & | b )

Return the min-mod of two values.

Note
  minmod(`a`,`b`) is defined to be:
  - minmod(`a`,`b`) = min(`a`,`b`), if `a` and `b` have the same sign.
  - minmod(`a`,`b`) = 0, if `a` and `b` have different signs.

## ◆ round()

template<typename T>

T round | ( | const T & | x,
|  | const double | y,
|  | const int | rounding_type = 0 )

Return rounded value.

Parameters

  x | Value to be rounded.
  y | Rounding precision.
  rounding_type | Type of rounding operation (`0` = nearest, `-1` = backward, `1` = forward).

Returns
  Rounded value, having the same type as input value `x`.

## ◆ atof()

double atof | ( | const char *const | str | ) |

Read value in a C-string.

Parameters

  str | C-string containing the float value to read.

Returns
  Read value.

Note
  Same as std::atof() extended to manage the retrieval of fractions from C-strings, as in "1/2".

## ◆ strncasecmp()

int strncasecmp | ( | const char *const | str1,
|  | const char *const | str2,
|  | const int | length )

Compare the first `length` characters of two C-strings, ignoring the case.

Parameters

  str1 | C-string.
  str2 | C-string.
  length | Number of characters to compare.

Returns
  `0` if the two strings are equal, something else otherwise.

Note
  This function has to be defined since it is not provided by all C++-compilers (not ANSI).

## ◆ strcasecmp()

int strcasecmp | ( | const char *const | str1,
|  | const char *const | str2 )

Compare two C-strings, ignoring the case.

Parameters

  str1 | C-string.
  str2 | C-string.

Returns
  `0` if the two strings are equal, something else otherwise.

Note
  This function has to be defined since it is not provided by all C++-compilers (not ANSI).

## ◆ strellipsize() [1/2]

char * strellipsize | ( | char *const | str,
|  | const unsigned int | l = 64,
|  | const bool | is_ending = true )

Ellipsize a string.

Parameters

  str | C-string.
  l | Max number of printed characters.
  is_ending | Tell if the dots are placed at the end or at the center of the ellipsized string.

## ◆ strellipsize() [2/2]

char * strellipsize | ( | const char *const | str,
|  | char *const | res,
|  | const unsigned int | l = 64,
|  | const bool | is_ending = true )

Ellipsize a string.

Parameters

  str | C-string.
  res | output C-string.
  l | Max number of printed characters. String 'res' must be a size of at least 'l+1'.
  is_ending | Tell if the dots are placed at the end or at the center of the ellipsized string.

## ◆ strpare()

bool strpare | ( | char *const | str,
|  | const char | delimiter,
|  | const bool | is_symmetric,
|  | const bool | is_iterative )

Remove delimiters on the start and/or end of a C-string.

Parameters

  [in,out] | str | C-string to work with (modified at output).
  | delimiter | Delimiter character code to remove.
  | is_symmetric | Tells if the removal is done only if delimiters are symmetric (both at the beginning and the end of `s`).
  | is_iterative | Tells if the removal is done if several iterations are possible.

Returns
  `true` if delimiters have been removed, `false` otherwise.

## ◆ strwindows_reserved()

void strwindows_reserved | ( | char *const | str,
|  | const char | c = '_' )

Replace reserved characters (for Windows filename) by another character.

Parameters

  [in,out] | str | C-string to work with (modified at output).
  [in] | c | Replacement character.

## ◆ strunescape()

void strunescape | ( | char *const | str | ) |

Replace escape sequences in C-strings by character values.

Parameters

  [in,out] | str | C-string to work with (modified at output).

## ◆ fopen()

std::FILE * fopen | ( | const char *const | path,
|  | const char *const | mode )

Open a file.

Parameters

  path | Path of the filename to open.
  mode | C-string describing the opening mode.

Returns
  Opened file.

Note
  Same as std::fopen() but throw a `CImgIOException` when the specified file cannot be opened, instead of returning `0`.

## ◆ fclose()

int fclose | ( | std::FILE * | file | ) |

Close a file.

Parameters

  file | File to close.

Returns
  `0` if file has been closed properly, something else otherwise.

Note
  Same as std::fclose() but display a warning message if the file has not been closed properly.

## ◆ is_directory()

bool is_directory | ( | const char *const | path | ) |

Check if a path is a directory.

Parameters

  path | Specified path to test.

## ◆ is_file()

bool is_file | ( | const char *const | path | ) |

Check if a path is a file.

Parameters

  path | Specified path to test.

## ◆ fsize()

long long fsize | ( | std::FILE *const | file | ) |

Get file size.

Parameters

  filename | Specified filename to get size from.

Returns
  File size or '-1' if file does not exist.

## ◆ fdate() [1/2]

template<typename T>

int fdate | ( | const char *const | path,
|  | T * | attr,
|  | const unsigned int | nb_attr )

Get last write time of a given file or directory (multiple-attributes version).

Parameters

  | path | Specified path to get attributes from.
  [in,out] | attr | Type of requested time attributes. Can be { 0=year | 1=month | 2=day | 3=day of week | 4=hour | 5=minute | 6=second } Replaced by read attributes after return (or -1 if an error occurred).
  | nb_attr | Number of attributes to read/write.

Returns
  Latest read attribute.

## ◆ fdate() [2/2]

int fdate | ( | const char *const | path,
|  | unsigned int | attr )

Get last write time of a given file or directory (single-attribute version).

Parameters

  path | Specified path to get attributes from.
  attr | Type of requested time attributes. Can be { 0=year | 1=month | 2=day | 3=day of week | 4=hour | 5=minute | 6=second }

Returns
  Specified attribute or -1 if an error occurred.

## ◆ date() [1/2]

template<typename T>

int date | ( | T * | attr,
|  | const unsigned int | nb_attr )

Get current local time (multiple-attributes version).

Parameters

  [in,out] | attr | Type of requested time attributes. Can be { 0=year | 1=month | 2=day | 3=day of week | 4=hour | 5=minute | 6=second | 7=millisecond } Replaced by read attributes after return (or -1 if an error occurred).
  | nb_attr | Number of attributes to read/write.

Returns
  Latest read attribute.

## ◆ date() [2/2]

int date | ( | unsigned int | attr | ) |

Get current local time (single-attribute version).

Parameters

  attr | Type of requested time attribute. Can be { 0=year | 1=month | 2=day | 3=day of week | 4=hour | 5=minute | 6=second | 7=millisecond }

Returns
  Specified attribute or -1 if an error occurred.

## ◆ curl_path()

const char * curl_path | ( | const char *const | user_path,
|  | const bool | reinit_path )

Search path of an executable.

Get the file or directory attributes with support for UTF-8 paths (Windows only). Get/set path to the Program Files/ directory (Windows only).

Parameters

  user_path | Specified path, or `0` to get the path currently used.
  reinit_path | Force path to be recalculated (may take some time).

Returns
  Path containing the program files. Get/set path to the `curl` binary.

Parameters

  user_path | Specified path, or `0` to get the path currently used.
  reinit_path | Force path to be recalculated (may take some time).

Returns
  Path containing the `curl` binary.

## ◆ dcraw_path()

const char * dcraw_path | ( | const char *const | user_path,
|  | const bool | reinit_path )

Get/set path to the `dcraw` binary.

Parameters

  user_path | Specified path, or `0` to get the path currently used.
  reinit_path | Force path to be recalculated (may take some time).

Returns
  Path containing the `dcraw` binary.

## ◆ ffmpeg_path()

const char * ffmpeg_path | ( | const char *const | user_path,
|  | const bool | reinit_path )

Get/set path to the FFMPEG's `ffmpeg` binary.

Parameters

  user_path | Specified path, or `0` to get the path currently used.
  reinit_path | Force path to be recalculated (may take some time).

Returns
  Path containing the `ffmpeg` binary.

## ◆ graphicsmagick_path()

const char * graphicsmagick_path | ( | const char *const | user_path,
|  | const bool | reinit_path )

Get/set path to the GraphicsMagick's `gm` binary.

Parameters

  user_path | Specified path, or `0` to get the path currently used.
  reinit_path | Force path to be recalculated (may take some time).

Returns
  Path containing the `gm` binary.

## ◆ gunzip_path()

const char * gunzip_path | ( | const char *const | user_path,
|  | const bool | reinit_path )

Get/set path to the `gunzip` binary.

Parameters

  user_path | Specified path, or `0` to get the path currently used.
  reinit_path | Force path to be recalculated (may take some time).

Returns
  Path containing the `gunzip` binary.

## ◆ gzip_path()

const char * gzip_path | ( | const char *const | user_path,
|  | const bool | reinit_path )

Get/set path to the `gzip` binary.

Parameters

  user_path | Specified path, or `0` to get the path currently used.
  reinit_path | Force path to be recalculated (may take some time).

Returns
  Path containing the `gzip` binary.

## ◆ imagemagick_path()

const char * imagemagick_path | ( | const char *const | user_path,
|  | const bool | reinit_path )

Get/set path to the ImageMagick's `convert` binary.

Parameters

  user_path | Specified path, or `0` to get the path currently used.
  reinit_path | Force path to be recalculated (may take some time).

Returns
  Path containing the `convert` binary.

## ◆ medcon_path()

const char * medcon_path | ( | const char *const | user_path,
|  | const bool | reinit_path )

Get/set path to the Medcon's `medcon` binary.

Parameters

  user_path | Specified path, or `0` to get the path currently used.
  reinit_path | Force path to be recalculated (may take some time).

Returns
  Path containing the `medcon` binary.

## ◆ temporary_path()

const char * temporary_path | ( | const char *const | user_path,
|  | const bool | reinit_path )

Get/set path to store temporary files.

Parameters

  user_path | Specified path, or `0` to get the path currently used.
  reinit_path | Force path to be recalculated (may take some time).

Returns
  Path where temporary files can be saved.

## ◆ wget_path()

const char * wget_path | ( | const char *const | user_path,
|  | const bool | reinit_path )

Get/set path to the `wget` binary.

Parameters

  user_path | Specified path, or `0` to get the path currently used.
  reinit_path | Force path to be recalculated (may take some time).

Returns
  Path containing the `wget` binary.

## ◆ split_filename()

const char * split_filename | ( | const char *const | filename,
|  | char *const | body = 0 )

Split filename into two C-strings `body` and `extension`.

filename and body must not overlap!

## ◆ fread()

template<typename T>

size_t fread | ( | T *const | ptr,
|  | const size_t | nmemb,
|  | std::FILE * | stream )

Read data from file.

Parameters

  [out] | ptr | Pointer to memory buffer that will contain the binary data read from file.
  | nmemb | Number of elements to read.
  | stream | File to read data from.

Returns
  Number of read elements.

Note
  Same as std::fread() but may display warning message if all elements could not be read.

## ◆ fwrite()

template<typename T>

size_t fwrite | ( | const T * | ptr,
|  | const size_t | nmemb,
|  | std::FILE * | stream )

Write data to file.

Parameters

  | ptr | Pointer to memory buffer containing the binary data to write on file.
  | nmemb | Number of elements to write.
  [out] | stream | File to write data on.

Returns
  Number of written elements.

Note
  Similar to std::fwrite but may display warning messages if all elements could not be written.

## ◆ fempty()

void fempty | ( | std::FILE *const | file,
|  | const char *const | filename )

Create an empty file.

Parameters

  file | Input file (can be `0` if `filename` is set).
  filename | Filename, as a C-string (can be `0` if `file` is set).

## ◆ ftype()

const char * ftype | ( | std::FILE *const | file,
|  | const char *const | filename )

Try to guess format from an image file.

Parameters

  file | Input file (can be `0` if `filename` is set).
  filename | Filename, as a C-string (can be `0` if `file` is set).

Returns
  C-string containing the guessed file format, or `0` if nothing has been guessed.

## ◆ load_network()

char * load_network | ( | const char *const | url,
|  | char *const | filename_local,
|  | const unsigned int | timeout,
|  | const bool | try_fallback,
|  | const char *const | referer,
|  | const char *const | user_agent )

Load file from network as a local temporary file.

Parameters

  | url | URL of the filename, as a C-string.
  [out] | filename_local | C-string containing the path to a local copy of `filename`.
  | timeout | Maximum time (in seconds) authorized for downloading the file from the URL.
  | try_fallback | When using libcurl, tells using system calls as fallbacks in case of libcurl failure.
  | referer | Referer used, as a C-string.
  | user_agent | User agent used, as a C-string.

Returns
  Value of `filename_local`.

Note
  Use the `libcurl` library, or the external binaries `wget` or `curl` to perform the download.

## ◆ files()

CImgList< char > files | ( | const char *const | path,
|  | const bool | is_pattern = false,
|  | const unsigned int | mode = 2,
|  | const bool | include_path = false )

Return list of files/directories in specified directory.

Parameters

  path | Path to the directory. Set to 0 for current directory.
  is_pattern | Tell if specified path has a matching pattern in it.
  mode | Output type, can be primary { 0=files only | 1=folders only | 2=files + folders }.
  include_path | Tell if `path` must be included in resulting filenames.

Returns
  A list of filenames.

## ◆ dialog()

template<typename t>

int dialog | ( | const char *const | title,
|  | const char *const | msg,
|  | const char *const | button1_label,
|  | const char *const | button2_label,
|  | const char *const | button3_label,
|  | const char *const | button4_label,
|  | const char *const | button5_label,
|  | const char *const | button6_label,
|  | const CImg< t > & | logo,
|  | const bool | is_centered = false )

Display a simple dialog box, and wait for the user's response.

Parameters

  title | Title of the dialog window.
  msg | Main message displayed inside the dialog window.
  button1_label | Label of the 1st button.
  button2_label | Label of the 2nd button (`0` to hide button).
  button3_label | Label of the 3rd button (`0` to hide button).
  button4_label | Label of the 4th button (`0` to hide button).
  button5_label | Label of the 5th button (`0` to hide button).
  button6_label | Label of the 6th button (`0` to hide button).
  logo | Image logo displayed at the left of the main message.
  is_centered | Tells if the dialog window must be centered on the screen.

Returns
  Index of clicked button (from `0` to `5`), or `-1` if the dialog window has been closed by the user.

Note
  - Up to 6 buttons can be defined in the dialog window.
  - The function returns when a user clicked one of the button or closed the dialog window.
  - If a button text is set to 0, the corresponding button (and the following) will not appear in the dialog box. At least one button must be specified.

Copyrights (C) From october 2004, David Tschumperlé - GREYC UMR CNRS 6072, Image team.
Copyrights (C) January->September 2004, David Tschumperlé.
Copyrights (C) 2000->2003, David Tschumperlé - INRIA Sophia-Antipolis. Odyssée group.