The CImg Library - C++ Template Image Processing Toolkit

[ Main ] [ Download ] [ Screenshots ] [ FAQ ] [ Tutorial ] [ Documentation ] [ Forum ] [ Links ]

- Main Page
- Modules
- Namespaces
- Classes

- Class List
- Class Hierarchy
- Class Members

Public Member Functions
CImgException Struct Reference

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

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

List of all members.

## Public Member Functions

const char * | what () const throw ()
| Return a C-string containing the error message associated to 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`. CImgException is never thrown itself. Derived classes that specify the type of errord are thrown instead. These derived classes can be:

- CImgArgumentException: Thrown when one argument of a called `CImg` function is invalid. This is probably one of the most thrown exception by `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 to a called `CImg` method does not fit the function 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 occured 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 by yourself, since they are expected to be thrown only by `CImg`. 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 get 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 () { ... }` bloc, as in the following example:

          #define "CImg.h"
          using namespace cimg_library;
          int main() {
            cimg::exception_mode(0);                                    // Enable quiet exception mode.
            try {
              ...                                                       // Here, do what you want to stress the CImg library.
            } catch (CImgException &e) {                                // You succeeded: something went wrong!
              std::fprintf(stderr,"CImg Library Error: %s",e.what());   // Display your custom error message.
              ...                                                       // Do what you want now to save the ship!
              }
            }