RegexForge.Patterns 1.0.0

RegexForge

A production-ready .NET library providing battle-tested regular expressions, source-generated validators, and a fluent, consistent API — so you stop re-deriving the email regex from StackOverflow every time you start a project.

Introduction

RegexForge gives you three things, layered:

• RegexForge.Patterns — raw pattern string constants, if you just want the regex.
• RegexForge.Validation — strongly-typed validators (EmailPattern.IsValid(...)) with caching and source-generated performance built in, no setup required.
• RegexForge.Core — the abstractions underneath, useful if you're building your own pattern library on the same foundation.

Every pattern ships with documented limitations. We'd rather tell you upfront that IbanPattern doesn't validate the checksum than have you find out in production.

Installation

dotnet add package RegexForge.Validation

RegexForge.Validation pulls in RegexForge.Core and RegexForge.Patterns automatically. If you only want the raw pattern strings without the validator API:

dotnet add package RegexForge.Patterns

Quick Start

using RegexForge.Validation;

bool isValid = EmailPattern.IsValid("john@example.com");      // true
bool isGuid  = GuidPattern.IsValid("not-a-guid");              // false

var match = EmailPattern.Match("Contact: jane@example.com");
Console.WriteLine(match.Value);                                // jane@example.com

string redacted = EmailPattern.Replace("Email me at me@x.com", "[hidden]");
// "Email me at [hidden]"

Supported Frameworks

The public API is identical across all three — your code doesn't change based on target.

Examples

// Validation
EmailPattern.IsValid(email);
GuidPattern.IsValid(value);
Ipv4Pattern.IsValid(ip);

// Matching
var match = EmailPattern.Match(value);
var all   = EmailPattern.Matches(value);
EmailPattern.TryMatch(value, out var found);

// String operations
string cleaned = EmailPattern.Replace(text, "[redacted]");
string[] parts = EmailPattern.Split(text);
int count       = EmailPattern.Count(text);

// Raw pattern access, if you need it
string pattern = RegexPatterns.Email;

See samples/ConsoleSample and samples/MinimalApiSample for complete, runnable examples including request-validation use in an ASP.NET Core endpoint.

Pattern Catalog (v1.0 — 34 patterns)

Full XML documentation, including known limitations per pattern, is available via IntelliSense or the documentation site.

Performance

RegexForge validators use a single cached instance per pattern, constructed once at first use:

• On net8.0/net10.0: a [GeneratedRegex]-produced Regex, compiled ahead of time.
• On netstandard2.0: a Regex built once with RegexOptions.Compiled.

Either way, you never pay regex construction cost more than once per process, and you never accidentally write new Regex(pattern) inside a hot path.

Benchmarks

Run locally:

dotnet run -c Release --project tests/RegexForge.Benchmarks/RegexForge.Benchmarks.csproj --framework net10.0

Warm-start (steady-state) — .NET 10.0.9, X64 RyuJIT AVX2

Baseline: RawRegexIsMatch_Valid (156 ns). Lower is better. All methods: 0 allocations.

RegexForge adds zero measurable overhead over a standalone [GeneratedRegex] (67.65 ns vs 66.24 ns — within noise). You get the clean API for free.

Cold-start (first-call cost) — RunStrategy.ColdStart, 5 launches

Measures the true first-call cost before any JIT/caching kicks in.

RegexForge's static initializer pays its setup cost once at first use, then allocates nothing for every subsequent call — unlike Regex(Compiled) which allocates 43 KB and takes 12 ms every time it is constructed.

Roadmap

See ROADMAP.md for the full v1/v2/v3 plan, including what's deliberately deferred and why (e.g. credit card validation, category-nested pattern browsing).

Contributing

See CONTRIBUTING.md, including the pattern submission checklist and the one category of pattern we won't accept (credit card numbers — PCI-DSS scope).

FAQ

Why isn't there an IsValidCreditCard? Deliberately deferred — see CONTRIBUTING.md.

Does IbanPattern/SwiftPattern validate the checksum? No — structural shape only. See the XML docs on each pattern for the specific limitation.

Why is RegexPatterns a single flat class instead of nested by category? Flat IntelliSense lookup (RegexPatterns.Em... → Email) is faster for the common case of "I know the pattern name" than requiring you to first know which category it lives in. Category-based browsing is being considered for v2 as an additive alias, not a replacement. See ROADMAP.md.

Does this support .NET Framework? Yes, via netstandard2.0 (.NET Framework 4.6.1+). Note: the netstandard2.0 code path is currently build-verified in CI but not yet behavior-tested with the same rigor as the net8.0/net10.0 paths — see CHANGELOG.md known limitations.

Is this fully RFC-compliant for email/URL/etc.? No regex-based validator is fully RFC 5322/3986 compliant — that's a known, accepted limitation of regex-based validation in general, not unique to this library. We aim for "correct for the overwhelming majority of real-world input," not formal RFC proof.

License

MIT — see LICENSE.