Mention difference between is_not and take_until in their respective docs.
SebastianJL opened this issue · 0 comments
SebastianJL commented
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>