# [−] [src] Struct regex::Regex

    pub struct Regex(_);

A compiled regular expression for matching Unicode strings.

It is represented as either a sequence of bytecode instructions (dynamic) or as a specialized Rust function (native). It can be used to search, split or replace text. All searching is done with an implicit `.*?` at the beginning and end of an expression. To force an expression to match the whole string (or a prefix or a suffix), you must use an anchor like `^` or `$` (or `\A` and `\z`).

While this crate will handle Unicode strings (whether in the regular expression or in the search text), all positions returned are byte indices. Every byte index is guaranteed to be at a Unicode code point boundary.

The lifetimes `'r` and `'t` in this crate correspond to the lifetime of a compiled regular expression and text to search, respectively.

The only methods that allocate new strings are the string replacement methods. All other methods (searching and splitting) return borrowed pointers into the string given.

# Examples

Find the location of a US phone number:

    let re = Regex::new("[0-9]{3}-[0-9]{3}-[0-9]{4}").unwrap();
    let mat = re.find("phone: 111-222-3333").unwrap();
    assert_eq!((mat.start(), mat.end()), (7, 19));

# Using the `std::str::pattern` methods with `Regex`

> Note: This section requires that this crate is compiled with the `pattern` Cargo feature enabled, which requires nightly Rust.

Since `Regex` implements `Pattern`, you can use regexes with methods defined on `&str`. For example, `is_match`, `find`, `find_iter` and `split` can be replaced with `str::contains`, `str::find`, `str::match_indices` and `str::split`.

Here are some examples:

ⓘThis example is not tested

    let re = Regex::new(r"\d+").unwrap();
    let haystack = "a111b222c";

    assert!(haystack.contains(&re));
    assert_eq!(haystack.find(&re), Some(1));
    assert_eq!(haystack.match_indices(&re).collect::<Vec<_>>(),
               vec![(1, 4), (5, 8)]);
    assert_eq!(haystack.split(&re).collect::<Vec<_>>(), vec!["a", "b", "c"]);

## Methods

### `impl Regex` [src]

Core regular expression methods.

#### `pub fn new(re: &str) -> Result<Regex, Error>` [src]

Compiles a regular expression. Once compiled, it can be used repeatedly to search, split or replace text in a string.

If an invalid expression is given, then an error is returned.

#### `pub fn is_match(&self, text: &str) -> bool` [src]

Returns true if and only if the regex matches the string given.

It is recommended to use this method if all you need to do is test a match, since the underlying matching engine may be able to do less work.

# Example

Test if some text contains at least one word with exactly 13 Unicode word characters:

    let text = "I categorically deny having triskaidekaphobia.";
    assert!(Regex::new(r"\b\w{13}\b").unwrap().is_match(text));

#### `pub fn find<'t>(&self, text: &'t str) -> Option<Match<'t>>` [src]

Returns the start and end byte range of the leftmost-first match in `text`. If no match exists, then `None` is returned.

Note that this should only be used if you want to discover the position of the match. Testing the existence of a match is faster if you use `is_match`.

# Example

Find the start and end location of the first word with exactly 13 Unicode word characters:

    let text = "I categorically deny having triskaidekaphobia.";
    let mat = Regex::new(r"\b\w{13}\b").unwrap().find(text).unwrap();
    assert_eq!(mat.start(), 2);
    assert_eq!(mat.end(), 15);

####
ⓘImportant traits for Matches<'r, 't>

### Important traits for Matches<'r, 't>

`impl<'r, 't> Iterator for Matches<'r, 't> type Item = Match<'t>;`
`pub fn find_iter<'r, 't>(&'r self, text: &'t str) -> Matches<'r, 't>` [src]

Returns an iterator for each successive non-overlapping match in `text`, returning the start and end byte indices with respect to `text`.

# Example

Find the start and end location of every word with exactly 13 Unicode word characters:

    let text = "Retroactively relinquishing remunerations is reprehensible.";
    for mat in Regex::new(r"\b\w{13}\b").unwrap().find_iter(text) {
        println!("{:?}", mat);
    }

#### `pub fn captures<'t>(&self, text: &'t str) -> Option<Captures<'t>>` [src]

Returns the capture groups corresponding to the leftmost-first match in `text`. Capture group `0` always corresponds to the entire match. If no match is found, then `None` is returned.

You should only use `captures` if you need access to the location of capturing group matches. Otherwise, `find` is faster for discovering the location of the overall match.

# Examples

Say you have some text with movie names and their release years, like "'Citizen Kane' (1941)". It'd be nice if we could search for text looking like that, while also extracting the movie name and its release year separately.

    let re = Regex::new(r"'([^']+)'\s+\((\d{4})\)").unwrap();
    let text = "Not my favorite movie: 'Citizen Kane' (1941).";
    let caps = re.captures(text).unwrap();
    assert_eq!(caps.get(1).unwrap().as_str(), "Citizen Kane");
    assert_eq!(caps.get(2).unwrap().as_str(), "1941");
    assert_eq!(caps.get(0).unwrap().as_str(), "'Citizen Kane' (1941)");
    // You can also access the groups by index using the Index notation.
    // Note that this will panic on an invalid index.
    assert_eq!(&caps[1], "Citizen Kane");
    assert_eq!(&caps[2], "1941");
    assert_eq!(&caps[0], "'Citizen Kane' (1941)");

Note that the full match is at capture group `0`. Each subsequent capture group is indexed by the order of its opening `(`.

We can make this example a bit clearer by using named capture groups:

    let re = Regex::new(r"'(?P<title>[^']+)'\s+\((?P<year>\d{4})\)")
                   .unwrap();
    let text = "Not my favorite movie: 'Citizen Kane' (1941).";
    let caps = re.captures(text).unwrap();
    assert_eq!(caps.name("title").unwrap().as_str(), "Citizen Kane");
    assert_eq!(caps.name("year").unwrap().as_str(), "1941");
    assert_eq!(caps.get(0).unwrap().as_str(), "'Citizen Kane' (1941)");
    // You can also access the groups by name using the Index notation.
    // Note that this will panic on an invalid group name.
    assert_eq!(&caps["title"], "Citizen Kane");
    assert_eq!(&caps["year"], "1941");
    assert_eq!(&caps[0], "'Citizen Kane' (1941)");

Here we name the capture groups, which we can access with the `name` method or the `Index` notation with a `&str`. Note that the named capture groups are still accessible with `get` or the `Index` notation with a `usize`.

The `0`th capture group is always unnamed, so it must always be accessed with `get(0)` or `[0]`.

####
ⓘImportant traits for CaptureMatches<'r, 't>

### Important traits for CaptureMatches<'r, 't>

`impl<'r, 't> Iterator for CaptureMatches<'r, 't> type Item = Captures<'t>;`
`pub fn captures_iter<'r, 't>(&'r self, text: &'t str) -> CaptureMatches<'r, 't>` [src]

Returns an iterator over all the non-overlapping capture groups matched in `text`. This is operationally the same as `find_iter`, except it yields information about capturing group matches.

# Example

We can use this to find all movie titles and their release years in some text, where the movie is formatted like "'Title' (xxxx)":

    let re = Regex::new(r"'(?P<title>[^']+)'\s+\((?P<year>\d{4})\)")
                   .unwrap();
    let text = "'Citizen Kane' (1941), 'The Wizard of Oz' (1939), 'M' (1931).";
    for caps in re.captures_iter(text) {
        println!("Movie: {:?}, Released: {:?}",
                 &caps["title"], &caps["year"]);
    }
    // Output:
    // Movie: Citizen Kane, Released: 1941
    // Movie: The Wizard of Oz, Released: 1939
    // Movie: M, Released: 1931

####
ⓘImportant traits for Split<'r, 't>

### Important traits for Split<'r, 't>

`impl<'r, 't> Iterator for Split<'r, 't> type Item = &'t str;`
`pub fn split<'r, 't>(&'r self, text: &'t str) -> Split<'r, 't>` [src]

Returns an iterator of substrings of `text` delimited by a match of the regular expression. Namely, each element of the iterator corresponds to text that isn't matched by the regular expression.

This method will not copy the text given.

# Example

To split a string delimited by arbitrary amounts of spaces or tabs:

    let re = Regex::new(r"[ \t]+").unwrap();
    let fields: Vec<&str> = re.split("a b \t  c\td    e").collect();
    assert_eq!(fields, vec!["a", "b", "c", "d", "e"]);

####
ⓘImportant traits for SplitN<'r, 't>

### Important traits for SplitN<'r, 't>

`impl<'r, 't> Iterator for SplitN<'r, 't> type Item = &'t str;`
`pub fn splitn<'r, 't>(&'r self, text: &'t str, limit: usize) -> SplitN<'r, 't>` [src]

Returns an iterator of at most `limit` substrings of `text` delimited by a match of the regular expression. (A `limit` of `0` will return no substrings.) Namely, each element of the iterator corresponds to text that isn't matched by the regular expression. The remainder of the string that is not split will be the last element in the iterator.

This method will not copy the text given.

# Example

Get the first two words in some text:

    let re = Regex::new(r"\W+").unwrap();
    let fields: Vec<&str> = re.splitn("Hey! How are you?", 3).collect();
    assert_eq!(fields, vec!("Hey", "How", "are you?"));

#### `pub fn replace<'t, R: Replacer>(&self, text: &'t str, rep: R) -> Cow<'t, str>` [src]

Replaces the leftmost-first match with the replacement provided. The replacement can be a regular string (where `$N` and `$name` are expanded to match capture groups) or a function that takes the matches' `Captures` and returns the replaced string.

If no match is found, then a copy of the string is returned unchanged.

# Replacement string syntax

All instances of `$name` in the replacement text is replaced with the corresponding capture group `name`.

`name` may be an integer corresponding to the index of the capture group (counted by order of opening parenthesis where `0` is the entire match) or it can be a name (consisting of letters, digits or underscores) corresponding to a named capture group.

If `name` isn't a valid capture group (whether the name doesn't exist or isn't a valid index), then it is replaced with the empty string.

The longest possible name is used. e.g., `$1a` looks up the capture group named `1a` and not the capture group at index `1`. To exert more precise control over the name, use braces, e.g., `${1}a`.

To write a literal `$` use `$$`.

# Examples

Note that this function is polymorphic with respect to the replacement. In typical usage, this can just be a normal string:

    let re = Regex::new("[^01]+").unwrap();
    assert_eq!(re.replace("1078910", ""), "1010");

But anything satisfying the `Replacer` trait will work. For example, a closure of type `|&Captures| -> String` provides direct access to the captures corresponding to a match. This allows one to access capturing group matches easily:

    let re = Regex::new(r"([^,\s]+),\s+(\S+)").unwrap();
    let result = re.replace("Springsteen, Bruce", |caps: &Captures| {
        format!("{} {}", &caps[2], &caps[1])
    });
    assert_eq!(result, "Bruce Springsteen");

But this is a bit cumbersome to use all the time. Instead, a simple syntax is supported that expands `$name` into the corresponding capture group. Here's the last example, but using this expansion technique with named capture groups:

    let re = Regex::new(r"(?P<last>[^,\s]+),\s+(?P<first>\S+)").unwrap();
    let result = re.replace("Springsteen, Bruce", "$first $last");
    assert_eq!(result, "Bruce Springsteen");

Note that using `$2` instead of `$first` or `$1` instead of `$last` would produce the same result. To write a literal `$` use `$$`.

Sometimes the replacement string requires use of curly braces to delineate a capture group replacement and surrounding literal text. For example, if we wanted to join two words together with an underscore:

    let re = Regex::new(r"(?P<first>\w+)\s+(?P<second>\w+)").unwrap();
    let result = re.replace("deep fried", "${first}_$second");
    assert_eq!(result, "deep_fried");

Without the curly braces, the capture group name `first_` would be used, and since it doesn't exist, it would be replaced with the empty string.

Finally, sometimes you just want to replace a literal string with no regard for capturing group expansion. This can be done by wrapping a byte string with `NoExpand`:

    use regex::NoExpand;

    let re = Regex::new(r"(?P<last>[^,\s]+),\s+(\S+)").unwrap();
    let result = re.replace("Springsteen, Bruce", NoExpand("$2 $last"));
    assert_eq!(result, "$2 $last");

#### `pub fn replace_all<'t, R: Replacer>(
&self,
text: &'t str,
rep: R
) -> Cow<'t, str>` [src]

Replaces all non-overlapping matches in `text` with the replacement provided. This is the same as calling `replacen` with `limit` set to `0`.

See the documentation for `replace` for details on how to access capturing group matches in the replacement string.

#### `pub fn replacen<'t, R: Replacer>(
&self,
text: &'t str,
limit: usize,
rep: R
) -> Cow<'t, str>` [src]

Replaces at most `limit` non-overlapping matches in `text` with the replacement provided. If `limit` is 0, then all non-overlapping matches are replaced.

See the documentation for `replace` for details on how to access capturing group matches in the replacement string.

### `impl Regex` [src]

Advanced or "lower level" search methods.

#### `pub fn shortest_match(&self, text: &str) -> Option<usize>` [src]

Returns the end location of a match in the text given.

This method may have the same performance characteristics as `is_match`, except it provides an end location for a match. In particular, the location returned may be shorter than the proper end of the leftmost-first match.

# Example

Typically, `a+` would match the entire first sequence of `a` in some text, but `shortest_match` can give up as soon as it sees the first `a`.

    let text = "aaaaa";
    let pos = Regex::new(r"a+").unwrap().shortest_match(text);
    assert_eq!(pos, Some(1));

#### `pub fn shortest_match_at(&self, text: &str, start: usize) -> Option<usize>` [src]

Returns the same as shortest_match, but starts the search at the given offset.

The significance of the starting point is that it takes the surrounding context into consideration. For example, the `\A` anchor can only match when `start == 0`.

#### `pub fn is_match_at(&self, text: &str, start: usize) -> bool` [src]

Returns the same as is_match, but starts the search at the given offset.

The significance of the starting point is that it takes the surrounding context into consideration. For example, the `\A` anchor can only match when `start == 0`.

#### `pub fn find_at<'t>(&self, text: &'t str, start: usize) -> Option<Match<'t>>` [src]

Returns the same as find, but starts the search at the given offset.

The significance of the starting point is that it takes the surrounding context into consideration. For example, the `\A` anchor can only match when `start == 0`.

#### `pub fn captures_read<'t>(
&self,
locs: &mut CaptureLocations,
text: &'t str
) -> Option<Match<'t>>` [src]

This is like `captures`, but uses `CaptureLocations` instead of `Captures` in order to amortize allocations.

To create a `CaptureLocations` value, use the `Regex::capture_locations` method.

This returns the overall match if this was successful, which is always equivalence to the `0`th capture group.

#### `pub fn captures_read_at<'t>(
&self,
locs: &mut CaptureLocations,
text: &'t str,
start: usize
) -> Option<Match<'t>>` [src]

Returns the same as captures, but starts the search at the given offset and populates the capture locations given.

The significance of the starting point is that it takes the surrounding context into consideration. For example, the `\A` anchor can only match when `start == 0`.

### `impl Regex` [src]

Auxiliary methods.

#### `pub fn as_str(&self) -> &str` [src]

Returns the original string of this regex.

####
ⓘImportant traits for CaptureNames<'r>

### Important traits for CaptureNames<'r>

`impl<'r> Iterator for CaptureNames<'r> type Item = Option<&'r str>;`
`pub fn capture_names(&self) -> CaptureNames` [src]

Returns an iterator over the capture names.

#### `pub fn captures_len(&self) -> usize` [src]

Returns the number of captures.

#### `pub fn capture_locations(&self) -> CaptureLocations` [src]

Returns an empty set of capture locations that can be reused in multiple calls to `captures_read` or `captures_read_at`.

## Trait Implementations

### `impl Clone for Regex` [src]

#### `fn clone(&self) -> Regex` [src]

Returns a copy of the value. Read more

#### `fn clone_from(&mut self, source: &Self)`1.0.0 [src]

Performs copy-assignment from `source`. Read more

### `impl Display for Regex` [src]

#### `fn fmt(&self, f: &mut Formatter) -> Result` [src]

Shows the original regular expression.

### `impl Debug for Regex` [src]

#### `fn fmt(&self, f: &mut Formatter) -> Result` [src]

Shows the original regular expression.

### `impl FromStr for Regex` [src]

#### `type Err = Error`

The associated error which can be returned from parsing.

#### `fn from_str(s: &str) -> Result<Regex, Error>` [src]

Attempts to parse a string into a regular expression

## Auto Trait Implementations

### `impl Send for Regex`

### `impl Sync for Regex`

## Blanket Implementations

### `impl<T> From<T> for T` [src]

#### `fn from(t: T) -> T` [src]

Performs the conversion.

### `impl<T> ToOwned for T where
T: Clone,` [src]

#### `type Owned = T`

The resulting type after obtaining ownership.

#### `fn to_owned(&self) -> T` [src]

Creates owned data from borrowed data, usually by cloning. Read more

#### `fn clone_into(&self, target: &mut T)` [src]

🔬 This is a nightly-only experimental API. (`toowned_clone_into`)

recently added

Uses borrowed data to replace owned data, usually by cloning. Read more

### `impl<T> ToString for T where
T: Display + ?Sized,` [src]

#### `default fn to_string(&self) -> String` [src]

Converts the given value to a `String`. Read more

### `impl<T, U> Into<U> for T where
U: From<T>,` [src]

#### `fn into(self) -> U` [src]

Performs the conversion.

### `impl<T, U> TryFrom<U> for T where
U: Into<T>,` [src]

#### `type Error = Infallible`

The type returned in the event of a conversion error.

#### `fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>` [src]

Performs the conversion.

### `impl<T, U> TryInto<U> for T where
U: TryFrom<T>,` [src]

#### `type Error = <U as TryFrom<T>>::Error`

The type returned in the event of a conversion error.

#### `fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>` [src]

Performs the conversion.

### `impl<T> BorrowMut<T> for T where
T: ?Sized,` [src]

#### `fn borrow_mut(&mut self) -> &mut T` [src]

Mutably borrows from an owned value. Read more

### `impl<T> Borrow<T> for T where
T: ?Sized,` [src]

#### `fn borrow(&self) -> &T` [src]

Immutably borrows from an owned value. Read more

### `impl<T> Any for T where
T: 'static + ?Sized,` [src]

#### `fn type_id(&self) -> TypeId` [src]

Gets the `TypeId` of `self`. Read more

# Help

## Keyboard Shortcuts

`?`
  Show this help dialog
`S`
  Focus the search field
`↑`
  Move up in search results
`↓`
  Move down in search results
`↹`
  Switch tab
`⏎`
  Go to active search result
`+`
  Expand all sections
`-`
  Collapse all sections

## Search Tricks

Prefix searches with a type followed by a colon (e.g., `fn:`) to restrict the search to a given type.

Accepted types are: `fn`, `mod`, `struct`, `enum`, `trait`, `type`, `macro`, and `const`.

Search functions by type signature (e.g., `vec -> usize` or `* -> vec`)

Search multiple things at once by splitting your query with comma (e.g., `str,u8` or `String,struct:Vec,test`)