std.regex

import std.regex;
import std.stdio;
void main()
{
    // Print out all possible dd/mm/yy(yy) dates found in user input.
    auto r = regex(r"\b[0-9][0-9]?/[0-9][0-9]?/[0-9][0-9](?:[0-9][0-9])?\b");
    foreach (line; stdin.byLine)
    {
      // matchAll() returns a range that can be iterated
      // to get all subsequent matches.
      foreach (c; matchAll(line, r))
          writeln(c.hit);
    }
}
...

// Create a static regex at compile-time, which contains fast native code.
auto ctr = ctRegex!(`^.*/([^/]+)/?$`);

// It works just like a normal regex:
auto c2 = matchFirst("foo/bar", ctr);   // First match found here, if any
assert(!c2.empty);   // Be sure to check if there is a match before examining contents!
assert(c2[1] == "bar");   // Captures is a range of submatches: 0 = full match.

...
// multi-pattern regex
auto multi = regex([`\d+,\d+`,`(a-z]+):(\d+)`]);
auto m = "abc:43 12,34".matchAll(multi);
assert(m.front.whichPattern == 2);
assert(m.front[1] == "abc");
assert(m.front[2] == "43");
m.popFront();
assert(m.front.whichPattern == 1);
assert(m.front[1] == "12");
...

// The result of the `matchAll/matchFirst` is directly testable with if/assert/while.
// e.g. test if a string consists of letters:
assert(matchFirst("Letter", `^\p{L}+$`));

template Regex(Char)

Regex object holds regular expression pattern in compiled form.

Instances of this object are constructed via calls to regex. This is an intended form for caching and storage of frequently used regular expressions.

Example Test if this object doesn't contain any compiled pattern.

Regex!char r;
assert(r.empty);
r = regex(""); // Note: "" is a valid regex pattern.
assert(!r.empty);

Getting a range of all the named captures in the regex.

import std.range;
import std.algorithm;

auto re = regex(`(?P<name>\w+) = (?P<var>\d+)`);
auto nc = re.namedCaptures;
static assert(isRandomAccessRange!(typeof(nc)));
assert(!nc.empty);
assert(nc.length == 2);
assert(nc.equal(["name", "var"]));
assert(nc[0] == "name");
assert(nc[1..$].equal(["var"]));

alias StaticRegex = Regex(Char);

A StaticRegex is Regex object that contains D code specially generated at compile-time to speed up matching.

No longer used, kept as alias to Regex for backwards compatibility.

@trusted auto regex(S : C[], C)(const S[] patterns, const(char)[] flags = "")
if (isSomeString!S);

@trusted auto regex(S)(S pattern, const(char)[] flags = "")
if (isSomeString!S);

Compile regular expression pattern for the later execution.

Returns:

Regex object that works on inputs having the same character width as pattern.

Parameters:

S pattern	A single regular expression to match.
S[] patterns	An array of regular expression strings. The resulting Regex object will match any expression; use whichPattern to know which.
const(char)[] flags	The attributes (g, i, m, s and x accepted)

Throws:

RegexException if there were any errors during compilation.

Examples:

void test(S)()
{
    // multi-pattern regex example
    S[] arr = [`([a-z]+):(\d+)`, `(\d+),\d+`];
    auto multi = regex(arr); // multi regex
    S str = "abc:43 12,34";
    auto m = str.matchAll(multi);
    writeln(m.front.whichPattern); // 1
    writeln(m.front[1]); // "abc"
    writeln(m.front[2]); // "43"
    m.popFront();
    writeln(m.front.whichPattern); // 2
    writeln(m.front[1]); // "12"
}

import std.meta : AliasSeq;
static foreach (C; AliasSeq!(string, wstring, dstring))
    // Test with const array of patterns - see https://issues.dlang.org/show_bug.cgi?id=20301
    static foreach (S; AliasSeq!(C, const C, immutable C))
        test!S();

enum auto ctRegex(alias pattern, alias flags = []);

Compile regular expression using CTFE and generate optimized native machine code for matching it.

Returns:

StaticRegex object for faster matching.

Parameters:

pattern	Regular expression
flags	The attributes (g, i, m, s and x accepted)

struct Captures(R) if (isSomeString!R);

Captures object contains submatches captured during a call to match or iteration over RegexMatch range.

First element of range is the whole match.

Examples:

import std.range.primitives : popFrontN;

auto c = matchFirst("@abc#", regex(`(\w)(\w)(\w)`));
assert(c.pre == "@"); // Part of input preceding match
assert(c.post == "#"); // Immediately after match
assert(c.hit == c[0] && c.hit == "abc"); // The whole match
writeln(c[2]); // "b"
writeln(c.front); // "abc"
c.popFront();
writeln(c.front); // "a"
writeln(c.back); // "c"
c.popBack();
writeln(c.back); // "b"
popFrontN(c, 2);
assert(c.empty);

assert(!matchFirst("nothing", "something"));

// Captures that are not matched will be null.
c = matchFirst("ac", regex(`a(b)?c`));
assert(c);
assert(!c[1]);

@property R pre();

Slice of input prior to the match.

@property R post();

Slice of input immediately after the match.

@property R hit();

Slice of matched portion of input.

@property R front();

@property R back();

void popFront();

void popBack();

const @property bool empty();

inout inout(R) opIndex()(size_t i);

Range interface.

const nothrow @safe bool opCast(T : bool)();

Explicit cast to bool. Useful as a shorthand for !(x.empty) in if and assert statements.

import std.regex;

assert(!matchFirst("nothing", "something"));

const nothrow @property @safe int whichPattern();

Number of pattern matched counting, where 1 - the first pattern. Returns 0 on no match.

Examples:

import std.regex;
writeln(matchFirst("abc", "[0-9]+", "[a-z]+").whichPattern); // 2

R opIndex(String)(String i)
if (isSomeString!String);

Lookup named submatch.

import std.regex;
import std.range;

auto c = matchFirst("a = 42;", regex(`(?P<var>\w+)\s*=\s*(?P<value>\d+);`));
assert(c["var"] == "a");
assert(c["value"] == "42");
popFrontN(c, 2);
//named groups are unaffected by range primitives
assert(c["var"] =="a");
assert(c.front == "42");

const @property size_t length();

Number of matches in this object.

@property ref auto captures();

A hook for compatibility with original std.regex.

struct RegexMatch(R) if (isSomeString!R);

A regex engine state, as returned by match family of functions.

Effectively it's a forward range of Captures!R, produced by lazily searching for matches in a given input.

@property R pre();

@property R post();

@property R hit();

Shorthands for front.pre, front.post, front.hit.

inout @property inout(Captures!R) front();

void popFront();

auto save();

Functionality for processing subsequent matches of global regexes via range interface:

import std.regex;
auto m = matchAll("Hello, world!", regex(`\w+`));
assert(m.front.hit == "Hello");
m.popFront();
assert(m.front.hit == "world");
m.popFront();
assert(m.empty);

const @property bool empty();

Test if this match object is empty.

T opCast(T : bool)();

Same as !(x.empty), provided for its convenience in conditional statements.

inout @property inout(Captures!R) captures();

Same as .front, provided for compatibility with original std.regex.

auto match(R, RegEx)(R input, RegEx re)
if (isSomeString!R && isRegexFor!(RegEx, R));

auto match(R, String)(R input, String re)
if (isSomeString!R && isSomeString!String);

Start matching input to regex pattern re, using Thompson NFA matching scheme.

The use of this function is discouraged - use either of matchAll or matchFirst.

Delegating the kind of operation to "g" flag is soon to be phased out along with the ability to choose the exact matching scheme. The choice of matching scheme to use depends highly on the pattern kind and can done automatically on case by case basis.

Returns:

a RegexMatch object holding engine state after first match.

auto matchFirst(R, RegEx)(R input, RegEx re)
if (isSomeString!R && isRegexFor!(RegEx, R));

auto matchFirst(R, String)(R input, String re)
if (isSomeString!R && isSomeString!String);

auto matchFirst(R, String)(R input, String[] re...)
if (isSomeString!R && isSomeString!String);

Find the first (leftmost) slice of the input that matches the pattern re. This function picks the most suitable regular expression engine depending on the pattern properties.

re parameter can be one of three types:

• Plain string(s), in which case it's compiled to bytecode before matching.
• Regex!char (wchar/dchar) that contains a pattern in the form of compiled bytecode.
• StaticRegex!char (wchar/dchar) that contains a pattern in the form of compiled native machine code.

Returns:

Captures containing the extent of a match together with all submatches if there was a match, otherwise an empty Captures object.

auto matchAll(R, RegEx)(R input, RegEx re)
if (isSomeString!R && isRegexFor!(RegEx, R));

auto matchAll(R, String)(R input, String re)
if (isSomeString!R && isSomeString!String);

auto matchAll(R, String)(R input, String[] re...)
if (isSomeString!R && isSomeString!String);

Initiate a search for all non-overlapping matches to the pattern re in the given input. The result is a lazy range of matches generated as they are encountered in the input going left to right.

This function picks the most suitable regular expression engine depending on the pattern properties.

re parameter can be one of three types:

• Plain string(s), in which case it's compiled to bytecode before matching.
• Regex!char (wchar/dchar) that contains a pattern in the form of compiled bytecode.
• StaticRegex!char (wchar/dchar) that contains a pattern in the form of compiled native machine code.

Returns:

RegexMatch object that represents matcher state after the first match was found or an empty one if not present.

auto bmatch(R, RegEx)(R input, RegEx re)
if (isSomeString!R && isRegexFor!(RegEx, R));

auto bmatch(R, String)(R input, String re)
if (isSomeString!R && isSomeString!String);

Start matching of input to regex pattern re, using traditional backtracking matching scheme.

The use of this function is discouraged - use either of matchAll or matchFirst.

Delegating the kind of operation to "g" flag is soon to be phased out along with the ability to choose the exact matching scheme. The choice of matching scheme to use depends highly on the pattern kind and can done automatically on case by case basis.

Returns:

a RegexMatch object holding engine state after first match.

R replaceFirst(R, C, RegEx)(R input, RegEx re, const(C)[] format)
if (isSomeString!R && is(C : dchar) && isRegexFor!(RegEx, R));

Construct a new string from input by replacing the first match with a string generated from it according to the format specifier.

To replace all matches use replaceAll.

Parameters:

R input	string to search
RegEx re	compiled regular expression to use
const(C)[] format	format string to generate replacements from, see the format string.

Returns:

A string of the same type with the first match (if any) replaced. If no match is found returns the input string itself.

Examples:

writeln(replaceFirst("noon", regex("n"), "[$&]")); // "[n]oon"

R replaceFirst(alias fun, R, RegEx)(R input, RegEx re)
if (isSomeString!R && isRegexFor!(RegEx, R));

This is a general replacement tool that construct a new string by replacing matches of pattern re in the input. Unlike the other overload there is no format string instead captures are passed to to a user-defined functor fun that returns a new string to use as replacement.

This version replaces the first match in input, see replaceAll to replace the all of the matches.

Returns:

A new string of the same type as input with all matches replaced by return values of fun. If no matches found returns the input itself.

Examples:

import std.conv : to;
string list = "#21 out of 46";
string newList = replaceFirst!(cap => to!string(to!int(cap.hit)+1))
    (list, regex(`[0-9]+`));
writeln(newList); // "#22 out of 46"

@trusted void replaceFirstInto(Sink, R, C, RegEx)(ref Sink sink, R input, RegEx re, const(C)[] format)
if (isOutputRange!(Sink, dchar) && isSomeString!R && is(C : dchar) && isRegexFor!(RegEx, R));

@trusted void replaceFirstInto(alias fun, Sink, R, RegEx)(Sink sink, R input, RegEx re)
if (isOutputRange!(Sink, dchar) && isSomeString!R && isRegexFor!(RegEx, R));

A variation on replaceFirst that instead of allocating a new string on each call outputs the result piece-wise to the sink. In particular this enables efficient construction of a final output incrementally.

Like in replaceFirst family of functions there is an overload for the substitution guided by the format string and the one with the user defined callback.

Examples:

import std.array;
string m1 = "first message\n";
string m2 = "second message\n";
auto result = appender!string();
replaceFirstInto(result, m1, regex(`([a-z]+) message`), "$1");
//equivalent of the above with user-defined callback
replaceFirstInto!(cap=>cap[1])(result, m2, regex(`([a-z]+) message`));
writeln(result.data); // "first\nsecond\n"

@trusted R replaceAll(R, C, RegEx)(R input, RegEx re, const(C)[] format)
if (isSomeString!R && is(C : dchar) && isRegexFor!(RegEx, R));

Construct a new string from input by replacing all of the fragments that match a pattern re with a string generated from the match according to the format specifier.

To replace only the first match use replaceFirst.

Parameters:

R input	string to search
RegEx re	compiled regular expression to use
const(C)[] format	format string to generate replacements from, see the format string.

Returns:

A string of the same type as input with the all of the matches (if any) replaced. If no match is found returns the input string itself.

Examples:

// insert comma as thousands delimiter
auto re = regex(r"(?<=\d)(?=(\d\d\d)+\b)","g");
writeln(replaceAll("12000 + 42100 = 54100", re, ",")); // "12,000 + 42,100 = 54,100"

@trusted R replaceAll(alias fun, R, RegEx)(R input, RegEx re)
if (isSomeString!R && isRegexFor!(RegEx, R));

This is a general replacement tool that construct a new string by replacing matches of pattern re in the input. Unlike the other overload there is no format string instead captures are passed to to a user-defined functor fun that returns a new string to use as replacement.

This version replaces all of the matches found in input, see replaceFirst to replace the first match only.

Returns:

A new string of the same type as input with all matches replaced by return values of fun. If no matches found returns the input itself.

Parameters:

R input	string to search
RegEx re	compiled regular expression
fun	delegate to use

Examples:

string baz(Captures!(string) m)
{
    import std.string : toUpper;
    return toUpper(m.hit);
}
// Capitalize the letters 'a' and 'r':
auto s = replaceAll!(baz)("Strap a rocket engine on a chicken.",
        regex("[ar]"));
writeln(s); // "StRAp A Rocket engine on A chicken."

@trusted void replaceAllInto(Sink, R, C, RegEx)(Sink sink, R input, RegEx re, const(C)[] format)
if (isOutputRange!(Sink, dchar) && isSomeString!R && is(C : dchar) && isRegexFor!(RegEx, R));

@trusted void replaceAllInto(alias fun, Sink, R, RegEx)(Sink sink, R input, RegEx re)
if (isOutputRange!(Sink, dchar) && isSomeString!R && isRegexFor!(RegEx, R));

A variation on replaceAll that instead of allocating a new string on each call outputs the result piece-wise to the sink. In particular this enables efficient construction of a final output incrementally.

As with replaceAll there are 2 overloads - one with a format string, the other one with a user defined functor.

Examples:

// insert comma as thousands delimiter in fifty randomly produced big numbers
import std.array, std.conv, std.random, std.range;
static re = regex(`(?<=\d)(?=(\d\d\d)+\b)`, "g");
auto sink = appender!(char [])();
enum ulong min = 10UL ^^ 10, max = 10UL ^^ 19;
foreach (i; 0 .. 50)
{
    sink.clear();
    replaceAllInto(sink, text(uniform(min, max)), re, ",");
    foreach (pos; iota(sink.data.length - 4, 0, -4))
        writeln(sink.data[pos]); // ','
}

R replace(alias scheme = match, R, C, RegEx)(R input, RegEx re, const(C)[] format)
if (isSomeString!R && isRegexFor!(RegEx, R));

R replace(alias fun, R, RegEx)(R input, RegEx re)
if (isSomeString!R && isRegexFor!(RegEx, R));

Old API for replacement, operation depends on flags of pattern re. With "g" flag it performs the equivalent of replaceAll otherwise it works the same as replaceFirst.

The use of this function is discouraged, please use replaceAll or replaceFirst explicitly.

struct Splitter(Flag!"keepSeparators" keepSeparators = No.keepSeparators, Range, alias RegEx = Regex) if (isSomeString!Range && isRegexFor!(RegEx, Range));

Splitter!(keepSeparators, Range, RegEx) splitter(Flag!"keepSeparators" keepSeparators = No.keepSeparators, Range, RegEx)(Range r, RegEx pat)
if (is(BasicElementOf!Range : dchar) && isRegexFor!(RegEx, Range));

Splits a string r using a regular expression pat as a separator.

Parameters:

keepSeparators	flag to specify if the matches should be in the resulting range
Range r	the string to split
RegEx pat	the pattern to split on

Returns:

A lazy range of strings

Examples:

import std.algorithm.comparison : equal;
auto s1 = ", abc, de,  fg, hi, ";
assert(equal(splitter(s1, regex(", *")),
    ["", "abc", "de", "fg", "hi", ""]));

Examples:

Split on a pattern, but keep the matches in the resulting range

import std.algorithm.comparison : equal;
import std.typecons : Yes;

auto pattern = regex(`([\.,])`);

assert("2003.04.05"
    .splitter!(Yes.keepSeparators)(pattern)
    .equal(["2003", ".", "04", ".", "05"]));

assert(",1,2,3"
    .splitter!(Yes.keepSeparators)(pattern)
    .equal([",", "1", ",", "2", ",", "3"]));

@property Range front();

@property bool empty();

void popFront();

@property auto save();

Forward range primitives.

@trusted String[] split(String, RegEx)(String input, RegEx rx)
if (isSomeString!String && isRegexFor!(RegEx, String));

An eager version of splitter that creates an array with splitted slices of input.

alias RegexException = std.regex.internal.ir.RegexException;

Exception object thrown in case of errors during regex compilation.

auto escaper(Range)(Range r);

A range that lazily produces a string output escaped to be used inside of a regular expression.

Examples:

import std.algorithm.comparison;
import std.regex;
string s = `This is {unfriendly} to *regex*`;
assert(s.escaper.equal(`This is \{unfriendly\} to \*regex\*`));