Errors

Error handling in the Erbsland Regular Expression library is intentionally kept simple. The entire library uses a single exception type for error reporting: Error.

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

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 Encoding error is thrown.

Pattern Compilation Errors

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

Parser The pattern contains a syntax error.
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:

Engine Indicates an internal execution problem.
Limit A resource or complexity limit was exceeded during matching.
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.

Diagnostics →

Interfaces and Types

class Error : public std::runtime_error

The error class for all regular expression operations.

Public Functions

template<typename MsgFwd> inline Error(const ErrorCategory errorCategory, MsgFwd &&msg, ErrorSupplements supplements = {})

Create a new error.

Parameters:

errorCategory – The error category.
msg – The error message.
supplements – Optional position information.

inline ErrorCategory category() const noexcept: Get the error category.

inline const std::string &message() const noexcept: Get the original error message without the automatically formatted category/position prefix.

inline std::size_t index() const noexcept: Get the character index associated with the error, or ErrorSupplements::cNoValue.

inline std::size_t line() const noexcept: Get the line associated with the error, or ErrorSupplements::cNoValue.

inline std::size_t column() const noexcept: Get the column associated with the error, or ErrorSupplements::cNoValue.

enum class erbsland::re::ErrorCategory : uint8_t

The category of an Error.

Values:

enumerator Encoding: An encoding error.

enumerator Parser: A parser error.

enumerator Format: A format error in a replacement string.

enumerator Assembler: An assembler error.

enumerator Engine: An engine error.

enumerator Timeout: A timeout error.

enumerator Limit: A limit error.

enumerator Internal: An internal error.