crispthinking/IronRe2

.NET Bindings to the Google Re2 library

Iron RE2

RE2 is a fast and powerful regular expression library created and maintained by Google. This repository provides a managed wrapper so it can be used from .NET.

> Install-Package IronRe2

IronRe2 targets the .NET Standard 2.0 framework. This means it is can be used from both .NET Core and .NET Framework. If you're targeting Linux, Windows, or macOS then it's batteries included. If not then you'll need to supply your own version of the cre2 library.

Usage

The simplest operation is to check if a pattern matches a given search text. If you're just doing this once then you can use the "easy match" API:

using IronRe2;

Assert.True(Regex.IsMatch(@"\d+", "with 1 digit"));
Assert.False(Regex.IsMatch(@"\d+", "digit-less"));

To find the extent of the match then Regex.Find can be used:

using IronRe2;

var match = Regex.Find(@"\d+", "with 1 digit");
Assert.True(match.Match);
Assert.Equal(5, match.Start);
Assert.Equal(6, match.End);

If you're going to be re-using the same pattern it makes sense to create a Regex object and hold on to it:

using IronRe2;

using (var re = new Regex("\w+"))
{
   Assert.False(re.IsMatch("(12323, 232, 4325235)"));

   var match = re.Find("hello world");
   Assert.True(match.Matched);
   Assert.Equal(0, match.Start);
   Assert.Equal(5, match.End);
}

To get information about capture group locations compiled Regexes offer a Captures API:

using IronRe2;

using (var re = new Regex(@"(?P<year>\d{4})-(?P<month>\d{2})-(?P<day>\d{2})"))
{
    var haystack = "The first woman in space launched on 1963-06-16 in Vostok 6";

    var captures = re.Captures(haystack);

    Assert.True(captures.Matched);

    // The first capture group is the whole match.
    Assert.True(captures[0].Matched);

    // Each capture group has position information
    Assert.True(captures[1].Matched);
    Assert.Equal(37, captures[1].Start);
    Assert.Equal(41, captures[1].End);

    /// As well as the UTF-8 indices the extracted text is available
    Assert.True(captures[2].Matched);
    Assert.Equal("06", captures[2].ExtractedText);

    // capture group indices can be looked up by name from the `Regex`
    Assert.True(captures[re.FindNamedCapture("day")].Matched);
}

Related Resources

This project depends on pre-built pacakges containing the native RE2 code. If you wish to target a runtime that isn't currently packaged then you can provide your own copy of libcre2.

For performance benchmarks comparing this project to .NET regex see the IronRure benchmarks.

License

This repository is distributed under the MIT license.