Arc<Mutex>

Guides

Rust walkthroughs

ā† Back to all guides

How does nom::bytes::complete::take_until differ from take_while for parsing delimited content?

take_until consumes input until it finds a specific delimiter pattern, returning everything before that delimiter, while take_while consumes input as long as each character satisfies a predicate function, stopping at the first character that fails the predicate. The fundamental difference is that take_until searches for a pattern to stop at, whereas take_while tests each character individually against a conditionā€”making them suited for different parsing scenarios: take_until for delimiter-based boundaries like "take everything until -->" and take_while for character-class boundaries like "take all digits."

Basic take_while Behavior

use nom::bytes::complete::take_while;
use nom::IResult;
 
fn take_while_example() {
    // take_while consumes characters matching a predicate
    // Stops at first character that doesn't match
    
    // Take while character is a digit
    fn parse_digits(input: &str) -> IResult<&str, &str> {
        take_while(|c: char| c.is_ascii_digit())(input)
    }
    
    assert_eq!(parse_digits("12345abc"), Ok(("abc", "12345")));
    // Consumes "12345", stops at 'a'
    
    assert_eq!(parse_digits("abc"), Ok(("abc", "")));
    // No digits, consumes nothing
    
    assert_eq!(parse_digits("12345"), Ok(("", "12345")));
    // All characters match, consumes entire input
    
    // take_while tests each character individually
    // Predicate: |c: char| c.is_ascii_digit()
    // Applied to each character until one returns false
}

take_while applies a predicate to each character, consuming until the predicate returns false.

Basic take_until Behavior

use nom::bytes::complete::take_until;
use nom::IResult;
 
fn take_until_example() {
    // take_until consumes input until finding a pattern
    // The pattern itself is NOT consumed
    
    fn until_end_tag(input: &str) -> IResult<&str, &str> {
        take_until("</tag>")(input)
    }
    
    assert_eq!(
        until_end_tag("content</tag>rest"),
        Ok(("</tag>rest", "content"))
    );
    // Consumes "content", stops at "</tag>"
    // The "</tag>" remains in input
    
    assert_eq!(
        until_end_tag("hello world</tag>"),
        Ok(("</tag>", "hello world"))
    );
    
    // If pattern not found, returns an error
    assert!(until_end_tag("no end tag here").is_err());
    
    // take_until looks for a specific pattern
    // Pattern is not included in the result
}

take_until searches for a specific delimiter string, consuming everything before it.

Character-Class vs Delimiter-Based Parsing

use nom::bytes::complete::{take_while, take_until};
use nom::IResult;
 
fn comparison() {
    // take_while: Character-class boundary
    // "Take characters while they satisfy predicate P"
    
    // Example: Parse identifier (alphanumeric + underscore)
    fn parse_identifier(input: &str) -> IResult<&str, &str> {
        take_while(|c: char| c.is_alphanumeric() || c == '_')(input)
    }
    
    assert_eq!(parse_identifier("hello_world123 rest"), Ok((" rest", "hello_world123")));
    // Stops at ' ' because space doesn't match predicate
    
    // take_until: Pattern boundary
    // "Take characters until you see pattern P"
    
    // Example: Parse until semicolon
    fn until_semicolon(input: &str) -> IResult<&str, &str> {
        take_until(";")(input)
    }
    
    assert_eq!(until_semicolon("hello world; rest"), Ok(("; rest", "hello world")));
    // Stops at ";" because that's the delimiter
    
    // Key difference:
    // - take_while: Tests each character individually
    // - take_until: Searches for a multi-character pattern
    
    // For single-character delimiter, both can work but differ:
    // - take_while(|c| c != ';') - predicate-based
    // - take_until(";") - pattern-based
    
    // Pattern-based can search for multi-character delimiters:
    fn until_end_comment(input: &str) -> IResult<&str, &str> {
        take_until("-->")(input)
    }
    
    assert_eq!(until_end_comment("comment text-->rest"), Ok(("-->rest", "comment text")));
    // Can't do this easily with take_while (would need more complex parser)
}

take_while tests individual characters; take_until searches for multi-character patterns.

Parsing XML-like Content

use nom::bytes::complete::take_until;
use nom::sequence::delimited;
use nom::IResult;
 
fn xml_parsing() {
    // take_until is ideal for delimited content
    
    fn parse_tag_content(input: &str) -> IResult<&str, &str> {
        // Take content until closing tag
        take_until("</")(input)
    }
    
    fn parse_element(input: &str) -> IResult<&str, &str> {
        // Full element parser: <tag>content</tag>
        let (input, _) = nom::bytes::complete::tag("<tag>")(input)?;
        let (input, content) = take_until("</tag>")(input)?;
        let (input, _) = nom::bytes::complete::tag("</tag>")(input)?;
        Ok((input, content))
    }
    
    assert_eq!(
        parse_element("<tag>content here</tag>rest"),
        Ok(("rest", "content here"))
    );
    
    // Nested elements would need more complex parsing
    // But take_until works for simple delimited content
    
    // Parsing CDATA sections
    fn parse_cdata(input: &str) -> IResult<&str, &str> {
        let (input, _) = nom::bytes::complete::tag("<![CDATA[")(input)?;
        let (input, content) = take_until("]]>")(input)?;
        let (input, _) = nom::bytes::complete::tag("]]>")(input)?;
        Ok((input, content))
    }
    
    assert_eq!(
        parse_cdata("<![CDATA[some <data> here]]>rest"),
        Ok(("rest", "some <data> here"))
    );
}

take_until excels at parsing content between known delimiters like XML/HTML tags.

Parsing Line-Based Content

use nom::bytes::complete::{take_while, take_until};
use nom::character::complete::newline;
use nom::IResult;
 
fn line_parsing() {
    // take_until for line-based parsing
    
    fn take_line(input: &str) -> IResult<&str, &str> {
        take_until("\n")(input)
    }
    
    // But be careful with last line (no newline)
    // Would fail on last line
    
    // Better approach: take_until with fallback
    fn take_line_safe(input: &str) -> IResult<&str, &str> {
        // Try to take until newline, or take all remaining
        let result = take_until("\n")(input);
        match result {
            Ok((remaining, line)) => {
                let remaining = remaining.strip_prefix("\n").unwrap_or(remaining);
                Ok((remaining, line))
            }
            Err(_) => {
                // No newline found, take all remaining input
                if input.is_empty() {
                    Err(nom::Err::Error(nom::error::Error::new(input, nom::error::ErrorKind::TakeUntil)))
                } else {
                    Ok(("", input))
                }
            }
        }
    }
    
    // Using take_while for whitespace-separated tokens
    fn take_word(input: &str) -> IResult<&str, &str> {
        take_while(|c: char| !c.is_whitespace())(input)
    }
    
    assert_eq!(take_word("hello world"), Ok((" world", "hello")));
    assert_eq!(take_word("hello\nworld"), Ok(("\nworld", "hello")));
    
    // take_while doesn't care what terminates, only that it fails predicate
}

take_until works for line-based parsing; take_while works for character-class boundaries.

Multi-Character Delimiters

use nom::bytes::complete::{take_while, take_until};
use nom::IResult;
 
fn multichar_delimiters() {
    // take_until handles multi-character delimiters
    
    // Parse until end-of-comment marker
    fn parse_comment_content(input: &str) -> IResult<&str, &str> {
        take_until("*/")(input)
    }
    
    assert_eq!(
        parse_comment_content("comment text*/rest"),
        Ok(("*/rest", "comment text"))
    );
    
    // Cannot easily do this with take_while
    // Would need to check for "*/" pattern, not single character
    
    // Common delimiters:
    fn until_close_brace(input: &str) -> IResult<&str, &str> {
        take_until("}")(input)
    }
    
    fn until_end_string(input: &str) -> IResult<&str, &str> {
        take_until("\"")(input)
    }
    
    fn until_end_tag(input: &str) -> IResult<&str, &str> {
        take_until("</")(input)
    }
    
    fn until_eof_marker(input: &str) -> IResult<&str, &str> {
        take_until("\x00")(input)  // Null byte delimiter
    }
    
    // Multi-character delimiter example:
    fn parse_http_headers(input: &str) -> IResult<&str, &str> {
        // Headers end with double CRLF
        take_until("\r\n\r\n")(input)
    }
    
    assert_eq!(
        parse_http_headers("Content-Type: text/html\r\nContent-Length: 42\r\n\r\nbody"),
        Ok(("\r\n\r\nbody", "Content-Type: text/html\r\nContent-Length: 42"))
    );
}

take_until naturally handles multi-character delimiters; take_while cannot.

Predicate Flexibility

use nom::bytes::complete::take_while;
use nom::IResult;
 
fn predicate_flexibility() {
    // take_while has flexible predicates
    
    // Complex character class
    fn parse_hex_number(input: &str) -> IResult<&str, &str> {
        take_while(|c: char| c.is_ascii_hexdigit())(input)
    }
    
    assert_eq!(parse_hex_number("1a2b3cxyz"), Ok(("xyz", "1a2b3c")));
    
    // Custom character class
    fn parse_base64_chars(input: &str) -> IResult<&str, &str> {
        take_while(|c: char| {
            c.is_ascii_alphanumeric() || c == '+' || c == '/' || c == '='
        })(input)
    }
    
    // Unicode-aware predicate
    fn parse_unicode_alpha(input: &str) -> IResult<&str, &str> {
        take_while(|c: char| c.is_alphabetic())(input)
    }
    
    assert_eq!(parse_unicode_alpha("hƩllo123"), Ok(("123", "hƩllo")));
    
    // Negated condition
    fn take_until_space(input: &str) -> IResult<&str, &str> {
        take_while(|c: char| !c.is_whitespace())(input)
    }
    
    assert_eq!(take_until_space("hello world"), Ok((" world", "hello")));
    
    // This is similar to take_until for single-char delimiters
    // But uses predicate instead of pattern matching
}

take_while supports complex predicates that can't be expressed as simple patterns.

Performance Characteristics

use nom::bytes::complete::{take_while, take_until};
use nom::IResult;
 
fn performance() {
    // take_while: O(n) where n is length matched
    // - Tests each character
    // - Stops at first failure
    
    // take_until: O(n*m) where n is position of delimiter
    // - Searches for pattern at each position
    // - m is pattern length (often small)
    
    // For single-character delimiters:
    // - take_until(";") might be faster (optimized)
    // - take_while(|c| c != ';') tests each character
    
    // For multi-character delimiters:
    // - take_until is necessary
    // - take_while would need complex state
    
    // Example where take_while is more natural:
    fn parse_identifier(input: &str) -> IResult<&str, &str> {
        take_while(|c: char| c.is_alphanumeric() || c == '_')(input)
    }
    
    // This is O(identifier_length)
    
    // Example where take_until is more natural:
    fn parse_string_content(input: &str) -> IResult<&str, &str> {
        take_until("\"")(input)
    }
    
    // This is O(string_length) with pattern search
    
    // In practice, both are fast for typical input sizes
    // Choose based on semantics, not micro-optimization
}

Both have similar performance for typical inputs; choose based on semantics.

Composing with Other Parsers

use nom::bytes::complete::{take_while, take_until, tag};
use nom::sequence::{preceded, terminated};
use nom::IResult;
 
fn composition() {
    // take_until often used with tag to consume delimiter
    
    // Parse until delimiter, then consume delimiter
    fn parse_until_end(input: &str) -> IResult<&str, &str> {
        terminated(take_until("-->"), tag("-->"))(input)
    }
    
    assert_eq!(parse_until_end("content-->rest"), Ok(("rest", "content")));
    
    // Parse delimiter, then until next delimiter
    fn parse_between_markers(input: &str) -> IResult<&str, &str> {
        preceded(tag("["), take_until("]"))(input)
    }
    
    assert_eq!(parse_between_markers("[content]rest"), Ok(("]rest", "content")));
    
    // take_while often used with other character parsers
    
    // Skip whitespace then take word
    fn parse_token(input: &str) -> IResult<&str, &str> {
        let (input, _) = nom::character::complete::space0(input)?;
        take_while(|c: char| c.is_alphanumeric())(input)
    }
    
    // Combined approach for complex parsing
    fn parse_key_value(input: &str) -> IResult<&str, (&str, &str)> {
        // Key: take while valid key char
        let (input, key) = take_while(|c: char| c.is_alphanumeric() || c == '_')(input)?;
        // Skip =
        let (input, _) = tag("=")(input)?;
        // Value: take until end of line
        let (input, value) = take_until("\n")(input).unwrap_or((input, input));
        Ok((input, (key, value)))
    }
    
    assert_eq!(parse_key_value("name=value\nrest"), Ok(("\nrest", ("name", "value"))));
}

take_until pairs naturally with tag to consume delimiters; take_while pairs with character predicates.

Error Handling Differences

use nom::bytes::complete::{take_while, take_until};
use nom::error::{Error, ErrorKind};
use nom::IResult;
 
fn error_handling() {
    // take_while never fails (can return empty string)
    fn parse_digits(input: &str) -> IResult<&str, &str> {
        take_while(|c: char| c.is_ascii_digit())(input)
    }
    
    // Always succeeds, possibly with empty match
    assert_eq!(parse_digits("abc"), Ok(("abc", "")));
    assert_eq!(parse_digits(""), Ok(("", "")));
    
    // take_until fails if pattern not found
    fn until_end(input: &str) -> IResult<&str, &str> {
        take_until("END")(input)
    }
    
    // Fails when pattern not present
    let result = until_end("no end marker here");
    assert!(result.is_err());
    
    match result {
        Err(nom::Err::Error(e)) => {
            assert_eq!(e.code, ErrorKind::TakeUntil);
        }
        _ => panic!("Expected error"),
    }
    
    // Error handling pattern
    fn safe_until_end(input: &str) -> IResult<&str, &str> {
        take_until("END")(input).or(Ok((input, input)))
    }
    
    // This returns all input if pattern not found
    
    // take_while never needs this pattern
    // It always succeeds (with empty string if nothing matches)
}

take_while always succeeds (possibly returning empty); take_until fails if pattern not found.

Practical Parsing Example

use nom::bytes::complete::{take_while, take_until, tag};
use nom::sequence::preceded;
use nom::IResult;
 
fn practical_example() {
    // Parse a simple configuration format
    // Format: key=value # comment
    
    #[derive(Debug)]
    struct ConfigEntry {
        key: String,
        value: String,
        comment: Option<String>,
    }
    
    fn parse_key(input: &str) -> IResult<&str, &str> {
        // Key: alphanumeric characters
        take_while(|c: char| c.is_alphanumeric() || c == '_')(input)
    }
    
    fn parse_value(input: &str) -> IResult<&str, &str> {
        // Value: until comment or end of line
        // First try to find comment marker
        if input.contains('#') {
            take_until("#")(input)
        } else if input.contains('\n') {
            take_until("\n")(input)
        } else {
            Ok(("", input.trim()))
        }
    }
    
    fn parse_comment(input: &str) -> IResult<&str, &str> {
        // Comment: after # until end of line
        preceded(tag("#"), take_until("\n"))(input).or(Ok(("", input)))
    }
    
    fn parse_entry(input: &str) -> IResult<&str, ConfigEntry> {
        let (input, key) = parse_key(input)?;
        let (input, _) = tag("=")(input)?;
        let (input, value) = parse_value(input)?;
        let (input, _) = tag("#")(input).unwrap_or((input, ""));
        let (input, comment) = parse_comment(input).unwrap_or((input, ""));
        
        Ok((input, ConfigEntry {
            key: key.trim().to_string(),
            value: value.trim().to_string(),
            comment: if comment.is_empty() { None } else { Some(comment.trim().to_string()) },
        }))
    }
    
    // Combining take_while (for key) and take_until (for delimiter)
}

Real-world parsers often combine both functions based on their strengths.

Comparison Summary

fn summary() {
    // take_while: Character-by-character predicate testing
    // - Tests each character against predicate
    // - Stops when predicate returns false
    // - Never fails (can return empty)
    // - Good for: character classes, identifiers, numbers
    // - Cannot handle multi-character boundaries
    
    // take_until: Pattern-based boundary detection
    // - Searches for specific delimiter pattern
    // - Stops before delimiter (delimiter not consumed)
    // - Fails if pattern not found
    // - Good for: delimited content, strings, comments
    // - Handles multi-character delimiters naturally
    
    // Example showing both:
    use nom::bytes::complete::{take_while, take_until};
    
    // Parse a string literal (simplified)
    fn parse_string(input: &str) -> IResult<&str, &str> {
        // Skip opening quote
        let (input, _) = tag("\"")(input)?;
        // Take until closing quote
        let (input, content) = take_until("\"")(input)?;
        // Skip closing quote
        let (input, _) = tag("\"")(input)?;
        Ok((input, content))
    }
    
    // Parse an identifier
    fn parse_ident(input: &str) -> IResult<&str, &str> {
        take_while(|c: char| c.is_alphanumeric() || c == '_')(input)
    }
    
    // String uses take_until (specific delimiter)
    // Identifier uses take_while (character class)
}

Choose take_while for character-class boundaries, take_until for pattern-based boundaries.

Synthesis

Core difference:

// take_while: Predicate-based, character by character
take_while(|c| c.is_digit(10))("12345abc")
// Result: ("abc", "12345")
// Tests each char against predicate
 
// take_until: Pattern-based, search for delimiter
take_until("-->")("content-->rest")
// Result: ("-->rest", "content")
// Searches for delimiter pattern

When to use each:

Scenario Best choice Reason
Alphanumeric identifier take_while Character class boundary
Until closing tag take_until Multi-char delimiter
Until newline Either (context-dependent) Single char, but take_until is clearer
Until specific keyword take_until Pattern matching needed
Whitespace skipping take_while Character class
Until end comment */ take_until Multi-char delimiter
Hex digits take_while Character class predicate

Key insight: take_until and take_while solve different parsing problemsā€”take_until is for when you know the exact delimiter pattern that marks the end of content (like parsing until --> or </tag>), while take_while is for when the boundary is defined by a character class (like parsing identifiers as alphanumeric characters until a space or punctuation). take_until fails when the pattern isn't found, making it useful for required delimiters; take_while always succeeds (returning an empty string if nothing matches), making it useful for optional content. For single-character boundaries, both can workā€”take_while(|c| c != ';') and take_until(";") achieve similar resultsā€”but take_until is often clearer when you're conceptually "searching for a delimiter" rather than "accepting characters that aren't something." Use take_until for delimiter-based content (strings, comments, XML/HTML, protocols); use take_while for character-class content (identifiers, numbers, whitespace).