Lazy Regex

https://docs.rs/lazy-regex/latest/
Admin
With lazy-regex macros, regular expressions are checked at compile time, compiled only once with...
Tokens:100,030
Snippets:1,158
Trust Score:9.7
Update:3 months ago
Show doc for...
Tokens:
Raw
### Lazy Initialization Example

Source: https://docs.rs/lazy-regex/latest/lazy_regex/struct.Lazy.html?search=

Demonstrates using Lazy for a thread-safe static HashMap.

```rust
use std::collections::HashMap;

use once_cell::sync::Lazy;

static HASHMAP: Lazy<HashMap<i32, String>> = Lazy::new(|| {
    println!("initializing");
    let mut m = HashMap::new();
    m.insert(13, "Spica".to_string());
    m.insert(74, "Hoyten".to_string());
    m
});

fn main() {
    println!("ready");
    std::thread::spawn(|| {
        println!("{:?}", HASHMAP.get(&13));
    }).join().unwrap();
    println!("{:?}", HASHMAP.get(&74));

    // Prints:
    //   ready
    //   initializing
    //   Some("Spica")
    //   Some("Hoyten")
}
```

--------------------------------

### Perform regex matching with starting offset

Source: https://docs.rs/lazy-regex/latest/lazy_regex/struct.Regex.html?search=u32+-%3E+bool

Demonstrates how starting a search at an offset affects look-around assertions compared to slicing the haystack.

```rust
use regex::Regex;

let re = Regex::new(r"\bchew\b").unwrap();
let hay = "eschew";
// We get a match here, but it's probably not intended.
assert!(re.is_match(&hay[2..]));
// No match because the  assertions take the context into account.
assert!(!re.is_match_at(hay, 2));
```

```rust
use regex::Regex;

let re = Regex::new(r"\bchew\b").unwrap();
let hay = "eschew";
// We get a match here, but it's probably not intended.
assert_eq!(re.find(&hay[2..]).map(|m| m.range()), Some(0..4));
// No match because the  assertions take the context into account.
assert_eq!(re.find_at(hay, 2), None);
```

```rust
use regex::Regex;

let re = Regex::new(r"\bchew\b").unwrap();
let hay = "eschew";
// We get a match here, but it's probably not intended.
assert_eq!(&re.captures(&hay[2..]).unwrap()[0], "chew");
// No match because the  assertions take the context into account.
assert!(re.captures_at(hay, 2).is_none());
```

--------------------------------

### Build Regexes

Source: https://docs.rs/lazy-regex/latest/src/lazy_regex/lib.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Examples of building regexes with various flags, raw literals, and byte-based support.

```rust
# use lazy_regex::regex;
let r = regex!("sa+$");
assert_eq!(r.is_match("Saa"), false);
```

```rust
# use lazy_regex::regex;
let r = regex!("sa+$"i);
assert_eq!(r.is_match("Saa"), true);
```

```rust
# use lazy_regex::regex;
let r = regex!(r#"^"+$"#);
assert_eq!(r.is_match("\"\""), true);
```

```rust
# use lazy_regex::regex;
let r = regex!(r#"^\s*("[a-t]*"\s*)+$"#i);
assert_eq!(r.is_match(r#" "Aristote" "Platon" "#), true);
```

```rust
# use lazy_regex::regex;
let r = regex!("(byte)?string$"B);
assert_eq!(r.is_match(b"bytestring"), true);
```

```rust
# use lazy_regex::regex;
let r = regex!(r"(?x)
    (?P<name>\w+)
    -
    (?P<version>[0-9.]+)
");
assert_eq!(r.find("This is lazy_regex-2.2!").unwrap().as_str(), "lazy_regex-2.2");
```

```rust
let r = regex!("(unclosed");
```

--------------------------------

### shortest_match_at

Source: https://docs.rs/lazy-regex/latest/lazy_regex/struct.Regex.html?search=u32+-%3E+bool

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

```APIDOC
## pub fn shortest_match_at(&self, haystack: &str, start: usize) -> Option<usize>

### Description
Returns the same as `Regex::shortest_match`, but starts the search at the given offset. The offset returned is relative to the beginning of the haystack.

### Parameters
- **haystack** (&str) - The string to search.
- **start** (usize) - The byte offset to start the search from.

### Returns
- **Option<usize>** - The end byte offset of the match, if found.
```

--------------------------------

### Perform shortest match starting at an offset

Source: https://docs.rs/lazy-regex/latest/lazy_regex/struct.BytesRegex.html?search=

Finds the shortest match starting from a specific byte offset, allowing look-around assertions to consider the surrounding context.

```rust
use regex::bytes::Regex;

let re = Regex::new(r"\bchew\b").unwrap();
let hay = b"eschew";
// We get a match here, but it's probably not intended.
assert_eq!(re.shortest_match(&hay[2..]), Some(4));
// No match because the  assertions take the context into account.
assert_eq!(re.shortest_match_at(hay, 2), None);
```

--------------------------------

### Split String Basic Usage

Source: https://docs.rs/lazy-regex/latest/lazy_regex/struct.Regex.html

Various examples of splitting strings using different regex patterns.

```rust
use regex::Regex;

let re = Regex::new(r" ").unwrap();
let hay = "Mary had a little lamb";
let got: Vec<&str> = re.split(hay).collect();
assert_eq!(got, vec!["Mary", "had", "a", "little", "lamb"]);

let re = Regex::new(r"X").unwrap();
let hay = "";
let got: Vec<&str> = re.split(hay).collect();
assert_eq!(got, vec![""]);

let re = Regex::new(r"X").unwrap();
let hay = "lionXXtigerXleopard";
let got: Vec<&str> = re.split(hay).collect();
assert_eq!(got, vec!["lion", "", "tiger", "leopard"]);

let re = Regex::new(r"::").unwrap();
let hay = "lion::tiger::leopard";
let got: Vec<&str> = re.split(hay).collect();
assert_eq!(got, vec!["lion", "tiger", "leopard"]);
```

--------------------------------

### Find match starting at an offset

Source: https://docs.rs/lazy-regex/latest/lazy_regex/struct.BytesRegex.html?search=

Returns the range of the first match found starting from the specified offset.

```rust
use regex::bytes::Regex;

let re = Regex::new(r"\bchew\b").unwrap();
let hay = b"eschew";
// We get a match here, but it's probably not intended.
assert_eq!(re.find(&hay[2..]).map(|m| m.range()), Some(0..4));
// No match because the  assertions take the context into account.
assert_eq!(re.find_at(hay, 2), None);
```

--------------------------------

### Perform regex replacement

Source: https://docs.rs/lazy-regex/latest/lazy_regex/macro.regex.html

Example of using the macro to perform a regex replacement operation.

```rust
let verbose = regex!(r#"_([\d\.]+)"#)
    .replace("This is lazy-regex_2.2", " (version $1)");
assert_eq!(verbose, "This is lazy-regex (version 2.2)");
```

--------------------------------

### pub fn shortest_match_at(&self, haystack: &str, start: usize) -> Option<usize>

Source: https://docs.rs/lazy-regex/latest/lazy_regex/struct.Regex.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Performs the same operation as `shortest_match` but begins the search at the specified byte offset.

```APIDOC
## pub fn shortest_match_at

### Description
Returns the end byte offset of the first match in the haystack, starting the search at the provided offset.

### Parameters
- **haystack** (&str) - The string to search.
- **start** (usize) - The byte offset to begin the search.

### Returns
- **Option<usize>** - The end byte offset of the match, relative to the start of the haystack.
```

--------------------------------

### Search with shortest_match_at

Source: https://docs.rs/lazy-regex/latest/lazy_regex/struct.Regex.html

Demonstrates how starting a search at an offset affects context-sensitive assertions like word boundaries.

```rust
let re = Regex::new(r"\bchew\b").unwrap();
let hay = "eschew";
// We get a match here, but it's probably not intended.
assert_eq!(re.shortest_match(&hay[2..]), Some(4));
// No match because the  assertions take the context into account.
assert_eq!(re.shortest_match_at(hay, 2), None);
```

--------------------------------

### Additional splitn usage scenarios

Source: https://docs.rs/lazy-regex/latest/lazy_regex/struct.BytesRegex.html?search=

Various examples showing how splitn behaves with different regex patterns, input strings, and limit values.

```rust
use regex::bytes::Regex;

let re = Regex::new(r" ").unwrap();
let hay = b"Mary had a little lamb";
let got: Vec<&[u8]> = re.splitn(hay, 3).collect();
assert_eq!(got, vec![&b"Mary"[..], &b"had"[..], &b"a little lamb"[..]]);

let re = Regex::new(r"X").unwrap();
let hay = b"";
let got: Vec<&[u8]> = re.splitn(hay, 3).collect();
assert_eq!(got, vec![&b""[..]]);

let re = Regex::new(r"X").unwrap();
let hay = b"lionXXtigerXleopard";
let got: Vec<&[u8]> = re.splitn(hay, 3).collect();
assert_eq!(got, vec![&b"lion"[..], &b""[..], &b"tigerXleopard"[..]]);

let re = Regex::new(r"::").unwrap();
let hay = b"lion::tiger::leopard";
let got: Vec<&[u8]> = re.splitn(hay, 2).collect();
assert_eq!(got, vec![&b"lion"[..], &b"tiger::leopard"[..]]);

let re = Regex::new(r"X").unwrap();
let hay = b"abcXdef";
let got: Vec<&[u8]> = re.splitn(hay, 1).collect();
assert_eq!(got, vec![&b"abcXdef"[..]]);

let re = Regex::new(r"X").unwrap();
let hay = b"abcdef";
let got: Vec<&[u8]> = re.splitn(hay, 2).collect();
assert_eq!(got, vec![&b"abcdef"[..]]);

let re = Regex::new(r"X").unwrap();
let hay = b"abcXdef";
let got: Vec<&[u8]> = re.splitn(hay, 0).collect();
assert!(got.is_empty());
```

--------------------------------

### Search with find_at

Source: https://docs.rs/lazy-regex/latest/lazy_regex/struct.Regex.html

Demonstrates find_at usage for context-aware matching starting at a specific byte offset.

```rust
use regex::Regex;

let re = Regex::new(r"\bchew\b").unwrap();
let hay = "eschew";
// We get a match here, but it's probably not intended.
assert_eq!(re.find(&hay[2..]).map(|m| m.range()), Some(0..4));
// No match because the  assertions take the context into account.
assert_eq!(re.find_at(hay, 2), None);
```

--------------------------------

### Configure Line Terminator

Source: https://docs.rs/lazy-regex/latest/lazy_regex/struct.BytesRegexBuilder.html

Examples demonstrating how to set a custom line terminator byte, its effect on dot matching, and handling non-ASCII bytes.

```rust
use regex::bytes::RegexBuilder;

let re = RegexBuilder::new(r"^foo$")
    .multi_line(true)
    .line_terminator(b'\x00')
    .build()
    .unwrap();
let hay = b"\x00foo\x00";
assert_eq!(Some(1..4), re.find(hay).map(|m| m.range()));
```

```rust
use regex::bytes::RegexBuilder;

let re = RegexBuilder::new(r".")
    .line_terminator(b'\x00')
    .build()
    .unwrap();
assert!(re.is_match(b"\n"));
assert!(!re.is_match(b"\x00"));
```

```rust
use regex::bytes::RegexBuilder;

assert!(
    RegexBuilder::new(r".")
        .unicode(false)
        .line_terminator(0x80)
        .build()
        .is_ok(),
);
```

--------------------------------

### Search with captures_at

Source: https://docs.rs/lazy-regex/latest/lazy_regex/struct.Regex.html

Illustrates how captures_at handles context-sensitive assertions when starting from an offset.

```rust
use regex::Regex;

let re = Regex::new(r"\bchew\b").unwrap();
let hay = "eschew";
// We get a match here, but it's probably not intended.
assert_eq!(&re.captures(&hay[2..]).unwrap()[0], "chew");
// No match because the  assertions take the context into account.
assert!(re.captures_at(hay, 2).is_none());
```

--------------------------------

### Split String with Boundary Matches

Source: https://docs.rs/lazy-regex/latest/lazy_regex/struct.Regex.html

Shows how separators at the start or end of a string produce empty substrings.

```rust
use regex::Regex;

let re = Regex::new(r"0").unwrap();
let hay = "010";
let got: Vec<&str> = re.split(hay).collect();
assert_eq!(got, vec!["", "1", ""]);
```

--------------------------------

### Replace all matches with replace_all

Source: https://docs.rs/lazy-regex/latest/lazy_regex/struct.BytesRegex.html?search=

Example of using replace_all to flip whitespace-delimited fields and normalize delimiters.

```rust
use regex::bytes::Regex;

let re = Regex::new(r"(?m)^(\S+)[\s--\r\n]+(\S+)$").unwrap();
let hay = b"
Greetings  1973
Wild\t1973
BornToRun\t\t\t\t1975
Darkness                    1978
TheRiver 1980
";
let new = re.replace_all(hay, b"$2 $1");
assert_eq!(new, &b"
1973 Greetings
1973 Wild
1975 BornToRun
1978 Darkness
1980 TheRiver
"[..]);
```

--------------------------------

### Regex Capture Group Pattern

Source: https://docs.rs/lazy-regex/latest/lazy_regex/struct.Captures.html

An example regex pattern demonstrating named and unnamed capture groups.

```regex
(?<first>\w)(\w)(?:\w)\w(?<last>\w)
```

--------------------------------

### pub fn get(&self, i: usize) -> Option<Match<'h>>

Source: https://docs.rs/lazy-regex/latest/lazy_regex/struct.Captures.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Returns the Match associated with the capture group at index i. Returns None if the index is invalid or the group did not participate in the match.

```APIDOC
## pub fn get(&self, i: usize) -> Option<Match<'h>>

### Description
Returns the `Match` associated with the capture group at index `i`. If `i` does not correspond to a capture group, or if the capture group did not participate in the match, then `None` is returned. When `i == 0`, this is guaranteed to return a non-`None` value.
```

--------------------------------

### pub fn get_match(&self) -> Match<'h>

Source: https://docs.rs/lazy-regex/latest/lazy_regex/struct.Captures.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Returns the overall match for the capture, equivalent to calling get(0).unwrap().

```APIDOC
## pub fn get_match(&self) -> Match<'h>

### Description
Return the overall match for the capture. This returns the match for index `0`.
```

--------------------------------

### pub fn get_match(&self) -> Match<'h>

Source: https://docs.rs/lazy-regex/latest/lazy_regex/struct.Captures.html?search=std%3A%3Avec

Returns the overall match for the capture, equivalent to calling get(0).unwrap().

```APIDOC
## pub fn get_match(&self) -> Match<'h>

### Description
Return the overall match for the capture. This returns the match for index 0.
```

--------------------------------

### Perform capture search at a specific offset

Source: https://docs.rs/lazy-regex/latest/lazy_regex/struct.BytesRegex.html?search=

Demonstrates using captures_read_at to start a search at a specific byte offset, which affects how look-around assertions behave.

```rust
use regex::bytes::Regex;

let re = Regex::new(r"\bchew\b").unwrap();
let hay = b"eschew";
let mut locs = re.capture_locations();
// We get a match here, but it's probably not intended.
assert!(re.captures_read(&mut locs, &hay[2..]).is_some());
// No match because the  assertions take the context into account.
assert!(re.captures_read_at(&mut locs, hay, 2).is_none());
```

--------------------------------

### Build a simple regex

Source: https://docs.rs/lazy-regex/latest/src/lazy_regex/lib.rs.html?search=std%3A%3Avec

Demonstrates basic regex creation and matching.

```rust
# use lazy_regex::regex;
let r = regex!("sa+$");
assert_eq!(r.is_match("Saa"), false);
```

--------------------------------

### Capture matches starting at an offset

Source: https://docs.rs/lazy-regex/latest/lazy_regex/struct.BytesRegex.html?search=

Retrieves capture groups for a match starting from the specified offset.

```rust
use regex::bytes::Regex;

let re = Regex::new(r"\bchew\b").unwrap();
let hay = b"eschew";
// We get a match here, but it's probably not intended.
assert_eq!(&re.captures(&hay[2..]).unwrap()[0], b"chew");
// No match because the  assertions take the context into account.
assert!(re.captures_at(hay, 2).is_none());
```

--------------------------------

### Check for match starting at an offset

Source: https://docs.rs/lazy-regex/latest/lazy_regex/struct.BytesRegex.html?search=

Determines if a match exists starting from a specific offset, respecting context-sensitive assertions.

```rust
use regex::bytes::Regex;

let re = Regex::new(r"\bchew\b").unwrap();
let hay = b"eschew";
// We get a match here, but it's probably not intended.
assert!(re.is_match(&hay[2..]));
// No match because the  assertions take the context into account.
assert!(!re.is_match_at(hay, 2));
```

--------------------------------

### Basic split usage and edge cases

Source: https://docs.rs/lazy-regex/latest/lazy_regex/struct.BytesRegex.html?search=

Demonstrates standard splitting, empty haystacks, and handling of multiple separators.

```rust
use regex::bytes::Regex;

let re = Regex::new(r" ").unwrap();
let hay = b"Mary had a little lamb";
let got: Vec<&[u8]> = re.split(hay).collect();
assert_eq!(got, vec![
    &b"Mary"[..], &b"had"[..], &b"a"[..], &b"little"[..], &b"lamb"[..],
]);

let re = Regex::new(r"X").unwrap();
let hay = b"";
let got: Vec<&[u8]> = re.split(hay).collect();
assert_eq!(got, vec![&b""[..]]);

let re = Regex::new(r"X").unwrap();
let hay = b"lionXXtigerXleopard";
let got: Vec<&[u8]> = re.split(hay).collect();
assert_eq!(got, vec![
    &b"lion"[..], &b""[..], &b"tiger"[..], &b"leopard"[..],
]);

let re = Regex::new(r"::").unwrap();
let hay = b"lion::tiger::leopard";
let got: Vec<&[u8]> = re.split(hay).collect();
assert_eq!(got, vec![&b"lion"[..], &b"tiger"[..], &b"leopard"[..]]);
```

--------------------------------

### captures_read_at

Source: https://docs.rs/lazy-regex/latest/lazy_regex/struct.Regex.html

Performs a capture read operation starting at a specific offset.

```APIDOC
## pub fn captures_read_at<'h>(&self, locs: &mut CaptureLocations, haystack: &'h str, start: usize) -> Option<Match<'h>>

### Description
Combines the functionality of `captures_read` with a starting offset. This method respects surrounding context for assertions.

### Parameters
- **locs** (&mut CaptureLocations) - The storage for capture offsets.
- **haystack** (&str) - The string to search.
- **start** (usize) - The byte offset to begin the search.

### Panics
Panics if `start >= haystack.len() + 1` or if `locs` was not created by this regex.
```

--------------------------------

### Compiling Regex patterns

Source: https://docs.rs/lazy-regex/latest/lazy_regex/struct.BytesRegex.html?search=

Shows how to compile a regex and handle potential errors due to invalid syntax or size limits.

```rust
use regex::bytes::Regex;

// An Invalid pattern because of an unclosed parenthesis
assert!(Regex::new(r"foo(bar").is_err());
// An invalid pattern because the regex would be too big
// because Unicode tends to inflate things.
assert!(Regex::new(r"\w{1000}").is_err());
// Disabling Unicode can make the regex much smaller,
// potentially by up to or more than an order of magnitude.
assert!(Regex::new(r"(?-u:\w){1000}").is_ok());
```

--------------------------------

### BytesRegexBuilder::build

Source: https://docs.rs/lazy-regex/latest/lazy_regex/struct.BytesRegexBuilder.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Compiles the pattern with the current configuration.

```APIDOC
## pub fn build(&self) -> Result<Regex, Error>

### Description
Compiles the pattern given to `RegexBuilder::new` with the configuration set on this builder. Returns an error if the pattern is invalid or exceeds size limits.
```

--------------------------------

### captures_read_at

Source: https://docs.rs/lazy-regex/latest/lazy_regex/struct.Regex.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Performs a capture read search starting at a specific offset.

```APIDOC
## pub fn captures_read_at<'h>(&self, locs: &mut CaptureLocations, haystack: &'h str, start: usize) -> Option<Match<'h>>

### Description
Combines the functionality of captures_read and a starting offset search.

### Parameters
- **locs** (&mut CaptureLocations) - The object to store capture offsets.
- **haystack** (&str) - The string to search.
- **start** (usize) - The byte offset to begin the search.

### Panics
Panics if start >= haystack.len() + 1 or if the CaptureLocations was not created by this regex.
```

--------------------------------

### Build a regex with flag(s)

Source: https://docs.rs/lazy-regex/latest/src/lazy_regex/lib.rs.html?search=std%3A%3Avec

Shows how to apply regex flags as a suffix.

```rust
# use lazy_regex::regex;
let r = regex!("sa+$"i);
assert_eq!(r.is_match("Saa"), true);
```

--------------------------------

### captures_at

Source: https://docs.rs/lazy-regex/latest/lazy_regex/struct.Regex.html?search=u32+-%3E+bool

Returns the captures found in the haystack starting at the specified offset.

```APIDOC
## pub fn captures_at<'h>(&self, haystack: &'h str, start: usize) -> Option<Captures<'h>>

### Description
Returns the same as `Regex::captures`, but starts the search at the given offset. The significance of the starting point is that it takes the surrounding context into consideration.

### Parameters
- **haystack** (&str) - The string to search.
- **start** (usize) - The byte offset to start the search.

### Panics
This panics when `start >= haystack.len() + 1`.
```

--------------------------------

### find_at

Source: https://docs.rs/lazy-regex/latest/lazy_regex/struct.BytesRegex.html?search=std%3A%3Avec

Finds the first match in the haystack starting at the given offset.

```APIDOC
## pub fn find_at<'h>(&self, haystack: &'h [u8], start: usize) -> Option<Match<'h>>

### Description
Returns the same as `Regex::find`, but starts the search at the given offset. The significance of the starting point is that it takes the surrounding context into consideration.

### Panics
This panics when `start >= haystack.len() + 1`.
```

--------------------------------

### is_match_at

Source: https://docs.rs/lazy-regex/latest/lazy_regex/struct.BytesRegex.html?search=std%3A%3Avec

Checks if the regex matches the haystack starting at the given offset.

```APIDOC
## pub fn is_match_at(&self, haystack: &[u8], start: usize) -> bool

### Description
Returns the same as `Regex::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.

### Panics
This panics when `start >= haystack.len() + 1`.
```

--------------------------------

### Implement a fallible replacement routine

Source: https://docs.rs/lazy-regex/latest/lazy_regex/struct.BytesRegex.html?search=

Demonstrates how to manually implement a replacement routine that can return an error, as the standard replace_all API does not support fallibility.

```rust
use regex::bytes::{Captures, Regex};

fn replace_all<E>(
    re: &Regex,
    haystack: &[u8],
    replacement: impl Fn(&Captures) -> Result<Vec<u8>, E>,
) -> Result<Vec<u8>, E> {
    let mut new = Vec::with_capacity(haystack.len());
    let mut last_match = 0;
    for caps in re.captures_iter(haystack) {
        let m = caps.get(0).unwrap();
        new.extend_from_slice(&haystack[last_match..m.start()]);
        new.extend_from_slice(&replacement(&caps)?);
        last_match = m.end();
    }
    new.extend_from_slice(&haystack[last_match..]);
    Ok(new)
}

// Let's replace each word with the number of bytes in that word.
// But if we see a word that is "too long," we'll give up.
let re = Regex::new(r"\w+").unwrap();
let replacement = |caps: &Captures| -> Result<Vec<u8>, &'static str> {
    if caps[0].len() >= 5 {
        return Err("word too long");
    }
    Ok(caps[0].len().to_string().into_bytes())
};
assert_eq!(
    Ok(b"2 3 3 3?".to_vec()),
    replace_all(&re, b"hi how are you?", &replacement),
);
assert!(replace_all(&re, b"hi there", &replacement).is_err());
```

--------------------------------

### BytesRegexBuilder::new

Source: https://docs.rs/lazy-regex/latest/lazy_regex/struct.BytesRegexBuilder.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Creates a new builder with a default configuration for the given pattern.

```APIDOC
## pub fn new(pattern: &str) -> RegexBuilder

### Description
Create a new builder with a default configuration for the given pattern. If the pattern is invalid or exceeds the configured size limits, an error will be returned when `build` is called.
```

--------------------------------

### captures_read_at

Source: https://docs.rs/lazy-regex/latest/lazy_regex/struct.BytesRegex.html?search=std%3A%3Avec

Executes a regex search starting from a specific offset in the byte slice.

```APIDOC
## pub fn captures_read_at<'h>(&self, locs: &mut CaptureLocations, haystack: &'h [u8], start: usize) -> Option<Match<'h>>

### Description
Similar to captures_read, but begins the search at the specified byte offset. This respects context-sensitive assertions like anchors.

### Parameters
- **locs** (&mut CaptureLocations) - Required - A mutable reference to a pre-allocated CaptureLocations object.
- **haystack** (&'h [u8]) - Required - The byte slice to search against.
- **start** (usize) - Required - The byte offset at which to begin the search.

### Panics
- Panics if start >= haystack.len() + 1.

### Returns
- **Option<Match<'h>>** - Returns the overall match if found, otherwise None.
```

--------------------------------

### build(&self) -> Result<Regex, Error>

Source: https://docs.rs/lazy-regex/latest/lazy_regex/struct.BytesRegexBuilder.html

Compiles the configured pattern into a Regex instance.

```APIDOC
## pub fn build(&self) -> Result<Regex, Error>

### Description
Compiles the pattern provided to the builder using the current configuration. Returns an error if the pattern is invalid or exceeds configured size limits.
```

--------------------------------

### captures_at

Source: https://docs.rs/lazy-regex/latest/lazy_regex/struct.BytesRegex.html?search=std%3A%3Avec

Returns the captures for the first match in the haystack starting at the given offset.

```APIDOC
## pub fn captures_at<'h>( &self, haystack: &'h [u8], start: usize, ) -> Option<Captures<'h>>

### Description
Returns the same as `Regex::captures`, but starts the search at the given offset. The significance of the starting point is that it takes the surrounding context into consideration.

### Panics
This panics when `start >= haystack.len() + 1`.
```

--------------------------------

### new(pattern: &str) -> RegexBuilder

Source: https://docs.rs/lazy-regex/latest/lazy_regex/struct.BytesRegexBuilder.html

Creates a new builder instance with default configuration for the specified regex pattern.

```APIDOC
## pub fn new(pattern: &str) -> RegexBuilder

### Description
Creates a new builder with a default configuration for the given pattern. If the pattern is invalid or exceeds size limits, an error occurs during the build phase.

### Parameters
- **pattern** (&str) - Required - The regular expression pattern string.
```

--------------------------------

### Separators at boundaries

Source: https://docs.rs/lazy-regex/latest/lazy_regex/struct.BytesRegex.html?search=

Demonstrates that separators at the start or end of a haystack produce empty substrings.

```rust
use regex::bytes::Regex;

let re = Regex::new(r"0").unwrap();
let hay = b"010";
let got: Vec<&[u8]> = re.split(hay).collect();
assert_eq!(got, vec![&b""[..], &b"1"[..], &b""[..]]);
```

--------------------------------

### pub fn expand(&self, replacement: &str, dst: &mut String)

Source: https://docs.rs/lazy-regex/latest/lazy_regex/struct.Captures.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Expands instances of $ref in a replacement string to the corresponding capture group and writes the result to a buffer.

```APIDOC
## expand(&self, replacement: &str, dst: &mut String)

### Description
Expands all instances of $ref in the replacement string to the corresponding capture group and writes them to the provided dst buffer. Supports both unbraced ($ref) and braced (${ref}) formats for capture references.
```

--------------------------------

### pub fn expand(&self, replacement: &str, dst: &mut String)

Source: https://docs.rs/lazy-regex/latest/lazy_regex/struct.Captures.html?search=std%3A%3Avec

Expands instances of $ref in a replacement string to the corresponding capture group and writes the result to a destination buffer.

```APIDOC
## pub fn expand(&self, replacement: &str, dst: &mut String)

### Description
Expands all instances of $ref in the replacement string to the corresponding capture group and writes them to the dst buffer. Supports both unbraced ($ref) and braced (${ref}) formats.
```

--------------------------------

### Using bytes_regex with Flags

Source: https://docs.rs/lazy-regex/latest/lazy_regex/macro.bytes_regex.html

Example of creating a case-insensitive byte regex using the 'i' flag.

```rust
let case_insensitive_regex = bytes_regex!("^ab+$"i);
assert!(case_insensitive_regex.is_match(b"abB"));
```

--------------------------------

### Get Initialized Lazy Value

Source: https://docs.rs/lazy-regex/latest/lazy_regex/struct.Lazy.html?search=

Retrieves the value if initialized, otherwise returns None.

```rust
use once_cell::sync::Lazy;

let lazy = Lazy::new(|| 92);

assert_eq!(Lazy::get(&lazy), None);
assert_eq!(&*lazy, &92);
assert_eq!(Lazy::get(&lazy), Some(&92));
```

--------------------------------

### pub fn expand(&self, replacement: &str, dst: &mut String)

Source: https://docs.rs/lazy-regex/latest/lazy_regex/struct.Captures.html

Expands capture group references in a replacement string and appends the result to the provided destination buffer.

```APIDOC
## pub fn expand(&self, replacement: &str, dst: &mut String)

### Description
Expands all instances of $ref in the replacement string to the corresponding capture group and writes them to the dst buffer. Supports both unbraced ($ref) and braced (${ref}) formats.

### Parameters
- **replacement** (&str) - The string containing references to capture groups (e.g., $1, ${name}).
- **dst** (&mut String) - The buffer where the expanded string will be written.
```

--------------------------------

### captures_read_at

Source: https://docs.rs/lazy-regex/latest/lazy_regex/struct.Regex.html?search=std%3A%3Avec

Writes capture group offsets into a provided CaptureLocations object, starting at a specific offset.

```APIDOC
## pub fn captures_read_at<'h>(&self, locs: &mut CaptureLocations, haystack: &'h str, start: usize) -> Option<Match<'h>>

### Description
Combines the functionality of captures_read and offset-based searching. It starts the search at the given offset and writes capture offsets into the provided CaptureLocations object.

### Parameters
- **locs** (&mut CaptureLocations) - The storage for capture offsets.
- **haystack** (&str) - The string to search.
- **start** (usize) - The byte offset to begin the search.

### Panics
Panics if start >= haystack.len() + 1 or if the CaptureLocations was not created by this regex.
```

--------------------------------

### Configure Swap Greed Mode

Source: https://docs.rs/lazy-regex/latest/lazy_regex/struct.BytesRegexBuilder.html

Demonstrates enabling swap-greed mode, which inverts the greediness of quantifiers like + and +?.

```rust
use regex::bytes::RegexBuilder;

let re = RegexBuilder::new(r"a+")
    .swap_greed(true)
    .build()
    .unwrap();
assert_eq!(Some(&b"a"[..]), re.find(b"aaa").map(|m| m.as_bytes()));
```

--------------------------------

### captures_read_at

Source: https://docs.rs/lazy-regex/latest/lazy_regex/struct.Regex.html?search=u32+-%3E+bool

Writes capture group offsets into a provided CaptureLocations object, starting at a specific offset.

```APIDOC
## pub fn captures_read_at<'h>(&self, locs: &mut CaptureLocations, haystack: &'h str, start: usize) -> Option<Match<'h>>

### Description
Returns the same as `Regex::captures_read`, but starts the search at the given offset.

### Parameters
- **locs** (&mut CaptureLocations) - The storage for capture offsets.
- **haystack** (&str) - The string to search.
- **start** (usize) - The byte offset to start the search.

### Panics
This panics when `start >= haystack.len() + 1` or if the `CaptureLocations` was not created by this regex.
```

--------------------------------

### Invalid regex compilation failure

Source: https://docs.rs/lazy-regex/latest/src/lazy_regex/lib.rs.html?search=std%3A%3Avec

Example of a regex that fails to compile due to syntax errors.

```rust
let r = regex!("(unclosed");
```

--------------------------------

### pub fn as_str(&self) -> &str

Source: https://docs.rs/lazy-regex/latest/lazy_regex/struct.Regex.html?search=

Returns the original string pattern used to create the regex.

```APIDOC
## pub fn as_str(&self) -> &str

### Description
Returns the original string of this regex.

### Returns
- **&str** - The original regex pattern string.
```

--------------------------------

### Parsing different formats with extract

Source: https://docs.rs/lazy-regex/latest/lazy_regex/struct.Captures.html

Illustrates using extract to handle multiple potential capture patterns in a single iteration.

```rust
use regex::Regex;

let re = Regex::new(r#"id:(?:"([^"]+)"|'([^']+)')"#).unwrap();
let hay = r#"The first is id:"foo" and the second is id:'bar'."#;
let mut ids = vec![];
for (_, [id]) in re.captures_iter(hay).map(|c| c.extract()) {
    ids.push(id);
}
assert_eq!(ids, vec!["foo", "bar"]);
```

--------------------------------

### Define a case-insensitive regex

Source: https://docs.rs/lazy-regex/latest/index.html

Example of defining a regex with a case-insensitive flag using the regex! macro.

```rust
let case_insensitive_regex = regex!("ab*"i);
```

--------------------------------

### Search with the Pattern trait

Source: https://docs.rs/lazy-regex/latest/lazy_regex/struct.Regex.html

Demonstrates how to use the Regex struct to perform pattern matching and retrieve capture locations.

```rust
let re = Regex::new(r"(.)(.)(\w+)").unwrap();
let mut locs = re.capture_locations();
assert!(re.captures_read(&mut locs, "Padron").is_some());
assert_eq!(locs.get(0), Some((0, 6)));
assert_eq!(locs.get(1), Some((0, 1)));
assert_eq!(locs.get(2), Some((1, 2)));
assert_eq!(locs.get(3), Some((2, 6)));
```

--------------------------------

### get_match() -> Match<'h>

Source: https://docs.rs/lazy-regex/latest/lazy_regex/struct.Captures.html

Returns the overall match for the capture, equivalent to calling get(0).

```APIDOC
## pub fn get_match(&self) -> Match<'h>

### Description
Return the overall match for the capture. This returns the match for index 0, equivalent to m.get(0).unwrap().
```

--------------------------------

### Searching with the Pattern trait

Source: https://docs.rs/lazy-regex/latest/lazy_regex/struct.Regex.html

Demonstrates how to use capture locations to perform searches while respecting word boundaries.

```rust
let re = Regex::new(r"\bchew\b").unwrap();
let hay = "eschew";
let mut locs = re.capture_locations();
// We get a match here, but it's probably not intended.
assert!(re.captures_read(&mut locs, &hay[2..]).is_some());
// No match because the  assertions take the context into account.
assert!(re.captures_read_at(&mut locs, hay, 2).is_none());
```

--------------------------------

### is_match_at

Source: https://docs.rs/lazy-regex/latest/lazy_regex/struct.Regex.html?search=std%3A%3Avec

Checks if the regex matches the haystack starting at the specified offset, taking surrounding context into account.

```APIDOC
## pub fn is_match_at(&self, haystack: &str, start: usize) -> bool

### Description
Returns true if the regex matches the haystack starting at the given offset. The search respects surrounding context, meaning anchors like \A only match when start is 0.

### Parameters
- **haystack** (&str) - The string to search.
- **start** (usize) - The byte offset to begin the search.

### Panics
Panics if start >= haystack.len() + 1.
```

--------------------------------

### Searching with the Pattern trait

Source: https://docs.rs/lazy-regex/latest/lazy_regex/struct.Regex.html

Demonstrates using Regex with standard library string methods. Requires the 'pattern' Cargo feature and nightly Rust.

```rust
use regex::Regex;

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

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

--------------------------------

### shortest_match_at

Source: https://docs.rs/lazy-regex/latest/lazy_regex/struct.BytesRegex.html?search=std%3A%3Avec

Returns the end byte offset of the first match in the haystack, starting the search at the given offset.

```APIDOC
## pub fn shortest_match_at(&self, haystack: &[u8], start: usize) -> Option<usize>

### Description
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.

### Panics
This panics when `start >= haystack.len() + 1`.
```

--------------------------------

### Build a multiline regex

Source: https://docs.rs/lazy-regex/latest/src/lazy_regex/lib.rs.html?search=std%3A%3Avec

Shows the use of the verbose multiline syntax for complex regexes.

```rust
# use lazy_regex::regex;
let r = regex!(r"(?x)
    (?P<name>\w+)
    -
    (?P<version>[0-9.]+)
");
assert_eq!(r.find("This is lazy_regex-2.2!").unwrap().as_str(), "lazy_regex-2.2");
```

--------------------------------

### Replace limited matches with replacen

Source: https://docs.rs/lazy-regex/latest/lazy_regex/struct.BytesRegex.html?search=

Example of using replacen to limit the number of replacements performed on the haystack.

```rust
use regex::bytes::Regex;

let re = Regex::new(r"(?m)^(\S+)[\s--\r\n]+(\S+)$").unwrap();
let hay = b"
Greetings  1973
Wild\t1973
BornToRun\t\t\t\t1975
Darkness                    1978
TheRiver 1980
";
let new = re.replacen(hay, 2, b"$2 $1");
assert_eq!(new, &b"
1973 Greetings
1973 Wild
BornToRun\t\t\t\t1975
Darkness                    1978
TheRiver 1980
"[..]);
```

--------------------------------

### Configure multi-line mode for BytesRegexBuilder

Source: https://docs.rs/lazy-regex/latest/lazy_regex/struct.BytesRegexBuilder.html

Enables multi-line mode, allowing ^ and $ to match at the beginning and end of lines in addition to the haystack.

```rust
use regex::bytes::RegexBuilder;

let re = RegexBuilder::new(r"^foo$")
    .multi_line(true)
    .build()
    .unwrap();
assert_eq!(Some(1..4), re.find(b"\nfoo\n").map(|m| m.range()));
```

--------------------------------

### Configure Ignore Whitespace (Verbose Mode)

Source: https://docs.rs/lazy-regex/latest/lazy_regex/struct.BytesRegexBuilder.html

Shows how to enable verbose mode to allow whitespace and comments within the regex pattern for better readability.

```rust
use regex::bytes::RegexBuilder;

let pat = r"
    \b
    (?<first>\p{Uppercase}\w*)  # always start with uppercase letter
    [\s--\n]+                   # whitespace should separate names
    (?: # middle name can be an initial!
        (?:(?<initial>\p{Uppercase})\.|(?<middle>\p{Uppercase}\w*))
        [\s--\n]+
    )?
    (?<last>\p{Uppercase}\w*)
    \b
";
let re = RegexBuilder::new(pat)
    .ignore_whitespace(true)
    .build()
    .unwrap();

let caps = re.captures(b"Harry Potter").unwrap();
assert_eq!(&b"Harry"[..], &caps["first"]);
assert_eq!(&b"Potter"[..], &caps["last"]);

let caps = re.captures(b"Harry J. Potter").unwrap();
assert_eq!(&b"Harry"[..], &caps["first"]);
// Since a middle name/initial isn't required for an overall match,
// we can't assume that 'initial' or 'middle' will be populated!
assert_eq!(
    Some(&b"J"[..]),
    caps.name("initial").map(|m| m.as_bytes()),
);
assert_eq!(None, caps.name("middle").map(|m| m.as_bytes()));
assert_eq!(&b"Potter"[..], &caps["last"]);

let caps = re.captures(b"Harry James Potter").unwrap();
assert_eq!(&b"Harry"[..], &caps["first"]);
// Since a middle name/initial isn't required for an overall match,
// we can't assume that 'initial' or 'middle' will be populated!
assert_eq!(None, caps.name("initial").map(|m| m.as_bytes()));
assert_eq!(
    Some(&b"James"[..]),
    caps.name("middle").map(|m| m.as_bytes()),
);
assert_eq!(&b"Potter"[..], &caps["last"]);
```

--------------------------------

### is_match_at

Source: https://docs.rs/lazy-regex/latest/lazy_regex/struct.Regex.html?search=u32+-%3E+bool

Returns true if the regex matches the haystack starting at the specified offset, taking surrounding context into account.

```APIDOC
## pub fn is_match_at(&self, haystack: &str, start: usize) -> bool

### Description
Returns the same as `Regex::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.

### Parameters
- **haystack** (&str) - The string to search.
- **start** (usize) - The byte offset to start the search.

### Panics
This panics when `start >= haystack.len() + 1`.
```

--------------------------------

### Get Mutable Initialized Lazy Value

Source: https://docs.rs/lazy-regex/latest/lazy_regex/struct.Lazy.html?search=

Retrieves a mutable reference to the value if initialized, otherwise returns None.

```rust
use once_cell::sync::Lazy;

let mut lazy = Lazy::new(|| 92);

assert_eq!(Lazy::get_mut(&mut lazy), None);
assert_eq!(&*lazy, &92);
assert_eq!(Lazy::get_mut(&mut lazy), Some(&mut 92));
```

--------------------------------

### Configure multi-line mode with RegexBuilder

Source: https://docs.rs/lazy-regex/latest/lazy_regex/struct.RegexBuilder.html

Enables multi-line mode where ^ and $ match at the beginning and end of lines.

```rust
use regex::RegexBuilder;

let re = RegexBuilder::new(r"^foo$")
    .multi_line(true)
    .build()
    .unwrap();
assert_eq!(Some(1..4), re.find("
foo
").map(|m| m.range()));
```

--------------------------------

### Get total number of capture groups

Source: https://docs.rs/lazy-regex/latest/lazy_regex/struct.Captures.html

Returns the total count of capture groups, which is always greater than zero.

```rust
use regex::Regex;

let re = Regex::new(r"(\w)(\d)?(\w)").unwrap();
let caps = re.captures("AZ").unwrap();
assert_eq!(caps.len(), 4);
```

--------------------------------

### RegexBuilder::build

Source: https://docs.rs/lazy-regex/latest/lazy_regex/struct.RegexBuilder.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Compiles the configured pattern into a Regex object.

```APIDOC
## pub fn build(&self) -> Result<Regex, Error>

### Description
Compiles the pattern provided to the builder with the current configuration. Returns an error if the pattern is invalid or if size limits are exceeded.
```
Tokens:
Raw