.. _particle-errors-page:

##############
Error Handling
##############

All operations that can fail accept an optional :class:`Error <cee::pt::Error>` pointer. The error codes are defined by
the :enum:`Error::Code <cee::pt::Error::Code>` enum:

.. list-table::
   :widths: 30 70
   :header-rows: 1

   * - Code
     - Description
   * - ``ERR_NOT_SET``
     - No error has been set (default initial state).
   * - ``ERR_FILE_NOT_FOUND``
     - The specified file path does not exist.
   * - ``ERR_FILE_OPEN``
     - The file could not be opened (permissions, locked).
   * - ``ERR_FILE_READ``
     - An I/O error occurred while reading.
   * - ``ERR_UNSUPPORTED_FORMAT``
     - No reader recognized the file format.
   * - ``ERR_INVALID_FORMAT``
     - The file is corrupt or has an unsupported version.
   * - ``ERR_NO_DATA``
     - The dataset contains no frames or particles.
   * - ``ERR_OUT_OF_RANGE``
     - A frame index or field name is out of bounds.
   * - ``ERR_NOT_OPEN``
     - An operation was attempted on a model/reader that is not open.
   * - ``ERR_USER_DEFINED_MESSAGE``
     - A custom error message was set (use :func:`userDefinedErrorMessage() <cee::pt::Error::userDefinedErrorMessage>`).

Example:

.. code-block:: cpp

    cee::pt::Error error;
    if (!model->setCurrentFrameIndex(999, &error))
    {
        if (error.errorCode() == cee::pt::Error::ERR_OUT_OF_RANGE)
        {
            // Frame index exceeds frameCount()
        }
    }
