Borrowed Strings: API Designs That Cut 94% of Allocations

// After: take a &str — zero extra allocations for callers who already have a &str  
pub fn validate_email(email: &str) -> bool {  
    email.contains('@') &&            // yep, still naive; we’re only fixing the ownership story  
    email.contains('.') &&  
    !email.is_empty()  
}  

// Usage (no allocation)  
let valid = validate_email(user_input);             // `&str` all the way, cheap + cheerful  

// If you want to be extra friendly to callers, accept anything “stringy”  
pub fn validate_email_flexible<S: AsRef<str>>(email: S) -> bool {  
    let s = email.as_ref();            // borrow without allocating  
    s.contains('@') && s.contains('.') && !s.is_empty()  
}  

// Works with &str, String, Cow<'_, str>, etc., all without new allocations:  
let a = validate_email_flexible(user_input);  
let b = validate_email_flexible(user_owned_string);

// after: same logic, kinder to callers — borrows &str so no extra allocations anywhere  
pub fn validate_email(email: &str) -> bool {  
    // still a deliberately naive check; we’re only fixing ownership here, not spec-grade validation  
    email.contains('@') &&            // quick sanity: needs an @  
    email.contains('.') &&            // and a dot somewhere (yeah, simplistic)  
    !email.is_empty()                 // obviously can’t be empty  
}  

// usage: all zero-copy borrows — no new Strings created just to call the function  
let valid = validate_email(&user_input);        // borrowing from an existing &str  
let valid = validate_email("test@example.com"); // string literal is already &str  
let valid = validate_email(&owned_string);      // borrow from a String without allocating

// generic + friendly: accept anything “stringy”, return a fresh owned String  
pub fn normalize_email<S: AsRef<str>>(email: S) -> String {  
    email  
        .as_ref()        // borrow without allocating (works for &str, String, etc.)  
        .trim()          // shave off accidental spaces/newlines at the edges  
        .to_lowercase()  // emails are case-insensitive (local-part case rules aside)  
}  

// works with everything — all callers compile down to the same borrow-then-own flow  
let s1 = normalize_email("Test@Example.com");     // &str literal  
let s2 = normalize_email(&owned_string);          // borrow from String  
let s3 = normalize_email(String::from("test"));   // move a String in  
let s4 = normalize_email(Box::new("test"));       // even boxed &str via AsRef<str>

use std::borrow::Cow; // borrow-or-own smart pointer — perfect for “allocate only if we must”  

pub fn sanitize_html<'a>(input: &'a str) -> Cow<'a, str> {  
    // quick escape hatch: if nothing needs escaping, don’t touch it  
    if needs_escaping(input) {  
        // we *might* double the size (every char → entity), so start roomy and avoid re-allocs  
        let mut output = String::with_capacity(input.len() * 2);  

        // walk the input once; swap problem chars with their HTML entities  
        for c in input.chars() {  
            match c {  
                '<' => output.push_str("&lt;"),   // less-than → &lt;  
                '>' => output.push_str("&gt;"),   // greater-than → &gt;  
                '&' => output.push_str("&amp;"),  // ampersand → &amp;  
                _ => output.push(c),              // everything else passes through  
            }  
        }  

        Cow::Owned(output) // we modified it, so return an owned String  
    } else {  
        // best case: zero-copy — no allocation, no work  
        Cow::Borrowed(input)  
    }  
}

// goal: intern strings => one global copy; return &'static str; yes, we leak by design.  

use std::collections::HashSet;      // set for fast “seen?” checks  
use once_cell::sync::Lazy;          // lazy init for globals  
use std::sync::Mutex;               // simple thread safety  

// global pool of canonical &'static str  
static STRING_POOL: Lazy<Mutex<HashSet<&'static str>>> =  
    Lazy::new(|| Mutex::new(HashSet::new()));  

/// If we've seen `s`, return the same &'static str; else leak a new one and store it.  
/// tradeoff: tiny leaks for stable identity + speed; fine for small vocabularies.  
pub fn intern(s: &str) -> &'static str {  
    let mut pool = STRING_POOL.lock().unwrap();             // grab lock (good enough for demo)  
    if let Some(&interned) = pool.get(s) {                  // already there?  
        return interned;                                    // yup — reuse pointer  
    }  
    let leaked: &'static str = Box::leak(                   // not found: make it immortal…  
        s.to_string().into_boxed_str()                      // own it, box it,  
    );                                                      // …and never free it (on purpose)  
    pool.insert(leaked);                                    // remember for next time  
    leaked                                                  // hand back the canonical ref  
}  

// tiny demo to prove pointer identity  
fn main() {  
    let status1 = intern("active");                         // first insert  
    let status2 = intern("active");                         // reuse same pointer  
    assert!(std::ptr::eq(status1, status2));                // identity holds  
    println!("interned: {status1:?} == {status2:?} ✅");     // quick victory lap  
}

// tiny http request parser, zero-copy-ish and deliberately simple.  
// i’m aiming for "works for basic requests", not full RFC wizardry. breathe. keep it human.  

#[derive(Debug)]                              // we’ll want to print errors without drama  
pub enum ParseError {                         // bare-minimum error shape; good enough for demo  
    Empty,                                    // input was empty (no first line to parse)  
    InvalidRequestLine,                       // method path version not exactly three parts  
    NoHeaderSection,                          // couldn’t find the headers/body separator  
}  

#[derive(Debug)]  
pub struct HttpRequest<'a> {  
    method: &'a str,                          // e.g., "GET" — borrowed from input  
    path: &'a str,                            // e.g., "/index.html" — also a borrow  
    headers: Vec<(&'a str, &'a str)>,         // header name/value pairs, all borrowed  
    body: &'a [u8],                           // body as bytes (don’t assume UTF-8)  
}  

impl<'a> HttpRequest<'a> {  
    /// Parse a raw HTTP request string into borrowed views.  
    pub fn parse(input: &'a str) -> Result<Self, ParseError> {  
        if input.is_empty() {                  // first: do we even have anything?  
            return Err(ParseError::Empty);     // nope — bail early  
        }  

        // find the end of headers: ideally CRLF CRLF, but fall back to LF LF (because… real life)  
        // i started with lines.len math, then remembered: slicing needs *byte* offsets. backtrack!  
        let (head, body_str) = if let Some(idx) = input.find("\r\n\r\n") {  
            // split at CRLFCRLF; body starts *after* that 4-byte separator  
            (&input[..idx], &input[idx + 4 ..]) // header text, body text  
        } else if let Some(idx) = input.find("\n\n") {  
            // okay, some clients just do LF; it happens in toy servers/tests  
            (&input[..idx], &input[idx + 2 ..])  
        } else {  
            // no separator means either no headers or malformed request  
            return Err(ParseError::NoHeaderSection);  
        };  

        // now parse the start-line + headers from `head` (which is the header block)  
        let mut head_lines = head.lines();     // iterate lines safely (CRLF handled by .lines())  

        // request line: METHOD SP PATH SP HTTP/VERSION (we only check len == 3)  
        let first_line = head_lines.next().ok_or(ParseError::Empty)?; // must exist  
        let parts: Vec<&str> = first_line.split_whitespace().collect(); // split by any spaces/tabs  
        if parts.len() != 3 {                  // we’re strict here because ambiguity is pain  
            return Err(ParseError::InvalidRequestLine);  
        }  
        let method = parts[0];                 // borrow directly — zero copies  
        let path   = parts[1];                 // ditto (we’re ignoring the version)  

        // parse headers: "Name: value" per line, preserve borrowing  
        let mut headers = Vec::new();          // store (&str, &str) pairs  
        for line in head_lines {               // walk remaining header lines  
            if line.is_empty() {               // defensive: though we split at blank, tolerate extras  
                continue;                      // skip empties  
            }  
            if let Some(pos) = line.find(':') {// find the first colon: separates name/value  
                let name  = &line[..pos];      // header name (no trim per spec; names are token chars)  
                let value = line[pos + 1 ..].trim(); // header value — trim spaces around  
                headers.push((name, value));   // stash the pair  
            } else {  
                // no colon? meh — ignore malformed line; could also error out if you prefer  
                // (i'm choosing leniency because that’s what you want in a toy parser)  
            }  
        }  

        // body is whatever remains after the separator — as bytes, no assumptions  
        let body = body_str.as_bytes();        // don’t force UTF-8; binary is common  

        Ok(HttpRequest {                      // finally, assemble the borrow-only struct  
            method,                           // "GET" / "POST" etc.  
            path,                             // "/things?x=1"  
            headers,                          // collected pairs  
            body,                             // borrowed bytes  
        })  
    }  
}  

// --- tiny demo, because seeing it work calms the nerves ---  
fn main() {  
    // quick, slightly messy request with LF-only newlines to prove the fallback works  
    let raw = "GET /hello HTTP/1.1\nHost: example.com\nContent-Length: 5\n\nhello";  

    // parse the thing; if it explodes, i want to *see* it  
    let req = HttpRequest::parse(raw).expect("failed to parse");  

    // sanity checks — not exhaustive, just “does this smell right”  
    assert_eq!(req.method, "GET");             // request line captured method  
    assert_eq!(req.path, "/hello");            // and path (we’re ignoring the version on purpose)  
    assert_eq!(req.headers.len(), 2);          // we fed 2 headers  
    assert_eq!(req.body, b"hello");            // body is exactly 5 bytes  

    println!("{req:#?}");                      // take a victory lap  
}

// tiny, opinionated string formatter — collects borrowed pieces (&str) and joins them later  
// idea: pre-compute exact capacity so we allocate only once in `build()`.  
// also: keep it zero-copy on inputs (we just borrow &str), so super lightweight.  

#[derive(Debug)]                              // because printing during debugging is therapy  
pub struct StringFormatter <'a> {  
    parts: Vec<&'a str>,                      // stash of string slices; we don't own them  
    separator: &'a str,                       // the glue between parts (", ", " | ", etc.)  
}  

impl<'a> StringFormatter<'a> {  
    /// make a new formatter with a chosen separator  
    pub fn new(separator: &'a str) -> Self {  
        Self {  
            parts: Vec::new(),                // start empty; we'll push as we go  
            separator,                        // remember the glue  
        }  
    }  

    /// add a new piece; returns &mut Self for chain-y vibes  
    pub fn add(&mut self, part: &'a str) -> &mut Self {  
        self.parts.push(part);                // just store the borrow; no allocation here  
        self                                   // allow .add(...).add(...).add(...)  
    }  

    /// convenience: add only if non-empty (sometimes you don't want stray separators)  
    pub fn add_if_nonempty(&mut self, part: &'a str) -> &mut Self {  
        if !part.is_empty() {                 // tiny guard to avoid "" in the output  
            self.parts.push(part);            // same as add, but conditional  
        }  
        self  
    }  

    /// build the final String with exactly one allocation (that’s the whole flex)  
    pub fn build(&self) -> String {  
        // edge case time: if there are no parts, this should just be empty. no drama.  
        if self.parts.is_empty() {            // avoid underflow on (len - 1) below  
            return String::new();             // zero parts → empty string  
        }  

        // how many separators do we need? between N parts, there are N-1 separators  
        let sep_count = self.parts.len() - 1; // safe because we handled len==0 above  

        // sum of all part lengths (no allocs yet) + separators  
        let parts_len: usize = self.parts  
            .iter()  
            .map(|s| s.len())                 // just lengths, please  
            .sum();  

        let total_len = parts_len + sep_count * self.separator.len(); // exact capacity  

        // pre-allocate so pushes don't reallocate; we're being a bit smug, yes  
        let mut result = String::with_capacity(total_len);  

        // now the simple, boring join loop (boring is good)  
        for (i, part) in self.parts.iter().enumerate() {  
            if i > 0 {                        // after the first item, insert glue  
                result.push_str(self.separator);  
            }  
            result.push_str(part);            // tack on the actual piece  
        }  

        debug_assert_eq!(result.len(), total_len, "capacity math went sideways"); // sanity  

        result                                 // and we’re done — one allocation 🎯  
    }  

    /// optional: consume builder and produce the string (ergonomic in some flows)  
    pub fn into_string(self) -> String {  
        self.build()                           // same implementation, just different signature  
    }  
}  

// --- demo time --- because proof beats vibes  
fn main() {  
    // let's assemble a tiny guest list; thoughts: order, commas, and oh,  
    // no trailing separator please (we got you)  
    let mut fmt = StringFormatter::new(", ");  // glue will be ", "  

    fmt.add("Alice")                           // first guest  
       .add("Bob")                             // second  
       .add_if_nonempty("")                    // noop thanks to the guard  
       .add("Charlie");                        // third — chaotic good  

    let result = fmt.build();                  // single allocation for the win  
    assert_eq!(result, "Alice, Bob, Charlie"); // yep  
    println!("{result}");                      // "Alice, Bob, Charlie"  
}

 // 10 allocations per string = 1M allocations  
let mut s = String::new();  
s.push_str(p1); s.push_str(", ");  
s.push_str(p2); s.push_str(", ");  
// ... etc

// goal: read config strings with minimal allocs; borrow when we can.  

use std::collections::HashMap;                 // we stash key/value pairs here  

#[derive(Debug)]  
pub struct Config {  
    data: HashMap<String, String>,             // own the strings; callers just borrow  
}  

impl Config {  
    // meh: always clones — simple but alloc-happy  
    pub fn get_bad(&self, key: &str) -> Option<String> {  
        self.data.get(key).cloned()            // copy-on-read (costly if frequent)  
    }  

    // better: borrow &'str from our owned String  
    pub fn get(&self, key: &str) -> Option<&str> {  
        self.data.get(key).map(|s| s.as_str()) // no alloc; just a view  
    }  

    // pragmatic: borrow value or fall back to a provided default  
    pub fn get_or_default<'a>(&'a self, key: &str, default: &'a str) -> &'a str {  
        self.data.get(key).map(|s| s.as_str()).unwrap_or(default) // still zero alloc  
    }  

    // tiny helper for examples  
    pub fn insert(&mut self, k: impl Into<String>, v: impl Into<String>) {  
        self.data.insert(k.into(), v.into());  // own the data once, up front  
    }  
}  

// quick sanity check — thoughts jump: does borrow survive? yes, tied to &self  
fn main() {  
    let mut cfg = Config { data: HashMap::new() }; // start empty  
    cfg.insert("mode", "release");                 // store owned strings  
    cfg.insert("color", "blue");                   // another one  

    let m = cfg.get("mode").unwrap();              // borrowed &str, no alloc  
    let z = cfg.get_or_default("zone", "us-east"); // fallback path  
    let bad = cfg.get_bad("color").unwrap();       // allocates (by design)  

    assert_eq!(m, "release");                      // borrowed value ok  
    assert_eq!(z, "us-east");                      // default used  
    assert_eq!(bad, "blue");                       // cloned string matches  
    println!("{m}, {z}, {bad}");                   // prints: release, us-east, blue  
}

 fn process(input: &str) -> bool {  
    input.len() > 10  
}

 fn find_domain<'a>(email: &'a str) -> Option<&'a str> {  
    email.split('@').nth(1)  
}

 struct EmailParser<'a> {  
    input: &'a str,  
    domain: Option<&'a str>,  
}  
impl<'a> EmailParser<'a> {  
    fn parse(input: &'a str) -> Self {  
        let domain = input.split('@').nth(1);  
        Self { input, domain }  
    }  
}

 // This doesn't compile - lifetime conflicts  
struct Cache<'a> {  
    data: HashMap<String, &'a str>,  
}  
// Fix: Use String or Cow instead  
struct Cache {  
    data: HashMap<String, String>,  
}

// benchmark owned vs borrowed validation; keep it small, no drama.  
use criterion::{black_box, criterion_group, criterion_main, Criterion};  

fn bench_owned(c: &mut Criterion) {  
    c.bench_function("validate_owned", |b| {  
        let email = String::from("test@example.com"); // owned String we’ll clone per iter  
        b.iter(|| {  
            validate_owned(black_box(email.clone()))   // bench includes clone cost  
        });  
    });  
}  

fn bench_borrowed(c: &mut Criterion) {  
    c.bench_function("validate_borrowed", |b| {  
        let email = "test@example.com";               // &'static str — zero alloc  
        b.iter(|| {  
            validate_borrowed(black_box(email))       // borrow; avoid cloning entirely  
        });  
    });  
}  

// group + entrypoint — Criterion’s standard glue  
criterion_group!(benches, bench_owned, bench_borrowed);  
criterion_main!(benches);  

// --- if you need minimal stubs to compile locally, uncomment below ---  
// fn validate_owned(s: String) -> bool { s.contains('@') }  
// fn validate_borrowed(s: &str) -> bool { s.contains('@') }

 // Bad: Borrowed to death  
fn process<'a, 'b>(  
    s1: &'a str,   
    s2: &'b str,  
) -> Result<&'a str, &'b str> {  
    // Lifetime hell  
}  

// Better: Selectively own  
fn process(s1: &str, s2: &str) -> Result<String, String> {  
    // Clear ownership  
}

 // Bad: Optimizing cold path  
fn rarely_called(s: &str) {  
    // Called once per day  
}  

// Better: Keep simple  
fn rarely_called(s: String) {  
    // Ergonomics over performance  
}

 // Looks fast, allocates


fn get_uppercase(s: &str) -> &str {


    // Can't return &str from to_uppercase!


    // Must allocate


}  

// Honest: Shows allocation


fn get_uppercase(s: &str) -> String {


    s.to_uppercase()  // Explicit allocation


}