Match regular expressions on arbitrary bytes.
This module provides a nearly identical API to the one found in the top-level of this crate. There are two important differences:
- Matching is done on
Vec<u8>is used where
Stringwould have been used.
- Regular expressions are compiled with Unicode support disabled by
default. This means that while Unicode regular expressions can only match valid
UTF-8, regular expressions in this module can match arbitrary bytes. Unicode
support can be selectively enabled via the
uflag in regular expressions provided by this sub-module.
This shows how to find all null-terminated strings in a slice of bytes:
let re = Regex::new(r"(?P<cstr>[^\x00]+)\x00").unwrap(); let text = b"foo\x00bar\x00baz\x00"; // Extract all of the strings without the null terminator from each match. // The unwrap is OK here since a match requires the `cstr` capture to match. let cstrs: Vec<&[u8]> = re.captures_iter(text) .map(|c| c.name("cstr").unwrap()) .collect(); assert_eq!(vec![&b"foo"[..], &b"bar"[..], &b"baz"[..]], cstrs);
This shows how to match an arbitrary byte pattern followed by a UTF-8 encoded string (e.g., to extract a title from a Matroska file):
let re = Regex::new(r"\x7b\xa9(?:[\x80-\xfe]|[\x40-\xff].)(?u:(.*))").unwrap(); let text = b"\x12\xd0\x3b\x5f\x7b\xa9\x85\xe2\x98\x83\x80\x98\x54\x76\x68\x65"; let caps = re.captures(text).unwrap(); // Notice that despite the `.*` at the end, it will only match valid UTF-8 // because Unicode mode was enabled with the `u` flag. Without the `u` flag, // the `.*` would match the rest of the bytes. assert_eq!((7, 10), caps.pos(1).unwrap()); // If there was a match, Unicode mode guarantees that `title` is valid UTF-8. let title = str::from_utf8(caps.at(1).unwrap()).unwrap(); assert_eq!("☃", title);
In general, if the Unicode flag is enabled in a capture group and that capture is part of the overall match, then the capture is guaranteed to be valid UTF-8.
The supported syntax is pretty much the same as the syntax for Unicode regular expressions with a few changes that make sense for matching arbitrary bytes:
uflag is disabled by default, but can be selectively enabled. (The opposite is true for the main
Regextype.) Disabling the
uflag is said to invoke "ASCII compatible" mode.
- In ASCII compatible mode, neither Unicode codepoints nor Unicode character classes are allowed.
- In ASCII compatible mode, Perl character classes (
\s) revert to their typical ASCII definition.
- In ASCII compatible mode, word boundaries use the ASCII compatible
\wto determine whether a byte is a word byte or not.
- Hexadecimal notation can be used to specify arbitrary bytes instead of
Unicode codepoints. For example, in ASCII compatible mode,
\xFFmatches the literal byte
\xFF, while in Unicode mode,
\xFFis a Unicode codepoint that matches its UTF-8 encoding of
\xC3\xBF. Similarly for octal notation.
.matches any byte except for
\ninstead of any codepoint. When the
sflag is enabled,
.matches any byte.
In general, one should expect performance on
&[u8] to be roughly similar to
An iterator over the names of all possible captures.
Captures represents a group of captured byte strings for a single match.
An iterator that yields all non-overlapping capture groups matching a particular regular expression.
An iterator over all non-overlapping matches for a particular string.
NoExpand indicates literal byte string replacement.
A compiled regular expression for matching arbitrary bytes.
A configurable builder for a regular expression.
Match multiple (possibly overlapping) regular expressions in a single scan.
A set of matches returned by a regex set.
An owned iterator over the set of matches from a regex set.
A borrowed iterator over the set of matches from a regex set.
Yields all substrings delimited by a regular expression match.
Yields at most
An iterator over capture groups for a particular match of a regular expression.
An Iterator over named capture groups as a tuple with the group name and the value.
An iterator over capture group positions for a particular match of a regular expression.
Replacer describes types that can be used to replace matches in a byte string.