Struct Extractor 

pub struct Extractor { /* private fields */ }

The main IP address extractor.

An Extractor scans byte slices for IPv4 and/or IPv6 addresses, applying configurable filters to include or exclude certain address classes (private, loopback, broadcast).

Extractors are best created via ExtractorBuilder and are designed to be reused across many calls to find_iter for maximum efficiency.

Bytes vs. Strings

This extractor works directly on byte slices rather than strings. This avoids UTF-8 validation overhead and enables zero-copy scanning of very large inputs.

Performance

The extractor uses a compile-time DFA (Deterministic Finite Automaton) for O(n) scanning with minimal overhead. See the crate-level documentation for throughput benchmarks.

Implementations

impl Extractor

pub fn find_iter<'a>( &'a self, haystack: &'a [u8], ) -> impl Iterator<Item = Range<usize>> + 'a

Find all IP addresses in a byte slice.

Returns an iterator of byte ranges [start, end) pointing to each IP address found. Ranges are guaranteed to be valid indices into haystack.

For richer match information (IP version, direct string access), use match_iter instead.

Example

use ip_extract::ExtractorBuilder;

let extractor = ExtractorBuilder::new().build()?;
let data = b"Connecting from 192.168.1.1";

for range in extractor.find_iter(data) {
    let ip = std::str::from_utf8(&data[range])?;
    println!("Found: {ip}");
}

pub fn match_iter<'a>( &'a self, haystack: &'a [u8], ) -> impl Iterator<Item = IpMatch<'a>> + 'a

Find all IP addresses in a byte slice, yielding rich IpMatch values.

Like find_iter, but each match carries the matched bytes, their position in the haystack, and the IP version — eliminating the need to re-parse or guess the version at the call site.

Example

use ip_extract::ExtractorBuilder;

let extractor = ExtractorBuilder::new().build()?;
let data = b"Log: 192.168.1.1 sent request to 2001:db8::1";

for m in extractor.match_iter(data) {
    println!("{} ({:?})", m.as_matched_str(), m.kind());
}

pub fn replace_iter<W, F>( &self, haystack: &[u8], wtr: &mut W, replacer: F, ) -> Result<usize>

where W: Write, F: FnMut(&IpMatch<'_>, &mut W) -> Result<()>,

Scan haystack for IP addresses, writing non-IP text to wtr and calling replacer for each match.

This is the efficient single-pass decoration primitive: the caller never needs to track byte offsets or manage gap writes. The replacer writes the substitution directly to wtr — no intermediate allocation.

Returns the number of IP addresses found.

Errors

Returns the first io::Error from either a gap write or the replacer.

Example

use ip_extract::ExtractorBuilder;
use std::io::Write;

let extractor = ExtractorBuilder::new().build()?;
let data = b"Server 192.168.1.1 is up";
let mut out = Vec::new();

let count = extractor.replace_iter(data, &mut out, |m, w| {
    write!(w, "[{}]", m.as_matched_str())
})?;

assert_eq!(count, 1);
assert_eq!(out, b"Server [192.168.1.1] is up");

Trait Implementations

impl Debug for Extractor

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.