rust-bakery/nom

Mention difference between is_not and take_until in their respective docs.

SebastianJL opened this issue · 0 comments

nom-version: 7.1.2

Hi

First of all, thanks for this great library. I enjoy using it.

This is about the nom docs, not about a feature.

I just sat in front of the docs and it took me like 5 minutes of staring at the respective docs to figure out the difference between take_until and is_not. Yes looking closely at the provided examples eventually made me realize that take_until matches the entire pattern while is_not matches one of the characters in the provided &str.

But I think it would help to add a small note to both to point out the difference and also to make the other version discoverable.

Below I propose how such a change could look. I'll do a pull request myself if I get your thumbs up.

-/// Parse till certain characters are met.
+/// Parse till one of multiple characters is met.
///
/// The parser will return the longest slice till one of the characters of the combinator's argument are met.
///
/// It doesn't consume the matched character.
///
/// It will return a `Err::Incomplete(Needed::new(1))` if the pattern wasn't met.
/// 
+/// # Difference to [nom::bytes::complete::take_until]
+/// While this parser matches any of the provided characters [nom::bytes::complete::take_until]
+/// will only match when the entire pattern is found.
///
/// # Example
/// ```rust
/// # use nom::{Err, error::ErrorKind, Needed, IResult};
/// use nom::bytes::streaming::is_not;
///
/// fn not_space(s: &str) -> IResult<&str, &str> {
///   is_not(" \t\r\n")(s)
/// }
///
/// assert_eq!(not_space("Hello, World!"), Ok((" World!", "Hello,")));
/// assert_eq!(not_space("Sometimes\t"), Ok(("\t", "Sometimes")));
/// assert_eq!(not_space("Nospace"), Err(Err::Incomplete(Needed::new(1))));
/// assert_eq!(not_space(""), Err(Err::Incomplete(Needed::new(1))));
/// ```
pub fn is_not<T, I, Error: ParseError<I>>(arr: T) -> impl FnMut(I) -> IResult<I, I, Error>