Settings

The Settings class allows you to control which features are accepted and which limits apply when compiling and executing regular expressions.

Settings are applied during compilation and define the behaviour of the resulting RegEx instance. They are especially important when your application processes patterns from external or untrusted sources, such as user configuration files or plug-in systems.

Limiting the Run-Time

When working with externally provided patterns, it is strongly recommended to limit the maximum run-time of matching operations.

Using setTimeout, you can define a per-call time limit for all matching operations performed by a RegEx instance.

If a matching operation exceeds the configured timeout, it is aborted and an Error exception with the error category Timeout is thrown.

This mechanism protects your application against excessively complex patterns or pathological input that would otherwise lead to long or unbounded execution times.

Setting Pattern Complexity Limits

In addition to time limits, the library provides a set of limits that restrict individual aspects of pattern complexity, such as nesting depth, repetition counts, or internal resource usage.

These limits can only be tightened, never extended. The library ships with a carefully chosen set of safe default limits that work well for most use cases.

Reducing these limits is useful when you want to:

  • Prevent excessive memory consumption

  • Guard against denial-of-service scenarios

  • Enforce predictable performance characteristics

All limits are checked during compilation or execution and result in a well-defined error if exceeded.

Enabling or Disabling Features

By default, the Erbsland Regular Expression library enables a number of compatibility features to ease migration from existing regular expression engines.

While convenient, some of these features come with ambiguities, surprising edge cases, or performance costs. For applications that accept patterns from external sources, it is often desirable to restrict the accepted syntax more strictly.

The feature flags in Settings allow you to explicitly control which parts of the pattern syntax are enabled.

A sensible starting point for untrusted patterns is disabling AllCompatibility, thereby accepting only the core, well-defined syntax.

Certain particularly problematic features are disabled by default:

Both can lead to unintuitive matches and make patterns harder to reason about. If you enable them, you should do so consciously and only when their behaviour is clearly understood and required.

Choosing the Right Settings

For internal, fully controlled patterns, the default settings are usually sufficient and provide maximum convenience.

For externally supplied patterns, we recommend:

  • Enabling a strict timeout

  • Tightening complexity limits where possible

  • Disabling compatibility features that are not explicitly required

This layered approach keeps your application robust while still allowing powerful and expressive regular expressions.

The Input Interface →

Interfaces and Types

class Settings

Settings for compiling regular expression patterns.

Public Functions

inline std::size_t maximumPatternLength() const noexcept

The maximum pattern length in characters.

inline void setMaximumPatternLength(std::size_t length) noexcept

Set the maximum pattern length.

Parameters:

length – A length in characters, or zero to reset back to default.

inline std::size_t maximumGroupNestingDepth() const noexcept

The maximum group nesting depth.

inline void setMaximumGroupNestingDepth(std::size_t depth) noexcept

Set the maximum group nesting depth.

Parameters:

depth – A depth in levels, or zero to reset back to default.

inline std::size_t maximumCaptureGroupCount() const noexcept

The maximum capture group count.

inline void setMaximumCaptureGroupCount(std::size_t count) noexcept

Set the maximum capture group count.

Parameters:

count – The maximum capture group count or zero to reset back to default.

inline std::size_t maximumSequenceLength() const noexcept

The maximum sequence length.

inline void setMaximumSequenceLength(std::size_t length) noexcept

Set the maximum sequence length.

Parameters:

length – A length in characters, or zero to reset back to default.

inline std::size_t maximumAlternativeCount() const noexcept

The maximum alternative count.

inline void setMaximumAlternativeCount(std::size_t count) noexcept

Set the maximum alternative count.

Parameters:

count – A count of alternatives, or zero to reset back to default.

inline std::size_t maximumQuantifierCount() const noexcept

Get the maximum quantifier count. This is the maximum for quantifier expressions like {n,m}

inline void setMaximumQuantifierCount(std::size_t count) noexcept

Set the maximum quantifier count.

Parameters:

count – The maximum quantifier count, or zero to reset back to default.

inline std::chrono::milliseconds timeout() const noexcept

Access the current timeout.

Returns:

The current timeout. Zero means no timeout.

inline void setTimeout(const std::chrono::milliseconds timeout) noexcept

Set a timeout for all calls.

Parameters:

timeout – The timeout to set, or zero to disable timeout.

inline bool hasFeature(const Feature feature) const noexcept

Test if a feature is enabled.

Parameters:

feature – The feature to test.

inline void disableFeature(const Feature feature) noexcept

Disable a feature.

Parameters:

feature – The feature to disable.

inline void enableFeature(const Feature feature) noexcept

Enable a feature

Parameters:

feature – The feature to enable.

inline std::string toString() const noexcept

Create a string representation for this settings object.

enum class erbsland::re::Feature : uint16_t

A feature of the regular expression syntax or engine.

Values:

enumerator QuotedLiterals

Using quotes \\Q...\\E.

enumerator EscapeBell

The escape sequence \\a for bell character.

enumerator EscapeControl

The escape sequence \\cX for control character.

enumerator EscapeEscape

The escape sequence \\e for the escape character.

enumerator EscapeFormFeed

The escape sequence \\f for form feed character.

enumerator EscapeOctal

The escape sequence \\o{nnn} for octal character.

enumerator EscapeHex

The escape sequence \\xnn and \\x{nnnn} for hexadecimal character.

enumerator EscapeLongUnicode

The escape sequence \\Unnnnnnnn for 32-bit Unicode character.

enumerator EscapeHorizontalSpace

The escape sequence \\h for horizontal space character.

enumerator EscapeVerticalSpace

The escape sequence \\v for vertical space character.

enumerator PosixClasses

Using POSIX character classes like [:digit:]

enumerator AnchorLowercaseZ

Using the anchor \\z for the end of the string.

enumerator EmptyAlternatives

Allow empty alternatives, like (?:a|b|)

enumerator EmptyGroups

Allow empty groups, like ()

enumerator AllCompatibility

All compatibility options.

enumerator Default

The default value (enable all compatibility features by default)

class Features : public impl::EnumFlags<Features, Feature>

Features for compiling regular expressions.

Public Functions

inline std::string toString() const

Create a diagnostic string for the enabled features.