std.regexp
Regular expressions are a powerful method of string pattern matching. The regular expression language used is the same as that commonly used, however, some of the very advanced forms may behave slightly differently.std.regexp is designed to work only with valid UTF strings as input. To validate untrusted input, use std.utf.validate().
In the following guide, pattern[] refers to a regular expression. The attributes[] refers to a string controlling the interpretation of the regular expression. It consists of a sequence of one or more of the following characters:
Attribute | Action |
---|---|
g | global; repeat over the whole input string |
i | case insensitive |
m | treat as multiple lines separated by newlines |
The format[] string has the formatting characters:
Format | Replaced With |
---|---|
$$ | $ |
$& | The matched substring. |
$` | The portion of string that precedes the matched substring. |
$' | The portion of string that follows the matched substring. |
$n | The nth capture, where n is a single digit 1-9 and n is not followed by a decimal digit. |
$nn | The nnth capture, where nn is a two-digit decimal number 01-99. If nnth capture is undefined or more than the number of parenthesized subexpressions, use the empty string instead. |
Any other $ are left as is.
References:
Wikipedia
- string email;
- Regular expression to extract an email address.
References:
How to Find or Validate an Email Address
RFC 2822 Internet Message Format
- string url;
- Regular expression to extract a url
- class RegExpException: object.Exception;
- One of these gets thrown on compilation errors
- string sub(string s, string pattern, string format, string attributes = null);
- Search string for matches with regular expression
pattern with attributes.
Replace each match with string generated from format.
Params:
invariant(char)[] s String to search. invariant(char)[] pattern Regular expression pattern. invariant(char)[] format Replacement string format. invariant(char)[] attributes Regular expression attributes.
Returns:
the resulting string
Example:
Replace the letters 'a' with the letters 'ZZ'.s = "Strap a rocket engine on a chicken." sub(s, "a", "ZZ") // result: StrZZp a rocket engine on a chicken. sub(s, "a", "ZZ", "g") // result: StrZZp ZZ rocket engine on ZZ chicken.
The replacement format can reference the matches using the $&, $$, $', $`, .. 9 notation:sub(s, "[ar]", "[$&]", "g") // result: St[r][a]p [a] [r]ocket engine on [a] chi
- string sub(string s, string pattern, invariant(char)[] delegate(RegExp) dg, string attributes = null);
- Search string for matches with regular expression
pattern with attributes.
Pass each match to delegate dg.
Replace each match with the return value from dg.
Params:
invariant(char)[] s String to search. invariant(char)[] pattern Regular expression pattern. invariant(char)[] delegate(RegExp) dg Delegate invariant(char)[] attributes Regular expression attributes.
Returns:
the resulting string.
Example:
Capitalize the letters 'a' and 'r':s = "Strap a rocket engine on a chicken."; sub(s, "[ar]", delegate char[] (RegExp m) { return toupper(m[0]); }, "g"); // result: StRAp A Rocket engine on A chicken.
- int find(string s, RegExp pattern);
- Search s[] for first match with pattern.
Params:
invariant(char)[] s String to search. RegExp pattern Regular expression pattern.
Returns:
index into s[] of match if found, -1 if no match.
Example:
auto s = "abcabcabab"; find(s, RegExp("b")); // match, returns 1 find(s, RegExp("f")); // no match, returns -1
- int find(string s, string pattern, string attributes = null);
- Returns:
Same as find(s, RegExp(pattern, attributes)).
WARNING:
This function is scheduled for deprecation due to unnecessary ambiguity with the homonym function in std.string. Instead of std.regexp.find(s, p, a), you may want to use find(s, RegExp(p, a)).
- int rfind(string s, RegExp pattern);
- Search s[] for last match with pattern.
Params:
invariant(char)[] s String to search. RegExp pattern Regular expression pattern.
Returns:
index into s[] of match if found, -1 if no match.
Example:
auto s = "abcabcabab"; rfind(s, RegExp("b")); // match, returns 9 rfind(s, RegExp("f")); // no match, returns -1
- int rfind(string s, string pattern, string attributes = null);
- Returns:
Same as rfind(s, RegExp(pattern, attributes)).
WARNING:
This function is scheduled for deprecation due to unnecessary ambiguity with the homonym function in std.string. Instead of std.regexp.rfind(s, p, a), you may want to use rfind(s, RegExp(p, a)).
- invariant(char)[][] split(string s, RegExp pattern);
- Split s[] into an array of strings, using the regular
expression pattern as the separator.
Params:
invariant(char)[] s String to search. RegExp pattern Regular expression pattern.
Returns:
array of slices into s[]
Example:
foreach (s; split("abcabcabab", RegExp("C.", "i"))) { writefln("s = '%s'", s); } // Prints: // s = 'ab' // s = 'b' // s = 'bab'
- invariant(char)[][] split(string s, string pattern, string attributes = null);
- Returns:
Same as split(s, RegExp(pattern, attributes)).
WARNING:
This function is scheduled for deprecation due to unnecessary ambiguity with the homonym function in std.string. Instead of std.regexp.split(s, p, a), you may want to use split(s, RegExp(p, a)).
- RegExp search(string s, string pattern, string attributes = null);
- Search s[] for first match with pattern[] with attributes[].
Params:
invariant(char)[] s String to search. invariant(char)[] pattern Regular expression pattern. invariant(char)[] attributes Regular expression attributes.
Returns:
corresponding RegExp if found, null if not.
Example:
import std.stdio; import std.regexp; void main() { if (auto m = std.regexp.search("abcdef", "c")) { writefln("%s[%s]%s", m.pre, m[0], m.post); } } // Prints: // ab[c]def
- class RegExp;
- RegExp is a class to handle regular expressions.
It is the core foundation for adding powerful string pattern matching capabilities to programs like grep, text editors, awk, sed, etc.
- this(string pattern, string attributes = null);
- Construct a RegExp object. Compile pattern
with attributes into
an internal form for fast execution.
Params:
invariant(char)[] pattern regular expression invariant(char)[] attributes attributes
Throws:
RegExpException if there are any compilation errors.
Example:
Declare two variables and assign to them a RegExp object:auto r = new RegExp("pattern"); auto s = new RegExp(r"p[1-5]\s*");
- static RegExp opCall(string pattern, string attributes = null);
- Generate instance of RegExp.
Params:
invariant(char)[] pattern regular expression invariant(char)[] attributes attributes
Throws:
RegExpException if there are any compilation errors.
Example:
Declare two variables and assign to them a RegExp object:auto r = RegExp("pattern"); auto s = RegExp(r"p[1-5]\s*");
- RegExp search(string string);
int opApply(int delegate(ref RegExp) dg); - Set up for start of foreach loop.
Returns:
search() returns instance of RegExp set up to search string[].
Example:
import std.stdio; import std.regexp; void main() { foreach(m; RegExp("ab").search("abcabcabab")) { writefln("%s[%s]%s", m.pre, m[0], m.post); } } // Prints: // [ab]cabcabab // abc[ab]cabab // abcabc[ab]ab // abcabcab[ab]
- string opIndex(size_t n);
- Retrieve match n.
n==0 means the matched substring, n>0 means the n'th parenthesized subexpression. if n is larger than the number of parenthesized subexpressions, null is returned.
- string match(size_t n);
- Same as opIndex(n).
WARNING:
Scheduled for deprecation due to confusion with overloaded match(string). Instead of regex.match(n) you may want to use regex[n].
- string pre();
- Return the slice of the input that precedes the matched substring.
- string post();
- Return the slice of the input that follows the matched substring.
- invariant(char)[][] split(string s);
- Split s[] into an array of strings, using the regular
expression as the separator.
Returns:
array of slices into s[]
- int find(string string);
- Search string[] for match with regular expression.
Returns:
index of match if successful, -1 if not found
- invariant(char)[][] match(string s);
- Search s[] for match.
Returns:
If global attribute, return same value as exec(s). If not global attribute, return array of all matches.
- string replace(string s, string format);
- Find regular expression matches in s[]. Replace those matches
with a new string composed of format[] merged with the result of the
matches.
If global, replace all matches. Otherwise, replace first match.
Returns:
the new string
- invariant(char)[][] exec(string string);
- Search string[] for match.
Returns:
array of slices into string[] representing matches
- invariant(char)[][] exec();
- Pick up where last exec(string) or exec() left off,
searching string[] for next match.
Returns:
array of slices into string[] representing matches
- int test(string s);
- Search s[] for match.
Returns:
0 for no match, !=0 for match
Example:
import std.stdio; import std.regexp; import std.string; int grep(int delegate(char[]) pred, char[][] list) { int count; foreach (s; list) { if (pred(s)) ++count; } return count; } void main() { auto x = grep(&RegExp("[Ff]oo").test, std.string.split("mary had a foo lamb")); writefln(x); }
which prints: 1
- int test();
- Pick up where last test(string) or test() left off, and search again.
Returns:
0 for no match, !=0 for match
- int test(string s, int startindex);
- Test s[] starting at startindex against regular expression.
Returns:
0 for no match, !=0 for match
- alias opEquals;
- Returns whether string s matches this.
- string replace(string format);
- After a match is found with test(), this function
will take the match results and, using the format
string, generate and return a new string.
- string replaceOld(string format);
- Like replace(char[] format), but uses old style formatting:
Format Description & replace with the match \n replace with the nth parenthesized match, n is 1..9 \c replace with char c.