CImgException Struct Reference

Instances of CImgException are thrown when errors are encountered in a CImg function call. More...

#include <CImg.h>

Inherits exception.

Inherited by CImgArgumentException, CImgDisplayException, CImgIOException, CImgInstanceException, and CImgWarningException.

Public Member Functions
const char *	what () const throw ()
	Return a C-string containing the error message associated with the thrown exception.

Detailed Description

Instances of CImgException are thrown when errors are encountered in a CImg function call.

Overview

CImgException is the base class of all exceptions thrown by CImg (except CImgAbortException). CImgException is never thrown directly. Derived classes that specify the type of error are thrown instead. These classes can be:

• CImgAbortException: Thrown when a computationally-intensive function is aborted by an external signal. This is the only non-derived exception class.
• CImgArgumentException: Thrown when one argument of a called CImg function is invalid. This is probably one of the most commonly thrown exceptions in CImg. For instance, the following example throws a CImgArgumentException:

  CImg<float> img(100,100,1,3); // Define a 100x100 color image with float-valued pixels
  img.mirror('e'); // Try to mirror image along the (non-existing) 'e'-axis

• CImgDisplayException: Thrown when something went wrong during the display of images in CImgDisplay instances.
• CImgInstanceException: Thrown when an instance associated with a called CImg function does not meet the function's requirements. For instance, the following example throws a CImgInstanceException:

  const CImg<float> img; // Define an empty image
  const float value = img.at(0); // Try to read first pixel value (does not exist)

• CImgIOException: Thrown when an error occurred when trying to load or save image files. This happens when trying to read files that do not exist or with invalid formats. For instance, the following example throws a CImgIOException:

  const CImg<float> img("missing_file.jpg"); // Try to load a file that does not exist

• CImgWarningException: Thrown only if configuration macro cimg_strict_warnings is set, and when a CImg function has to display a warning message (see cimg::warn()).

It is not recommended to throw CImgException instances manually, as they are intended to be thrown only by the CImg library. When an error occurs in a library function call, CImg may display error messages on the screen or on the standard output, depending on the current CImg exception mode. The CImg exception mode can be queried and set by functions cimg::exception_mode() and cimg::exception_mode(unsigned int).

Exceptions handling

In all cases, when an error occurs in CImg, an instance of the corresponding exception class is thrown. This may lead the program to break (this is the default behavior), but you can bypass this behavior by handling the exceptions by yourself, using a usual try { ... } catch () { ... } block, as in the following example:

#include "CImg.h"
using namespace cimg_library;
int main() {
  cimg::exception_mode(0); // Enable quiet exception mode
  try {
    ... // Here, do what you want to stress CImg
  } catch (CImgException& e) { // You succeeded: something went wrong!
    std::fprintf(stderr,"CImg Library Error: %s",e.what()); // Display your custom error message
    ... // Perform necessary recovery or cleanup steps here
    }
  }