Skip to content

erbsland-dev/erbsland-cpp-re

BranchesTags

Repository files navigation

Erbsland Regular Expression Library

The Erbsland Regular Expression Library is a secure and reliable regular expression engine for modern C++.
It is designed to be lightweight, dependency-free, and predictable, while offering solid UTF-8 and Unicode support out of the box.

You can embed the library directly into your project to provide regular expression matching without pulling in large external dependencies. The pattern syntax is inspired by a pragmatic mix of PCRE and Python regular expressions, focusing on clarity, safety, and maintainability.

Internally, the engine implements a carefully optimized variant of Thompson’s NFA algorithm, adapted for modern C++ and robust execution under strict resource limits.

Feature Overview

  • Zero dependencies – easy to embed and audit.
  • Strong focus on security and reliability.
  • Full UTF-8 support with strict input validation.
  • Rich regular expression syntax:
    • Greedy, lazy, and possessive quantifiers
    • Atomic groups
  • Optional syntax compatibility with PCRE, Python, and other popular regex engines.
  • Built-in time and memory limits with safe defaults.
  • Solid Unicode support without relying on ICU:
    • Full Unicode character classes
    • Case-insensitive matching using simple case folding
  • Configurable string type support:
    • std::string or std::u8string (selected at build time)
  • Human-readable error messages when parsing regular expressions.
  • Rich API for:
    • Finding first or all matches
    • Replacing text using placeholders
  • Efficient coroutine-based matching.
  • String-view-based processing with no unnecessary allocations.
  • Abstract input interface for custom or streaming input sources.
  • Diagnostic Tools:
    • Disassembler to display the generated code for any pattern.
    • Assembler to write custom regex engines.

Non-Features and Design Goals

This library intentionally avoids certain features to remain predictable, secure, and memory-efficient:

  • To keep the memory footprint low and matching deterministic:
    • No Unicode normalization
    • No multi-character case folding
    • No Unicode character names
  • The primary goal is security, not maximum throughput:
    • Matching is efficient, but not intended for workloads where regex performance is the main bottleneck.
    • Regular matching is fast, but due to almost no program optimizations, strict validation of the input, and the design of the NFA algorithm, not as fast as RE2 or PCRE.
  • Some advanced constructs are deliberately not supported:
    • No backreferences
    • No lookahead assertions
    • No conditional patterns

Project Status

  • ✔ Stable and suitable for production use (for UTF-8 based strings).
  • ✔ Public API is stable
  • ✔ Tested on:
    • Linux (GCC)
    • macOS (Clang)
    • Windows (MSVC)
  • ✗ UTF-16 and UTF-32 support:
    • Implemented but not fully tested. Use it at your own risk.
    • Not documented.

Quick Start

#include <iostream> #include <string> #include <el/re/regex.hpp> using namespace el::re; int main() { try { auto re = RegEx::compile(R"(\d+)"); auto text = std::string{"abc 12345 xyz"}; if (auto match = re->findFirst(text); match != nullptr) { std::cout << "Found a number: " << match->content(0) << "\n"; } } catch (const Error &error) { std::cerr << error.what() << "\n"; return 1; } return 0; }

Performance Comparison

Direct performance comparisons between regular expression engines are often misleading.
The following benchmarks are provided only as a rough indication of performance characteristics.

All benchmarks were run on a 2021 MacBook Pro with an Apple M1 Max CPU and ample memory.

Important notes:

  • The Erbsland Regular Expression Library:
    • Always reads and validates UTF-8 input
    • Performs Unicode-aware comparisons in all modes
    • The compiled program from the pattern is not optimized for performance
    • The engine has almost no speed optimizations
  • Neither PCRE nor std::regex enforce strict UTF-8 validation (for this benchmark).
  • “ASCII mode” in Erbsland RE only affects character class handling; input is still processed as Unicode.

Benchmark Results

These are the results for version 1.0.0 of the library.

Benchmarking file: war_and_peace.txt (3.20 MB) ┌─────────────┬─────────────┬─────────┬───────────┬─────┬───────────────────────┬─────────┐ │ Pattern │ Library │ Mode │ Time (ms) │ % │ Bar │ Matches │ ├─────────────┼─────────────┼─────────┼───────────┼─────┼───────────────────────┼─────────┤ │ Words │ erbsland-re │ Unicode │ 145.751 │ 100 │ ██████████ │ 576584 │ │ │ pcre2 │ Unicode │ 66.280 │ 45 │ ████▌ │ 576584 │ │ │ erbsland-re │ Ascii │ 144.482 │ 99 │ ██████████ │ 586871 │ │ │ std::regex │ Ascii │ 232.292 │ 159 │ ████████████████ │ 586871 │ │ │ pcre2 │ Ascii │ 45.934 │ 32 │ ███ │ 586871 │ ├─────────────┼─────────────┼─────────┼───────────┼─────┼───────────────────────┼─────────┤ │ Capitalized │ erbsland-re │ Unicode │ 86.961 │ 100 │ ██████████ │ 50038 │ │ │ pcre2 │ Unicode │ 8.242 │ 9 │ █ │ 50038 │ │ │ erbsland-re │ Ascii │ 86.307 │ 99 │ ██████████ │ 60182 │ │ │ std::regex │ Ascii │ 215.900 │ 248 │ ████████████████████► │ 60182 │ │ │ pcre2 │ Ascii │ 7.872 │ 9 │ █ │ 60182 │ └─────────────┴─────────────┴─────────┴───────────┴─────┴───────────────────────┴─────────┘ 
Benchmarking file: shakespeare.html (6.98 MB) ┌───────────────────┬─────────────┬─────────┬───────────┬─────┬───────────────────────┬─────────┐ │ Pattern │ Library │ Mode │ Time (ms) │ % │ Bar │ Matches │ ├───────────────────┼─────────────┼─────────┼───────────┼─────┼───────────────────────┼─────────┤ │ Words │ erbsland-re │ Unicode │ 310.203 │ 100 │ ██████████ │ 1301628 │ │ │ pcre2 │ Unicode │ 166.467 │ 54 │ █████▌ │ 1301628 │ │ │ erbsland-re │ Ascii │ 309.185 │ 100 │ ██████████ │ 1301773 │ │ │ std::regex │ Ascii │ 521.527 │ 168 │ █████████████████ │ 1301773 │ │ │ pcre2 │ Ascii │ 100.895 │ 33 │ ███▌ │ 1301773 │ ├───────────────────┼─────────────┼─────────┼───────────┼─────┼───────────────────────┼─────────┤ │ Capitalized │ erbsland-re │ Unicode │ 205.873 │ 100 │ ██████████ │ 184903 │ │ │ pcre2 │ Unicode │ 29.793 │ 14 │ █▌ │ 184903 │ │ │ erbsland-re │ Ascii │ 217.043 │ 105 │ ██████████▌ │ 185027 │ │ │ std::regex │ Ascii │ 493.012 │ 239 │ ████████████████████► │ 185027 │ │ │ pcre2 │ Ascii │ 27.376 │ 13 │ █▌ │ 185027 │ ├───────────────────┼─────────────┼─────────┼───────────┼─────┼───────────────────────┼─────────┤ │ URI │ erbsland-re │ Unicode │ 146.271 │ 100 │ ██████████ │ 10 │ │ │ pcre2 │ Unicode │ 8.598 │ 6 │ ▌ │ 10 │ │ │ erbsland-re │ Ascii │ 146.246 │ 100 │ ██████████ │ 10 │ │ │ std::regex │ Ascii │ 409.767 │ 280 │ ████████████████████► │ 10 │ │ │ pcre2 │ Ascii │ 8.365 │ 6 │ ▌ │ 10 │ ├───────────────────┼─────────────┼─────────┼───────────┼─────┼───────────────────────┼─────────┤ │ ExtractTocLinks │ erbsland-re │ Unicode │ 432.889 │ 100 │ ██████████ │ 44 │ │ │ pcre2 │ Unicode │ 6.351 │ 1 │ │ 44 │ │ │ erbsland-re │ Ascii │ 432.571 │ 100 │ ██████████ │ 44 │ │ │ std::regex │ Ascii │ 557.580 │ 129 │ █████████████ │ 44 │ │ │ pcre2 │ Ascii │ 6.175 │ 1 │ │ 44 │ ├───────────────────┼─────────────┼─────────┼───────────┼─────┼───────────────────────┼─────────┤ │ ExtractLicenseDiv │ erbsland-re │ Unicode │ 432.680 │ 100 │ ██████████ │ 1 │ │ │ pcre2 │ Unicode │ 6.412 │ 1 │ │ 1 │ │ │ erbsland-re │ Ascii │ 432.290 │ 100 │ ██████████ │ 1 │ │ │ std::regex │ Ascii │ 543.849 │ 126 │ ████████████▌ │ 1 │ │ │ pcre2 │ Ascii │ 6.205 │ 1 │ │ 1 │ ├───────────────────┼─────────────┼─────────┼───────────┼─────┼───────────────────────┼─────────┤ │ HTML Tags │ erbsland-re │ Unicode │ 195.751 │ 100 │ ██████████ │ 159584 │ │ │ pcre2 │ Unicode │ 18.203 │ 9 │ █ │ 159584 │ │ │ erbsland-re │ Ascii │ 190.732 │ 97 │ █████████▌ │ 159584 │ │ │ std::regex │ Ascii │ 416.028 │ 213 │ ████████████████████► │ 159584 │ │ │ pcre2 │ Ascii │ 18.031 │ 9 │ █ │ 159584 │ └───────────────────┴─────────────┴─────────┴───────────┴─────┴───────────────────────┴─────────┘ 
Benchmarking file: shakespeare.txt (5.38 MB) ┌─────────────┬─────────────┬─────────┬───────────┬─────┬────────────────────┬─────────┐ │ Pattern │ Library │ Mode │ Time (ms) │ % │ Bar │ Matches │ ├─────────────┼─────────────┼─────────┼───────────┼─────┼────────────────────┼─────────┤ │ Words │ erbsland-re │ Unicode │ 247.719 │ 100 │ ██████████ │ 996052 │ │ │ pcre2 │ Unicode │ 119.407 │ 48 │ █████ │ 996052 │ │ │ erbsland-re │ Ascii │ 242.508 │ 98 │ ██████████ │ 996199 │ │ │ std::regex │ Ascii │ 403.254 │ 163 │ ████████████████▌ │ 996199 │ │ │ pcre2 │ Ascii │ 79.064 │ 32 │ ███ │ 996199 │ ├─────────────┼─────────────┼─────────┼───────────┼─────┼────────────────────┼─────────┤ │ Capitalized │ erbsland-re │ Unicode │ 212.670 │ 100 │ ██████████ │ 180019 │ │ │ pcre2 │ Unicode │ 27.846 │ 13 │ █▌ │ 180019 │ │ │ erbsland-re │ Ascii │ 162.808 │ 77 │ ███████▌ │ 180140 │ │ │ std::regex │ Ascii │ 380.359 │ 179 │ ██████████████████ │ 180140 │ │ │ pcre2 │ Ascii │ 26.088 │ 12 │ █ │ 180140 │ └─────────────┴─────────────┴─────────┴───────────┴─────┴────────────────────┴─────────┘

Pattern Legend

  • Words
    \w+
  • Capitalized
    \b[A-Z][a-z]*\b
  • URI
    https?://[a-zA-Z0-9\.]+
  • ExtractTocLinks
    <a href="#(chap([0-9]{2}))" class="pginternal">([^<]+)</a>
  • ExtractLicenseDiv
    <div id="(([^-\"]+)-([^-"]+)-([^"]+))">([^<]+)</div>
  • HTML Tags
    <[a-z1-6]+[^>]*>

Requirements

  • A C++20-compliant compiler:
    • Clang
    • GCC
    • MSVC
  • CMake 3.23 or newer

License

Copyright © 2026 Tobias Erbsland
https://erbsland.dev/

Licensed under the Apache License, Version 2.0.
You may obtain a copy at:
http://www.apache.org/licenses/LICENSE-2.0

Distributed on an “AS IS” basis, without warranties or conditions of any kind.
See the LICENSE file for full details.

About

A secure and predictable regular expression library for modern C++. Dependency-free, UTF-8 aware, and built on a Thompson NFA engine with strict limits, clear APIs, streaming input support, and diagnostics. Designed for reliability over raw speed.

re.erbsland.dev/

Topics

security unicode streaming cpp regex utf-8 regular-expression timeout robust regular-expression-engine nfa deterministic utf-16 utf-32 dependency-free cpp20 thompson-algorithm cpp23 finite-automaton

Resources

Readme

License

Apache-2.0 license

Code of conduct

Code of conduct

Contributing

Contributing

Security policy

Security policy
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases 1

First Public Release of the Erbsland Regular Expression Library Latest
Jan 17, 2026

Sponsor this project

Contributors

Languages