Merge pull request #491 from epage/docs

docs: Further clarify APIs

examples/json_iterator.rs

@@ -2,7 +2,7 @@ use std::collections::HashMap;
 
 use winnow::prelude::*;
 use winnow::{
-    ascii::{alphanumeric1 as alphanumeric, escaped, float},
+    ascii::{alphanumeric1 as alphanumeric, float, take_escaped},
     combinator::alt,
     combinator::cut_err,
     combinator::separated,
@@ -216,7 +216,7 @@ fn sp<'a, E: ParserError<&'a str>>(i: &mut &'a str) -> PResult<&'a str, E> {
 }
 
 fn parse_str<'a, E: ParserError<&'a str>>(i: &mut &'a str) -> PResult<&'a str, E> {
-    escaped(alphanumeric, '\\', one_of(['"', 'n', '\\'])).parse_next(i)
+    take_escaped(alphanumeric, '\\', one_of(['"', 'n', '\\'])).parse_next(i)
 }
 
 fn string<'s>(i: &mut &'s str) -> PResult<&'s str> {

src/_topic/language.rs

@@ -136,7 +136,7 @@
 #![doc = include_str!("../../examples/string/parser.rs")]
 //! ```
 //!
-//! See also [`escaped`] and [`escaped_transform`].
+//! See also [`take_escaped`] and [`escaped_transform`].
 //!
 //! ### Integers
 //!
@@ -320,7 +320,7 @@
 #![allow(unused_imports)]
 use crate::ascii::dec_int;
 use crate::ascii::dec_uint;
-use crate::ascii::escaped;
 use crate::ascii::escaped_transform;
 use crate::ascii::float;
 use crate::ascii::hex_uint;
+use crate::ascii::take_escaped;

src/ascii/tests.rs

@@ -646,31 +646,31 @@ mod complete {
       }
     }
 
-    // issue #1336 "escaped hangs if normal parser accepts empty"
+    // issue #1336 "take_escaped hangs if normal parser accepts empty"
     #[test]
-    fn complete_escaped_hang() {
-        // issue #1336 "escaped hangs if normal parser accepts empty"
+    fn complete_take_escaped_hang() {
+        // issue #1336 "take_escaped hangs if normal parser accepts empty"
         fn escaped_string(input: &str) -> IResult<&str, &str> {
             use crate::ascii::alpha0;
             use crate::token::one_of;
-            escaped(alpha0, '\\', one_of(['n'])).parse_peek(input)
+            take_escaped(alpha0, '\\', one_of(['n'])).parse_peek(input)
         }
 
         escaped_string("7").unwrap();
         escaped_string("a7").unwrap();
     }
 
     #[test]
-    fn complete_escaped_hang_1118() {
-        // issue ##1118 escaped does not work with empty string
+    fn complete_take_escaped_hang_1118() {
+        // issue ##1118 take_escaped does not work with empty string
         fn unquote(input: &str) -> IResult<&str, &str> {
             use crate::combinator::delimited;
             use crate::combinator::opt;
             use crate::token::one_of;
 
             delimited(
                 '"',
-                escaped(
+                take_escaped(
                     opt(none_of(['\\', '"'])),
                     '\\',
                     one_of(['\\', '"', 'r', 'n', 't']),
@@ -691,7 +691,7 @@ mod complete {
         use crate::token::one_of;
 
         fn esc(i: &[u8]) -> IResult<&[u8], &[u8]> {
-            escaped(alpha, '\\', one_of(['\"', 'n', '\\'])).parse_peek(i)
+            take_escaped(alpha, '\\', one_of(['\"', 'n', '\\'])).parse_peek(i)
         }
         assert_eq!(esc(&b"abcd;"[..]), Ok((&b";"[..], &b"abcd"[..])));
         assert_eq!(esc(&b"ab\\\"cd;"[..]), Ok((&b";"[..], &b"ab\\\"cd"[..])));
@@ -715,7 +715,7 @@ mod complete {
         );
 
         fn esc2(i: &[u8]) -> IResult<&[u8], &[u8]> {
-            escaped(digit, '\\', one_of(['\"', 'n', '\\'])).parse_peek(i)
+            take_escaped(digit, '\\', one_of(['\"', 'n', '\\'])).parse_peek(i)
         }
         assert_eq!(esc2(&b"12\\nnn34"[..]), Ok((&b"nn34"[..], &b"12\\n"[..])));
     }
@@ -727,7 +727,7 @@ mod complete {
         use crate::token::one_of;
 
         fn esc(i: &str) -> IResult<&str, &str> {
-            escaped(alpha, '\\', one_of(['\"', 'n', '\\'])).parse_peek(i)
+            take_escaped(alpha, '\\', one_of(['\"', 'n', '\\'])).parse_peek(i)
         }
         assert_eq!(esc("abcd;"), Ok((";", "abcd")));
         assert_eq!(esc("ab\\\"cd;"), Ok((";", "ab\\\"cd")));
@@ -748,12 +748,12 @@ mod complete {
         );
 
         fn esc2(i: &str) -> IResult<&str, &str> {
-            escaped(digit, '\\', one_of(['\"', 'n', '\\'])).parse_peek(i)
+            take_escaped(digit, '\\', one_of(['\"', 'n', '\\'])).parse_peek(i)
         }
         assert_eq!(esc2("12\\nnn34"), Ok(("nn34", "12\\n")));
 
         fn esc3(i: &str) -> IResult<&str, &str> {
-            escaped(alpha, '\u{241b}', one_of(['\"', 'n'])).parse_peek(i)
+            take_escaped(alpha, '\u{241b}', one_of(['\"', 'n'])).parse_peek(i)
         }
         assert_eq!(esc3("ab␛ncd;"), Ok((";", "ab␛ncd")));
     }
@@ -762,7 +762,7 @@ mod complete {
     fn test_escaped_error() {
         fn esc(s: &str) -> IResult<&str, &str> {
             use crate::ascii::digit1;
-            escaped(digit1, '\\', one_of(['\"', 'n', '\\'])).parse_peek(s)
+            take_escaped(digit1, '\\', one_of(['\"', 'n', '\\'])).parse_peek(s)
         }
 
         assert_eq!(esc("abcd"), Ok(("abcd", "")));

src/binary/bits/mod.rs

@@ -150,7 +150,7 @@ where
 ///
 /// # Effective Signature
 ///
-/// Assuming you are parsing `&str`:
+/// Assuming you are parsing a `(&[u8], usize)` bit [Stream]:
 /// ```rust
 /// # use winnow::prelude::*;;
 /// # use winnow::error::ContextError;
@@ -268,7 +268,7 @@ where
 ///
 /// # Effective Signature
 ///
-/// Assuming you are parsing `&str`:
+/// Assuming you are parsing a `(&[u8], usize)` bit [Stream]:
 /// ```rust
 /// # use winnow::prelude::*;;
 /// # use winnow::error::ContextError;
@@ -368,7 +368,7 @@ where
 ///
 /// # Effective Signature
 ///
-/// Assuming you are parsing `&str`:
+/// Assuming you are parsing a `(&[u8], usize)` bit [Stream]:
 /// ```rust
 /// # use winnow::prelude::*;;
 /// # use winnow::error::ContextError;