.. index::
    single: Error
    single: Error Handling

******
Errors
******

Error handling in the Erbsland Regular Expression library is intentionally kept
simple. The entire library uses a single exception type for error reporting:
:cpp:class:`Error <erbsland::re::Error>`.

In the simplest case, you can enclose all usage of the library in a single
``try / catch`` block:

.. code-block:: cpp

    try {
        // Use the regular expression library.
    } catch (const el::re::Error &error) {
        // Report the error and terminate the application.
    }

Design Rationale
================

All errors thrown by the Erbsland Regular Expression library represent *fatal*
conditions for the current operation.

An exception is raised when:

*   a pattern cannot be compiled,
*   input data is malformed,
*   a configured limit is exceeded, or
*   a matching operation runs longer than allowed.

During normal operation with valid patterns and input, no exceptions are
thrown.

Because of this, small tools and utilities can often handle errors at a single,
central location. In many cases, such an error means the program cannot perform
its task anyway and should terminate with a clear diagnostic.

For security-facing or long-running applications, error handling can be more
fine-grained. The built-in error categories allow you to distinguish between
invalid patterns, problematic input data, and resource-related failures, making
it possible to reject individual requests while keeping the application
running.

Error Sources
=============

Errors can originate from several stages of using the library.

Character Encoding Errors
-------------------------

Character encoding errors may occur during *any* API call that processes text.
If invalid encoding is encountered, an
:cpp:any:`Encoding <erbsland::re::ErrorCategory::Encoding>` error is thrown.

Pattern Compilation Errors
--------------------------

While compiling regular expressions, the following error categories may occur:

*   :cpp:any:`Parser <erbsland::re::ErrorCategory::Parser>`
    The pattern contains a syntax error.

*   :cpp:any:`Limit <erbsland::re::ErrorCategory::Limit>`
    A configured or built-in complexity limit was exceeded during compilation.

When working with static or hard-coded patterns, it is usually best *not* to
catch these exceptions. A failing compilation typically indicates a programming
error, and letting the application fail fast allows the debugger to point
directly to the problematic pattern.

Matching Errors
---------------

When matching text, the following error categories may occur:

*   :cpp:any:`Engine <erbsland::re::ErrorCategory::Engine>`
    Indicates an internal execution problem.

*   :cpp:any:`Limit <erbsland::re::ErrorCategory::Limit>`
    A resource or complexity limit was exceeded during matching.

*   :cpp:any:`Timeout <erbsland::re::ErrorCategory::Timeout>`
    The configured execution time limit was reached.

Engine errors are typically only encountered when using custom-written programs
or extensions that violate internal assumptions, such as invalid jump targets.
If you want to be conservative, handling engine errors in the same way as limit
errors is a reasonable approach.

.. button-ref:: diagnostics
    :ref-type: doc
    :color: success
    :align: center
    :expand:
    :class: sd-fs-5 sd-font-weight-bold sd-p-2 sd-my-4

    Diagnostics →

Interfaces and Types
====================

.. doxygenclass:: erbsland::re::Error
    :members:

.. doxygenenum:: erbsland::re::ErrorCategory