Capture Group Interpolation: Code Companion¶

/// Interpolate capture references in `replacement` and write the interpolation
/// result to `dst`. References in `replacement` take the form of $N or $name,
/// where `N` is a capture group index and `name` is a capture group name.
#[inline]
pub fn interpolate<A, N>(
    mut replacement: &[u8],      // Mutable slice - will be narrowed as we parse
    mut append: A,               // Closure: writes captured text given an index
    mut name_to_index: N,        // Closure: resolves named groups to indices
    dst: &mut Vec<u8>,           // Output buffer, caller-controlled
) where
    A: FnMut(usize, &mut Vec<u8>),        // May mutate state between calls
    N: FnMut(&str) -> Option<usize>,      // Returns None for unknown names
{
    // ... implementation
}

while !replacement.is_empty() {
    match memchr(b'$', replacement) {
        None => break,  // No more $ characters, exit loop
        Some(i) => {
            // Copy literal text before the $ to output
            dst.extend(&replacement[..i]);
            // Narrow slice to start at the $
            replacement = &replacement[i..];
        }
    }

    // ... handle the $ reference ...
}
// After loop: append any remaining literal text
dst.extend(replacement);

// Check if this is an escaped dollar sign ($$)
if replacement.get(1).map_or(false, |&b| b == b'$') {
    dst.push(b'$');           // Output single literal $
    replacement = &replacement[2..];  // Skip both $ characters
    continue;                  // Restart loop to find next $
}

/// Represents a parsed capture reference with its position.
/// The lifetime 'a ties this to the input slice for zero-copy parsing.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
struct CaptureRef<'a> {
    cap: Ref<'a>,    // The actual reference (number or name)
    end: usize,      // Byte position immediately after the reference
}

/// A reference to a capture group - either by index or by name.
/// e.g., `$2`, `$foo`, `${foo}`.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
enum Ref<'a> {
    Named(&'a str),  // Borrows from input - no allocation
    Number(usize),   // Self-contained, no borrowing needed
}

impl<'a> From<&'a str> for Ref<'a> {
    #[inline]
    fn from(x: &'a str) -> Ref<'a> {
        Ref::Named(x)  // Lifetime flows from input to output
    }
}

impl From<usize> for Ref<'static> {
    #[inline]
    fn from(x: usize) -> Ref<'static> {
        Ref::Number(x)  // 'static because numbers don't borrow
    }
}

// Test macro exploiting the From implementations
macro_rules! c {
    ($name_or_number:expr, $pos:expr) => {
        CaptureRef { cap: $name_or_number.into(), end: $pos }
    };
}

// Usage in tests:
// c!("foo", 4)  -> CaptureRef with Named("foo")
// c!(5, 2)      -> CaptureRef with Number(5)

#[inline]
fn find_cap_ref(replacement: &[u8]) -> Option<CaptureRef<'_>> {
    let mut i = 0;
    // Must have at least $ and one more character
    if replacement.len() <= 1 || replacement[0] != b'$' {
        return None;
    }

    let mut brace = false;
    i += 1;  // Skip past $

    // Check for braced form: ${...}
    if replacement[i] == b'{' {
        brace = true;
        i += 1;
    }

    // Scan valid identifier characters
    let mut cap_end = i;
    while replacement.get(cap_end).map_or(false, is_valid_cap_letter) {
        cap_end += 1;
    }

    // Must have at least one valid character
    if cap_end == i {
        return None;
    }

    // Safe because is_valid_cap_letter only accepts ASCII
    let cap = std::str::from_utf8(&replacement[i..cap_end])
        .expect("valid UTF-8 capture name");

    // Braced form requires closing brace
    if brace {
        if !replacement.get(cap_end).map_or(false, |&b| b == b'}') {
            return None;
        }
        cap_end += 1;
    }

    // Determine if it's a number or a name
    Some(CaptureRef {
        cap: match cap.parse::<u32>() {
            Ok(i) => Ref::Number(i as usize),
            Err(_) => Ref::Named(cap),
        },
        end: cap_end,
    })
}

/// Returns true if and only if the given byte is allowed in a capture name.
#[inline]
fn is_valid_cap_letter(b: &u8) -> bool {
    match *b {
        b'0'..=b'9' | b'a'..=b'z' | b'A'..=b'Z' | b'_' => true,
        _ => false,
    }
}

// In find_cap_ref, after extracting the identifier:
Some(CaptureRef {
    cap: match cap.parse::<u32>() {
        Ok(i) => Ref::Number(i as usize),  // "123" -> Number(123)
        Err(_) => Ref::Named(cap),          // "foo" or "42a" -> Named
    },
    end: cap_end,
})

struct CaptureRef<'a> { cap: Ref<'a>, end: usize }
enum Ref<'a> { Named(&'a str), Number(usize) }

pub fn interpolate<A, N>(replacement: &[u8], append: A, name_to_index: N, dst: &mut Vec<u8>)
where
    A: FnMut(usize, &mut Vec<u8>),
    N: FnMut(&str) -> Option<usize>;

fn find_cap_ref(replacement: &[u8]) -> Option<CaptureRef<'_>>;
fn is_valid_cap_letter(b: &u8) -> bool;