blob: d3dc58d66f7b76d509a7b3a0a65230951196893f [file] [log] [blame]
Chih-Hung Hsiehe42c5052020-04-16 10:44:21 -07001/*!
2This crate provides a library for parsing, compiling, and executing regular
3expressions. Its syntax is similar to Perl-style regular expressions, but lacks
4a few features like look around and backreferences. In exchange, all searches
5execute in linear time with respect to the size of the regular expression and
6search text.
7
8This crate's documentation provides some simple examples, describes
9[Unicode support](#unicode) and exhaustively lists the
10[supported syntax](#syntax).
11
12For more specific details on the API for regular expressions, please see the
13documentation for the [`Regex`](struct.Regex.html) type.
14
15# Usage
16
17This crate is [on crates.io](https://crates.io/crates/regex) and can be
18used by adding `regex` to your dependencies in your project's `Cargo.toml`.
19
20```toml
21[dependencies]
22regex = "1"
23```
24
25If you're using Rust 2015, then you'll also need to add it to your crate root:
26
27```rust
28extern crate regex;
29```
30
31# Example: find a date
32
33General use of regular expressions in this package involves compiling an
34expression and then using it to search, split or replace text. For example,
35to confirm that some text resembles a date:
36
37```rust
38use regex::Regex;
39let re = Regex::new(r"^\d{4}-\d{2}-\d{2}$").unwrap();
40assert!(re.is_match("2014-01-01"));
41```
42
43Notice the use of the `^` and `$` anchors. In this crate, every expression
44is executed with an implicit `.*?` at the beginning and end, which allows
45it to match anywhere in the text. Anchors can be used to ensure that the
46full text matches an expression.
47
48This example also demonstrates the utility of
49[raw strings](https://doc.rust-lang.org/stable/reference/tokens.html#raw-string-literals)
50in Rust, which
51are just like regular strings except they are prefixed with an `r` and do
52not process any escape sequences. For example, `"\\d"` is the same
53expression as `r"\d"`.
54
55# Example: Avoid compiling the same regex in a loop
56
57It is an anti-pattern to compile the same regular expression in a loop
58since compilation is typically expensive. (It takes anywhere from a few
59microseconds to a few **milliseconds** depending on the size of the
60regex.) Not only is compilation itself expensive, but this also prevents
61optimizations that reuse allocations internally to the matching engines.
62
63In Rust, it can sometimes be a pain to pass regular expressions around if
64they're used from inside a helper function. Instead, we recommend using the
65[`lazy_static`](https://crates.io/crates/lazy_static) crate to ensure that
66regular expressions are compiled exactly once.
67
68For example:
69
70```rust
71#[macro_use] extern crate lazy_static;
72extern crate regex;
73
74use regex::Regex;
75
76fn some_helper_function(text: &str) -> bool {
77 lazy_static! {
78 static ref RE: Regex = Regex::new("...").unwrap();
79 }
80 RE.is_match(text)
81}
82
83fn main() {}
84```
85
86Specifically, in this example, the regex will be compiled when it is used for
87the first time. On subsequent uses, it will reuse the previous compilation.
88
89# Example: iterating over capture groups
90
91This crate provides convenient iterators for matching an expression
92repeatedly against a search string to find successive non-overlapping
93matches. For example, to find all dates in a string and be able to access
94them by their component pieces:
95
96```rust
97# extern crate regex; use regex::Regex;
98# fn main() {
99let re = Regex::new(r"(\d{4})-(\d{2})-(\d{2})").unwrap();
100let text = "2012-03-14, 2013-01-01 and 2014-07-05";
101for cap in re.captures_iter(text) {
102 println!("Month: {} Day: {} Year: {}", &cap[2], &cap[3], &cap[1]);
103}
104// Output:
105// Month: 03 Day: 14 Year: 2012
106// Month: 01 Day: 01 Year: 2013
107// Month: 07 Day: 05 Year: 2014
108# }
109```
110
111Notice that the year is in the capture group indexed at `1`. This is
112because the *entire match* is stored in the capture group at index `0`.
113
114# Example: replacement with named capture groups
115
116Building on the previous example, perhaps we'd like to rearrange the date
117formats. This can be done with text replacement. But to make the code
118clearer, we can *name* our capture groups and use those names as variables
119in our replacement text:
120
121```rust
122# extern crate regex; use regex::Regex;
123# fn main() {
124let re = Regex::new(r"(?P<y>\d{4})-(?P<m>\d{2})-(?P<d>\d{2})").unwrap();
125let before = "2012-03-14, 2013-01-01 and 2014-07-05";
126let after = re.replace_all(before, "$m/$d/$y");
127assert_eq!(after, "03/14/2012, 01/01/2013 and 07/05/2014");
128# }
129```
130
131The `replace` methods are actually polymorphic in the replacement, which
132provides more flexibility than is seen here. (See the documentation for
133`Regex::replace` for more details.)
134
135Note that if your regex gets complicated, you can use the `x` flag to
136enable insignificant whitespace mode, which also lets you write comments:
137
138```rust
139# extern crate regex; use regex::Regex;
140# fn main() {
141let re = Regex::new(r"(?x)
142 (?P<y>\d{4}) # the year
143 -
144 (?P<m>\d{2}) # the month
145 -
146 (?P<d>\d{2}) # the day
147").unwrap();
148let before = "2012-03-14, 2013-01-01 and 2014-07-05";
149let after = re.replace_all(before, "$m/$d/$y");
150assert_eq!(after, "03/14/2012, 01/01/2013 and 07/05/2014");
151# }
152```
153
154If you wish to match against whitespace in this mode, you can still use `\s`,
Haibo Huang49cbe5f2020-05-28 20:14:24 -0700155`\n`, `\t`, etc. For escaping a single space character, you can escape it
156directly with `\ `, use its hex character code `\x20` or temporarily disable
157the `x` flag, e.g., `(?-x: )`.
Chih-Hung Hsiehe42c5052020-04-16 10:44:21 -0700158
159# Example: match multiple regular expressions simultaneously
160
161This demonstrates how to use a `RegexSet` to match multiple (possibly
162overlapping) regular expressions in a single scan of the search text:
163
164```rust
165use regex::RegexSet;
166
167let set = RegexSet::new(&[
168 r"\w+",
169 r"\d+",
170 r"\pL+",
171 r"foo",
172 r"bar",
173 r"barfoo",
174 r"foobar",
175]).unwrap();
176
177// Iterate over and collect all of the matches.
178let matches: Vec<_> = set.matches("foobar").into_iter().collect();
179assert_eq!(matches, vec![0, 2, 3, 4, 6]);
180
181// You can also test whether a particular regex matched:
182let matches = set.matches("foobar");
183assert!(!matches.matched(5));
184assert!(matches.matched(6));
185```
186
187# Pay for what you use
188
189With respect to searching text with a regular expression, there are three
190questions that can be asked:
191
1921. Does the text match this expression?
1932. If so, where does it match?
1943. Where did the capturing groups match?
195
196Generally speaking, this crate could provide a function to answer only #3,
197which would subsume #1 and #2 automatically. However, it can be significantly
198more expensive to compute the location of capturing group matches, so it's best
199not to do it if you don't need to.
200
201Therefore, only use what you need. For example, don't use `find` if you
202only need to test if an expression matches a string. (Use `is_match`
203instead.)
204
205# Unicode
206
207This implementation executes regular expressions **only** on valid UTF-8
208while exposing match locations as byte indices into the search string. (To
209relax this restriction, use the [`bytes`](bytes/index.html) sub-module.)
210
211Only simple case folding is supported. Namely, when matching
212case-insensitively, the characters are first mapped using the "simple" case
213folding rules defined by Unicode.
214
215Regular expressions themselves are **only** interpreted as a sequence of
216Unicode scalar values. This means you can use Unicode characters directly
217in your expression:
218
219```rust
220# extern crate regex; use regex::Regex;
221# fn main() {
222let re = Regex::new(r"(?i)Δ+").unwrap();
223let mat = re.find("ΔδΔ").unwrap();
224assert_eq!((mat.start(), mat.end()), (0, 6));
225# }
226```
227
228Most features of the regular expressions in this crate are Unicode aware. Here
229are some examples:
230
231* `.` will match any valid UTF-8 encoded Unicode scalar value except for `\n`.
232 (To also match `\n`, enable the `s` flag, e.g., `(?s:.)`.)
233* `\w`, `\d` and `\s` are Unicode aware. For example, `\s` will match all forms
234 of whitespace categorized by Unicode.
235* `\b` matches a Unicode word boundary.
236* Negated character classes like `[^a]` match all Unicode scalar values except
237 for `a`.
238* `^` and `$` are **not** Unicode aware in multi-line mode. Namely, they only
239 recognize `\n` and not any of the other forms of line terminators defined
240 by Unicode.
241
242Unicode general categories, scripts, script extensions, ages and a smattering
243of boolean properties are available as character classes. For example, you can
244match a sequence of numerals, Greek or Cherokee letters:
245
246```rust
247# extern crate regex; use regex::Regex;
248# fn main() {
249let re = Regex::new(r"[\pN\p{Greek}\p{Cherokee}]+").unwrap();
250let mat = re.find("abcΔᎠβⅠᏴγδⅡxyz").unwrap();
251assert_eq!((mat.start(), mat.end()), (3, 23));
252# }
253```
254
255For a more detailed breakdown of Unicode support with respect to
256[UTS#18](http://unicode.org/reports/tr18/),
257please see the
258[UNICODE](https://github.com/rust-lang/regex/blob/master/UNICODE.md)
259document in the root of the regex repository.
260
261# Opt out of Unicode support
262
263The `bytes` sub-module provides a `Regex` type that can be used to match
264on `&[u8]`. By default, text is interpreted as UTF-8 just like it is with
265the main `Regex` type. However, this behavior can be disabled by turning
266off the `u` flag, even if doing so could result in matching invalid UTF-8.
267For example, when the `u` flag is disabled, `.` will match any byte instead
268of any Unicode scalar value.
269
270Disabling the `u` flag is also possible with the standard `&str`-based `Regex`
271type, but it is only allowed where the UTF-8 invariant is maintained. For
272example, `(?-u:\w)` is an ASCII-only `\w` character class and is legal in an
273`&str`-based `Regex`, but `(?-u:\xFF)` will attempt to match the raw byte
274`\xFF`, which is invalid UTF-8 and therefore is illegal in `&str`-based
275regexes.
276
277Finally, since Unicode support requires bundling large Unicode data
278tables, this crate exposes knobs to disable the compilation of those
279data tables, which can be useful for shrinking binary size and reducing
280compilation times. For details on how to do that, see the section on [crate
281features](#crate-features).
282
283# Syntax
284
285The syntax supported in this crate is documented below.
286
287Note that the regular expression parser and abstract syntax are exposed in
288a separate crate, [`regex-syntax`](https://docs.rs/regex-syntax).
289
290## Matching one character
291
292<pre class="rust">
293. any character except new line (includes new line with s flag)
294\d digit (\p{Nd})
295\D not digit
296\pN One-letter name Unicode character class
297\p{Greek} Unicode character class (general category or script)
298\PN Negated one-letter name Unicode character class
299\P{Greek} negated Unicode character class (general category or script)
300</pre>
301
302### Character classes
303
304<pre class="rust">
305[xyz] A character class matching either x, y or z (union).
306[^xyz] A character class matching any character except x, y and z.
307[a-z] A character class matching any character in range a-z.
308[[:alpha:]] ASCII character class ([A-Za-z])
309[[:^alpha:]] Negated ASCII character class ([^A-Za-z])
310[x[^xyz]] Nested/grouping character class (matching any character except y and z)
311[a-y&&xyz] Intersection (matching x or y)
312[0-9&&[^4]] Subtraction using intersection and negation (matching 0-9 except 4)
313[0-9--4] Direct subtraction (matching 0-9 except 4)
314[a-g~~b-h] Symmetric difference (matching `a` and `h` only)
315[\[\]] Escaping in character classes (matching [ or ])
316</pre>
317
318Any named character class may appear inside a bracketed `[...]` character
319class. For example, `[\p{Greek}[:digit:]]` matches any Greek or ASCII
320digit. `[\p{Greek}&&\pL]` matches Greek letters.
321
322Precedence in character classes, from most binding to least:
323
3241. Ranges: `a-cd` == `[a-c]d`
3252. Union: `ab&&bc` == `[ab]&&[bc]`
3263. Intersection: `^a-z&&b` == `^[a-z&&b]`
3274. Negation
328
329## Composites
330
331<pre class="rust">
332xy concatenation (x followed by y)
333x|y alternation (x or y, prefer x)
334</pre>
335
336## Repetitions
337
338<pre class="rust">
339x* zero or more of x (greedy)
340x+ one or more of x (greedy)
341x? zero or one of x (greedy)
342x*? zero or more of x (ungreedy/lazy)
343x+? one or more of x (ungreedy/lazy)
344x?? zero or one of x (ungreedy/lazy)
345x{n,m} at least n x and at most m x (greedy)
346x{n,} at least n x (greedy)
347x{n} exactly n x
348x{n,m}? at least n x and at most m x (ungreedy/lazy)
349x{n,}? at least n x (ungreedy/lazy)
350x{n}? exactly n x
351</pre>
352
353## Empty matches
354
355<pre class="rust">
356^ the beginning of text (or start-of-line with multi-line mode)
357$ the end of text (or end-of-line with multi-line mode)
358\A only the beginning of text (even with multi-line mode enabled)
359\z only the end of text (even with multi-line mode enabled)
360\b a Unicode word boundary (\w on one side and \W, \A, or \z on other)
361\B not a Unicode word boundary
362</pre>
363
364## Grouping and flags
365
366<pre class="rust">
367(exp) numbered capture group (indexed by opening parenthesis)
Chih-Hung Hsieh849e4452020-10-26 13:16:47 -0700368(?P&lt;name&gt;exp) named (also numbered) capture group (allowed chars: [_0-9a-zA-Z.\[\]])
Chih-Hung Hsiehe42c5052020-04-16 10:44:21 -0700369(?:exp) non-capturing group
370(?flags) set flags within current group
371(?flags:exp) set flags for exp (non-capturing)
372</pre>
373
374Flags are each a single character. For example, `(?x)` sets the flag `x`
375and `(?-x)` clears the flag `x`. Multiple flags can be set or cleared at
376the same time: `(?xy)` sets both the `x` and `y` flags and `(?x-y)` sets
377the `x` flag and clears the `y` flag.
378
379All flags are by default disabled unless stated otherwise. They are:
380
381<pre class="rust">
382i case-insensitive: letters match both upper and lower case
383m multi-line mode: ^ and $ match begin/end of line
384s allow . to match \n
385U swap the meaning of x* and x*?
386u Unicode support (enabled by default)
387x ignore whitespace and allow line comments (starting with `#`)
388</pre>
389
390Flags can be toggled within a pattern. Here's an example that matches
391case-insensitively for the first part but case-sensitively for the second part:
392
393```rust
394# extern crate regex; use regex::Regex;
395# fn main() {
396let re = Regex::new(r"(?i)a+(?-i)b+").unwrap();
397let cap = re.captures("AaAaAbbBBBb").unwrap();
398assert_eq!(&cap[0], "AaAaAbb");
399# }
400```
401
402Notice that the `a+` matches either `a` or `A`, but the `b+` only matches
403`b`.
404
405Multi-line mode means `^` and `$` no longer match just at the beginning/end of
406the input, but at the beginning/end of lines:
407
408```
409# use regex::Regex;
410let re = Regex::new(r"(?m)^line \d+").unwrap();
411let m = re.find("line one\nline 2\n").unwrap();
412assert_eq!(m.as_str(), "line 2");
413```
414
415Note that `^` matches after new lines, even at the end of input:
416
417```
418# use regex::Regex;
419let re = Regex::new(r"(?m)^").unwrap();
420let m = re.find_iter("test\n").last().unwrap();
421assert_eq!((m.start(), m.end()), (5, 5));
422```
423
424Here is an example that uses an ASCII word boundary instead of a Unicode
425word boundary:
426
427```rust
428# extern crate regex; use regex::Regex;
429# fn main() {
430let re = Regex::new(r"(?-u:\b).+(?-u:\b)").unwrap();
431let cap = re.captures("$$abc$$").unwrap();
432assert_eq!(&cap[0], "abc");
433# }
434```
435
436## Escape sequences
437
438<pre class="rust">
439\* literal *, works for any punctuation character: \.+*?()|[]{}^$
440\a bell (\x07)
441\f form feed (\x0C)
442\t horizontal tab
443\n new line
444\r carriage return
445\v vertical tab (\x0B)
446\123 octal character code (up to three digits) (when enabled)
447\x7F hex character code (exactly two digits)
448\x{10FFFF} any hex character code corresponding to a Unicode code point
449\u007F hex character code (exactly four digits)
450\u{7F} any hex character code corresponding to a Unicode code point
451\U0000007F hex character code (exactly eight digits)
452\U{7F} any hex character code corresponding to a Unicode code point
453</pre>
454
455## Perl character classes (Unicode friendly)
456
457These classes are based on the definitions provided in
458[UTS#18](http://www.unicode.org/reports/tr18/#Compatibility_Properties):
459
460<pre class="rust">
461\d digit (\p{Nd})
462\D not digit
463\s whitespace (\p{White_Space})
464\S not whitespace
465\w word character (\p{Alphabetic} + \p{M} + \d + \p{Pc} + \p{Join_Control})
466\W not word character
467</pre>
468
469## ASCII character classes
470
471<pre class="rust">
472[[:alnum:]] alphanumeric ([0-9A-Za-z])
473[[:alpha:]] alphabetic ([A-Za-z])
474[[:ascii:]] ASCII ([\x00-\x7F])
475[[:blank:]] blank ([\t ])
476[[:cntrl:]] control ([\x00-\x1F\x7F])
477[[:digit:]] digits ([0-9])
478[[:graph:]] graphical ([!-~])
479[[:lower:]] lower case ([a-z])
480[[:print:]] printable ([ -~])
481[[:punct:]] punctuation ([!-/:-@\[-`{-~])
482[[:space:]] whitespace ([\t\n\v\f\r ])
483[[:upper:]] upper case ([A-Z])
484[[:word:]] word characters ([0-9A-Za-z_])
485[[:xdigit:]] hex digit ([0-9A-Fa-f])
486</pre>
487
488# Crate features
489
490By default, this crate tries pretty hard to make regex matching both as fast
491as possible and as correct as it can be, within reason. This means that there
492is a lot of code dedicated to performance, the handling of Unicode data and the
493Unicode data itself. Overall, this leads to more dependencies, larger binaries
494and longer compile times. This trade off may not be appropriate in all cases,
495and indeed, even when all Unicode and performance features are disabled, one
496is still left with a perfectly serviceable regex engine that will work well
497in many cases.
498
499This crate exposes a number of features for controlling that trade off. Some
500of these features are strictly performance oriented, such that disabling them
501won't result in a loss of functionality, but may result in worse performance.
502Other features, such as the ones controlling the presence or absence of Unicode
503data, can result in a loss of functionality. For example, if one disables the
504`unicode-case` feature (described below), then compiling the regex `(?i)a`
505will fail since Unicode case insensitivity is enabled by default. Instead,
506callers must use `(?i-u)a` instead to disable Unicode case folding. Stated
507differently, enabling or disabling any of the features below can only add or
508subtract from the total set of valid regular expressions. Enabling or disabling
509a feature will never modify the match semantics of a regular expression.
510
511All features below are enabled by default.
512
513### Ecosystem features
514
515* **std** -
516 When enabled, this will cause `regex` to use the standard library. Currently,
517 disabling this feature will always result in a compilation error. It is
518 intended to add `alloc`-only support to regex in the future.
519
520### Performance features
521
522* **perf** -
523 Enables all performance related features. This feature is enabled by default
524 and will always cover all features that improve performance, even if more
525 are added in the future.
526* **perf-cache** -
527 Enables the use of very fast thread safe caching for internal match state.
528 When this is disabled, caching is still used, but with a slower and simpler
529 implementation. Disabling this drops the `thread_local` and `lazy_static`
530 dependencies.
531* **perf-dfa** -
532 Enables the use of a lazy DFA for matching. The lazy DFA is used to compile
533 portions of a regex to a very fast DFA on an as-needed basis. This can
534 result in substantial speedups, usually by an order of magnitude on large
535 haystacks. The lazy DFA does not bring in any new dependencies, but it can
536 make compile times longer.
537* **perf-inline** -
538 Enables the use of aggressive inlining inside match routines. This reduces
539 the overhead of each match. The aggressive inlining, however, increases
540 compile times and binary size.
541* **perf-literal** -
542 Enables the use of literal optimizations for speeding up matches. In some
543 cases, literal optimizations can result in speedups of _several_ orders of
544 magnitude. Disabling this drops the `aho-corasick` and `memchr` dependencies.
545
546### Unicode features
547
548* **unicode** -
549 Enables all Unicode features. This feature is enabled by default, and will
550 always cover all Unicode features, even if more are added in the future.
551* **unicode-age** -
552 Provide the data for the
553 [Unicode `Age` property](https://www.unicode.org/reports/tr44/tr44-24.html#Character_Age).
554 This makes it possible to use classes like `\p{Age:6.0}` to refer to all
555 codepoints first introduced in Unicode 6.0
556* **unicode-bool** -
557 Provide the data for numerous Unicode boolean properties. The full list
558 is not included here, but contains properties like `Alphabetic`, `Emoji`,
559 `Lowercase`, `Math`, `Uppercase` and `White_Space`.
560* **unicode-case** -
561 Provide the data for case insensitive matching using
562 [Unicode's "simple loose matches" specification](https://www.unicode.org/reports/tr18/#Simple_Loose_Matches).
563* **unicode-gencat** -
564 Provide the data for
Chih-Hung Hsieh849e4452020-10-26 13:16:47 -0700565 [Unicode general categories](https://www.unicode.org/reports/tr44/tr44-24.html#General_Category_Values).
Chih-Hung Hsiehe42c5052020-04-16 10:44:21 -0700566 This includes, but is not limited to, `Decimal_Number`, `Letter`,
567 `Math_Symbol`, `Number` and `Punctuation`.
568* **unicode-perl** -
569 Provide the data for supporting the Unicode-aware Perl character classes,
570 corresponding to `\w`, `\s` and `\d`. This is also necessary for using
571 Unicode-aware word boundary assertions. Note that if this feature is
572 disabled, the `\s` and `\d` character classes are still available if the
573 `unicode-bool` and `unicode-gencat` features are enabled, respectively.
574* **unicode-script** -
575 Provide the data for
576 [Unicode scripts and script extensions](https://www.unicode.org/reports/tr24/).
577 This includes, but is not limited to, `Arabic`, `Cyrillic`, `Hebrew`,
578 `Latin` and `Thai`.
579* **unicode-segment** -
580 Provide the data necessary to provide the properties used to implement the
581 [Unicode text segmentation algorithms](https://www.unicode.org/reports/tr29/).
582 This enables using classes like `\p{gcb=Extend}`, `\p{wb=Katakana}` and
583 `\p{sb=ATerm}`.
584
585
586# Untrusted input
587
588This crate can handle both untrusted regular expressions and untrusted
589search text.
590
591Untrusted regular expressions are handled by capping the size of a compiled
592regular expression.
593(See [`RegexBuilder::size_limit`](struct.RegexBuilder.html#method.size_limit).)
594Without this, it would be trivial for an attacker to exhaust your system's
595memory with expressions like `a{100}{100}{100}`.
596
597Untrusted search text is allowed because the matching engine(s) in this
598crate have time complexity `O(mn)` (with `m ~ regex` and `n ~ search
599text`), which means there's no way to cause exponential blow-up like with
600some other regular expression engines. (We pay for this by disallowing
601features like arbitrary look-ahead and backreferences.)
602
603When a DFA is used, pathological cases with exponential state blow-up are
604avoided by constructing the DFA lazily or in an "online" manner. Therefore,
605at most one new state can be created for each byte of input. This satisfies
606our time complexity guarantees, but can lead to memory growth
607proportional to the size of the input. As a stopgap, the DFA is only
608allowed to store a fixed number of states. When the limit is reached, its
609states are wiped and continues on, possibly duplicating previous work. If
610the limit is reached too frequently, it gives up and hands control off to
611another matching engine with fixed memory requirements.
612(The DFA size limit can also be tweaked. See
613[`RegexBuilder::dfa_size_limit`](struct.RegexBuilder.html#method.dfa_size_limit).)
614*/
615
616#![deny(missing_docs)]
617#![cfg_attr(test, deny(warnings))]
618#![cfg_attr(feature = "pattern", feature(pattern))]
Haibo Huang47619dd2021-01-08 17:05:43 -0800619#![warn(missing_debug_implementations)]
Chih-Hung Hsiehe42c5052020-04-16 10:44:21 -0700620
621#[cfg(not(feature = "std"))]
622compile_error!("`std` feature is currently required to build this crate");
623
624#[cfg(feature = "perf-literal")]
625extern crate aho_corasick;
Haibo Huang49cbe5f2020-05-28 20:14:24 -0700626// #[cfg(doctest)]
627// extern crate doc_comment;
Chih-Hung Hsiehe42c5052020-04-16 10:44:21 -0700628#[cfg(feature = "perf-literal")]
629extern crate memchr;
630#[cfg(test)]
631#[cfg_attr(feature = "perf-literal", macro_use)]
632extern crate quickcheck;
633extern crate regex_syntax as syntax;
634#[cfg(feature = "perf-cache")]
635extern crate thread_local;
636
Haibo Huang49cbe5f2020-05-28 20:14:24 -0700637// #[cfg(doctest)]
638// doc_comment::doctest!("../README.md");
Chih-Hung Hsiehe42c5052020-04-16 10:44:21 -0700639
640#[cfg(feature = "std")]
641pub use error::Error;
642#[cfg(feature = "std")]
643pub use re_builder::set_unicode::*;
644#[cfg(feature = "std")]
645pub use re_builder::unicode::*;
646#[cfg(feature = "std")]
647pub use re_set::unicode::*;
648#[cfg(feature = "std")]
649#[cfg(feature = "std")]
650pub use re_unicode::{
651 escape, CaptureLocations, CaptureMatches, CaptureNames, Captures,
652 Locations, Match, Matches, NoExpand, Regex, Replacer, ReplacerRef, Split,
653 SplitN, SubCaptureMatches,
654};
655
656/**
657Match regular expressions on arbitrary bytes.
658
659This module provides a nearly identical API to the one found in the
660top-level of this crate. There are two important differences:
661
6621. Matching is done on `&[u8]` instead of `&str`. Additionally, `Vec<u8>`
663is used where `String` would have been used.
6642. Unicode support can be disabled even when disabling it would result in
665matching invalid UTF-8 bytes.
666
667# Example: match null terminated string
668
669This shows how to find all null-terminated strings in a slice of bytes:
670
671```rust
672# use regex::bytes::Regex;
673let re = Regex::new(r"(?-u)(?P<cstr>[^\x00]+)\x00").unwrap();
674let text = b"foo\x00bar\x00baz\x00";
675
676// Extract all of the strings without the null terminator from each match.
677// The unwrap is OK here since a match requires the `cstr` capture to match.
678let cstrs: Vec<&[u8]> =
679 re.captures_iter(text)
680 .map(|c| c.name("cstr").unwrap().as_bytes())
681 .collect();
682assert_eq!(vec![&b"foo"[..], &b"bar"[..], &b"baz"[..]], cstrs);
683```
684
685# Example: selectively enable Unicode support
686
687This shows how to match an arbitrary byte pattern followed by a UTF-8 encoded
688string (e.g., to extract a title from a Matroska file):
689
690```rust
691# use std::str;
692# use regex::bytes::Regex;
693let re = Regex::new(
694 r"(?-u)\x7b\xa9(?:[\x80-\xfe]|[\x40-\xff].)(?u:(.*))"
695).unwrap();
696let text = b"\x12\xd0\x3b\x5f\x7b\xa9\x85\xe2\x98\x83\x80\x98\x54\x76\x68\x65";
697let caps = re.captures(text).unwrap();
698
699// Notice that despite the `.*` at the end, it will only match valid UTF-8
700// because Unicode mode was enabled with the `u` flag. Without the `u` flag,
701// the `.*` would match the rest of the bytes.
702let mat = caps.get(1).unwrap();
703assert_eq!((7, 10), (mat.start(), mat.end()));
704
705// If there was a match, Unicode mode guarantees that `title` is valid UTF-8.
706let title = str::from_utf8(&caps[1]).unwrap();
707assert_eq!("☃", title);
708```
709
710In general, if the Unicode flag is enabled in a capture group and that capture
711is part of the overall match, then the capture is *guaranteed* to be valid
712UTF-8.
713
714# Syntax
715
716The supported syntax is pretty much the same as the syntax for Unicode
717regular expressions with a few changes that make sense for matching arbitrary
718bytes:
719
7201. The `u` flag can be disabled even when disabling it might cause the regex to
721match invalid UTF-8. When the `u` flag is disabled, the regex is said to be in
722"ASCII compatible" mode.
7232. In ASCII compatible mode, neither Unicode scalar values nor Unicode
724character classes are allowed.
7253. In ASCII compatible mode, Perl character classes (`\w`, `\d` and `\s`)
726revert to their typical ASCII definition. `\w` maps to `[[:word:]]`, `\d` maps
727to `[[:digit:]]` and `\s` maps to `[[:space:]]`.
7284. In ASCII compatible mode, word boundaries use the ASCII compatible `\w` to
729determine whether a byte is a word byte or not.
7305. Hexadecimal notation can be used to specify arbitrary bytes instead of
731Unicode codepoints. For example, in ASCII compatible mode, `\xFF` matches the
732literal byte `\xFF`, while in Unicode mode, `\xFF` is a Unicode codepoint that
733matches its UTF-8 encoding of `\xC3\xBF`. Similarly for octal notation when
734enabled.
Chih-Hung Hsieh849e4452020-10-26 13:16:47 -07007356. In ASCII compatible mode, `.` matches any *byte* except for `\n`. When the
736`s` flag is additionally enabled, `.` matches any byte.
Chih-Hung Hsiehe42c5052020-04-16 10:44:21 -0700737
738# Performance
739
740In general, one should expect performance on `&[u8]` to be roughly similar to
741performance on `&str`.
742*/
743#[cfg(feature = "std")]
744pub mod bytes {
745 pub use re_builder::bytes::*;
746 pub use re_builder::set_bytes::*;
747 pub use re_bytes::*;
748 pub use re_set::bytes::*;
749}
750
751mod backtrack;
752mod cache;
753mod compile;
754#[cfg(feature = "perf-dfa")]
755mod dfa;
756mod error;
757mod exec;
758mod expand;
759mod find_byte;
760#[cfg(feature = "perf-literal")]
761mod freqs;
762mod input;
763mod literal;
764#[cfg(feature = "pattern")]
765mod pattern;
766mod pikevm;
767mod prog;
768mod re_builder;
769mod re_bytes;
770mod re_set;
771mod re_trait;
772mod re_unicode;
773mod sparse;
774mod utf8;
775
776/// The `internal` module exists to support suspicious activity, such as
777/// testing different matching engines and supporting the `regex-debug` CLI
778/// utility.
779#[doc(hidden)]
780#[cfg(feature = "std")]
781pub mod internal {
782 pub use compile::Compiler;
783 pub use exec::{Exec, ExecBuilder};
784 pub use input::{Char, CharInput, Input, InputAt};
785 pub use literal::LiteralSearcher;
786 pub use prog::{EmptyLook, Inst, InstRanges, Program};
787}