### Create New Quoter with Default Settings

Source: https://docs.rs/shlex/1.3.0/shlex/bytes/struct.Quoter.html

Instantiates a new Quoter with default configuration. Use this when you need a Quoter but want to start with the standard settings.

```rust
pub fn new() -> Self
```

--------------------------------

### Normal Behavior with \xa0

Source: https://docs.rs/shlex/1.3.0/src/shlex/quoting_warning.md.html

This example shows the expected behavior when the \xa0 byte is handled correctly, typically resulting in a single error message.

```bash
$ echo -e 'ls a\xa0b' | bash
ls: cannot access 'a'\x24'\240''b': No such file or directory
```

--------------------------------

### Using shlex::bytes::join (Deprecated)

Source: https://docs.rs/shlex/1.3.0/shlex/bytes/fn.join.html

This example demonstrates the usage of the deprecated `shlex::bytes::join` function. It joins byte slices into a single byte string, quoting words if necessary and separating them with spaces. Null bytes are passed through, which is a dangerous behavior leading to its deprecation.

```rust
Equivalent to `Quoter::new().allow_nul(true).join(words).unwrap()`.
```

--------------------------------

### Bash argument list too long example

Source: https://docs.rs/shlex/1.3.0/shlex/quoting_warning/index.html

This example shows a scenario where a shell command might succeed but encounter issues due to an excessively long argument, leading to an 'Argument list too long' error.

```bash
x=$(printf '%010000000d' 0); /bin/echo $x
```

--------------------------------

### ANSI-C Quoting Example in Bash

Source: https://docs.rs/shlex/1.3.0/shlex/quoting_warning/index.html

Shows how ANSI-C quoting in Bash can be used to include escape sequences like hex values and newlines within a string. Note that this quoting style is not universally supported by all shells.

```bash
echo $'A
B'
```

--------------------------------

### Quoter::new

Source: https://docs.rs/shlex/1.3.0/shlex/bytes/struct.Quoter.html

Creates a new `Quoter` instance with default settings. This is the entry point for using the Quoter with standard configurations.

```APIDOC
## Quoter::new

### Description
Create a new `Quoter` with default settings.

### Method
`pub fn new() -> Self`

### Returns
A new `Quoter` instance with default settings.
```

--------------------------------

### Get TypeId of Quoter

Source: https://docs.rs/shlex/1.3.0/shlex/bytes/struct.Quoter.html

Retrieves the `TypeId` of the Quoter type. This is part of the `Any` trait implementation and is used for dynamic type checking.

```rust
fn type_id(&self) -> TypeId
```

--------------------------------

### Bash Argument List Too Long Error

Source: https://docs.rs/shlex/1.3.0/src/shlex/quoting_warning.md.html

Example of a shell command failing with an 'Argument list too long' error due to an excessively long string.

```bash
x=$(printf '%010000000d' 0); /bin/echo $x
bash: /bin/echo: Argument list too long
```

--------------------------------

### Shlex step_by() Method

Source: https://docs.rs/shlex/1.3.0/shlex/bytes/struct.Shlex.html

Creates a new iterator that steps through the Shlex iterator at a specified interval.

```rust
fn step_by(self, step: usize) -> StepBy<Self>
where
    Self: Sized,
```

--------------------------------

### Convenience Functions

Source: https://docs.rs/shlex/1.3.0/src/shlex/lib.rs.html

Convenience functions for quoting and joining strings with default or specific configurations.

```APIDOC
## Convenience Functions

### `join<'a, I: IntoIterator<Item = &'a str>>(words: I) -> String`

**Deprecated**: Convenience function that consumes an iterable of words and turns it into a single string, quoting words when necessary. Consecutive words will be separated by a single space.

Uses default settings except that nul bytes are passed through, which [may be dangerous](quoting_warning#nul-bytes), leading to this function being deprecated.

Equivalent to [`Quoter::new().allow_nul(true).join(words).unwrap()`](Quoter).

(That configuration never returns `Err`, so this function does not panic.)

The bytes equivalent is [bytes::join].

### `try_join<'a, I: IntoIterator<Item = &'a str>>(words: I) -> Result<String, QuoteError>`

Convenience function that consumes an iterable of words and turns it into a single string, quoting words when necessary. Consecutive words will be separated by a single space.

Uses default settings. The only error that can be returned is [`QuoteError::Nul`].

Equivalent to [`Quoter::new().join(words)`](Quoter).

The bytes equivalent is [bytes::try_join].

### `quote(in_str: &str) -> Cow<str>`

**Deprecated**: Given a single word, return a string suitable to encode it as a shell argument.

Uses default settings except that nul bytes are passed through, which [may be dangerous](quoting_warning#nul-bytes), leading to this function being deprecated.

Equivalent to [`Quoter::new().allow_nul(true).quote(in_str).unwrap()`](Quoter).

(That configuration never returns `Err`, so this function does not panic.)

The bytes equivalent is [bytes::quote].

### `try_quote(in_str: &str) -> Result<Cow<'_, str>, QuoteError>`

Given a single word, return a string suitable to encode it as a shell argument.

Uses default settings. The only error that can be returned is [`QuoteError::Nul`].

Equivalent to [`Quoter::new().quote(in_str)`](Quoter).

(That configuration never returns `Err`, so this function does not panic.)

The bytes equivalent is [bytes::try_quote].
```

--------------------------------

### Get next character with line number tracking

Source: https://docs.rs/shlex/1.3.0/src/shlex/bytes.rs.html

The `next_char` method advances the iterator and increments the line number if a newline character is encountered. It returns the next byte or `None` if the iterator is exhausted.

```rust
fn next_char(&mut self) -> Option<u8> {
    let res = self.in_iter.next().copied();
    if res == Some(b'\n') { self.line_no += 1; }
    res
}

```

--------------------------------

### Shlex zip() Method

Source: https://docs.rs/shlex/1.3.0/shlex/bytes/struct.Shlex.html

Combines the Shlex iterator with another iterator into an iterator of pairs.

```rust
fn zip<U>(self, other: U) -> Zip<Self, <U as IntoIterator>::IntoIter>
where
    Self: Sized,
    U: IntoIterator,
```

--------------------------------

### Shlex next_chunk() Method (Nightly)

Source: https://docs.rs/shlex/1.3.0/shlex/bytes/struct.Shlex.html

Advances the Shlex iterator and returns an array of N items. This is an experimental, nightly-only API.

```rust
fn next_chunk<const N: usize>(
    &mut self,
) -> Result<[Self::Item; N], IntoIter<Self::Item, N>>
where
    Self: Sized,
```

--------------------------------

### Shlex Constructor

Source: https://docs.rs/shlex/1.3.0/shlex/bytes/struct.Shlex.html

Creates a new Shlex iterator from a byte string slice. This is the entry point for parsing.

```rust
pub fn new(in_bytes: &'a [u8]) -> Self
```

--------------------------------

### Shlex::new

Source: https://docs.rs/shlex/1.3.0/shlex/bytes/struct.Shlex.html

Constructor for the Shlex struct. Initializes a new Shlex iterator with the provided byte string slice.

```APIDOC
### impl<'a> Shlex<'a>

#### pub fn new(in_bytes: &'a [u8]) -> Self

Creates a new Shlex iterator from a byte string slice.
```

--------------------------------

### Shlex::new

Source: https://docs.rs/shlex/1.3.0/src/shlex/bytes.rs.html

Creates a new Shlex iterator from a byte slice. This iterator will split the input byte string into words based on shell-like syntax.

```APIDOC
## Shlex::new

### Description
Creates a new `Shlex` iterator that processes a byte slice (`&[u8]`). This iterator splits the input into words according to POSIX shell rules.

### Method
`Shlex::new(in_bytes: &'a [u8]) -> Self`

### Parameters
* `in_bytes` (`&'a [u8]`) - The input byte slice to be tokenized.
```

--------------------------------

### product

Source: https://docs.rs/shlex/1.3.0/shlex/bytes/struct.Shlex.html

Iterates over the entire iterator, multiplying all the elements.

```APIDOC
## fn product<P>(self) -> P
where Self: Sized, P: Product<Self::Item>,

### Description
Iterates over the entire iterator, multiplying all the elements.
```

--------------------------------

### fn product<P>(self) -> P

Source: https://docs.rs/shlex/1.3.0/shlex/struct.Shlex.html

Iterates over the entire iterator, multiplying all the elements.

```APIDOC
## fn product<P>(self) -> P

### Description
Iterates over the entire iterator, multiplying all the elements.

### Constraints
- `P` must implement `Product<Self::Item>`.

### Returns
- The product of the elements in the iterator.
```

--------------------------------

### Shlex advance_by() Method (Nightly)

Source: https://docs.rs/shlex/1.3.0/shlex/bytes/struct.Shlex.html

Advances the Shlex iterator by a specified number of elements. This is a nightly-only experimental API.

```rust
fn advance_by(&mut self, n: usize) -> Result<(), NonZero<usize>>
```

--------------------------------

### Generic Blanket Implementations

Source: https://docs.rs/shlex/1.3.0/shlex/enum.QuoteError.html

Documentation for generic blanket implementations that apply to various types, including QuoteError.

```APIDOC
## Generic Blanket Implementations

### impl<T> Any for T
This blanket implementation provides the `type_id` method for any type `T` that is `'static` and sized.

#### fn type_id(&self) -> TypeId
Gets the `TypeId` of `self`.

### impl<T> Borrow<T> for T
This blanket implementation provides the `borrow` method for any type `T`.

#### fn borrow(&self) -> &T
Immutably borrows from an owned value.

### impl<T> BorrowMut<T> for T
This blanket implementation provides the `borrow_mut` method for any type `T`.

#### fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value.

### impl<T> CloneToUninit for T
This nightly-only experimental API provides `clone_to_uninit` for types `T` that implement `Clone`.

#### unsafe fn clone_to_uninit(&self, dest: *mut u8)
Performs copy-assignment from `self` to `dest`.

### impl<T> From<T> for T
This blanket implementation allows converting a value of type `T` into itself.

#### fn from(t: T) -> T
Returns the argument unchanged.

### impl<T, U> Into<U> for T
This blanket implementation allows converting type `T` into type `U` if `U` implements `From<T>`.

#### fn into(self) -> U
Calls `U::from(self)`.

### impl<T> ToOwned for T
This blanket implementation provides methods for creating owned data from borrowed data for types `T` that implement `Clone`.

#### type Owned = T
The resulting type after obtaining ownership.

#### fn to_owned(&self) -> T
Creates owned data from borrowed data, usually by cloning.

#### fn clone_into(&self, target: &mut T)
Uses borrowed data to replace owned data, usually by cloning.

### impl<T> ToString for T
This blanket implementation provides the `to_string` method for types `T` that implement `Display` and are sized.

#### fn to_string(&self) -> String
Converts the given value to a `String`.

### impl<T, U> TryFrom<U> for T
This blanket implementation allows attempting to convert type `U` into type `T` if `T` implements `TryFrom<U>`.

#### type Error = Infallible
The type returned in the event of a conversion error.

#### fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>
Performs the conversion.

### impl<T, U> TryInto<U> for T
This blanket implementation allows attempting to convert type `T` into type `U` if `U` implements `TryFrom<T>`.

#### type Error = <U as TryFrom<T>>::Error
The type returned in the event of a conversion error.

#### fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>
Performs the conversion.
```

--------------------------------

### Shlex size_hint() Method

Source: https://docs.rs/shlex/1.3.0/shlex/bytes/struct.Shlex.html

Provides an estimate of the remaining number of items the iterator will yield.

```rust
fn size_hint(&self) -> (usize, Option<usize>)
```

--------------------------------

### take

Source: https://docs.rs/shlex/1.3.0/shlex/struct.Shlex.html

Creates an iterator that yields the first `n` elements, or fewer if the underlying iterator ends sooner. This method is available from version 1.0.0.

```APIDOC
## fn take(self, n: usize) -> Take<Self>

### Description
Creates an iterator that yields the first `n` elements, or fewer if the underlying iterator ends sooner.

### Parameters
- `n`: The maximum number of elements to yield.

### Returns
A `Take` iterator.
```

--------------------------------

### Create a Shlex iterator

Source: https://docs.rs/shlex/1.3.0/src/shlex/lib.rs.html

Instantiate a `Shlex` iterator from a string slice. This iterator splits the input string into words according to POSIX shell rules.

```rust
pub fn new(in_str: &'a str) -> Self {
    Self(bytes::Shlex::new(in_str.as_bytes()))
}
```

--------------------------------

### fn partial_cmp<I>(self, other: I) -> Option<Ordering>

Source: https://docs.rs/shlex/1.3.0/shlex/struct.Shlex.html

Lexicographically compares `PartialOrd` elements, with short-circuit evaluation.

```APIDOC
## fn partial_cmp<I>(self, other: I) -> Option<Ordering>

### Description
Lexicographically compares the `PartialOrd` elements of this `Iterator` with those of another. The comparison works like short-circuit evaluation, returning a result without comparing the remaining elements. As soon as an order can be determined, the evaluation stops and a result is returned.

### Parameters
- **other**: Another `IntoIterator`.

### Constraints
- `Self::Item` must implement `PartialOrd` with respect to the item type of `I`.

### Returns
- `Some(Ordering)` if an order can be determined, `None` if elements are incomparable.
```

--------------------------------

### Test Shlex Joining Empty Vector

Source: https://docs.rs/shlex/1.3.0/src/shlex/lib.rs.html

Tests the `join` function with an empty vector, asserting that it returns an empty string.

```rust
#[test]
#[allow(deprecated)]
fn test_join() {
    assert_eq!(join(vec![]), "");
    assert_eq!(join(vec![""]), "''");
    assert_eq!(join(vec!["a", "b"]), "a b");
    assert_eq!(join(vec!["foo bar", "baz"]), "'foo bar' baz");
}
```

--------------------------------

### Shlex next() Method

Source: https://docs.rs/shlex/1.3.0/shlex/bytes/struct.Shlex.html

Advances the Shlex iterator and returns the next parsed word as an Option<Vec<u8>>. Returns None when parsing is complete.

```rust
fn next(&mut self) -> Option<Self::Item>
```

--------------------------------

### Rust: Safely Quoting a String for Shell Input

Source: https://docs.rs/shlex/1.3.0/src/shlex/quoting_warning.md.html

Demonstrates attempting to safely quote a string containing a control character before piping it to an interactive Bash shell. Even with quoting, the control character can be interpreted by the shell.

```rust
use std::process::{Command, Stdio};
use std::io::Write;

let evil_string = "\x01do_something_evil; ";
let quoted = shlex::try_quote(evil_string).unwrap();
println!("quoted string is {:?}", quoted);

let mut bash = Command::new("bash")
    .arg("-i") // force interactive mode
    .stdin(Stdio::piped())
    .spawn()
    .unwrap();
let stdin = bash.stdin.as_mut().unwrap();
write!(stdin, "echo {}\n", quoted).unwrap();

```

--------------------------------

### map_windows

Source: https://docs.rs/shlex/1.3.0/shlex/struct.Shlex.html

Calls the given function `f` for each contiguous window of size `N` over `self` and returns an iterator over the outputs of `f`. This is a nightly-only experimental API. This method is available from version 1.0.0.

```APIDOC
## fn map_windows<F, R, const N: usize>(self, f: F) -> MapWindows<Self, F, N>

### Description
Calls the given function `f` for each contiguous window of size `N` over `self` and returns an iterator over the outputs of `f`. Like `slice::windows()`, the windows during mapping overlap as well.

### Parameters
- `f`: A closure that takes a slice representing the window and returns a value `R`.

### Type Parameters
- `N`: The size of the window.

### Returns
A `MapWindows` iterator.

### Note
This is a nightly-only experimental API. (`iter_map_windows`)
```

--------------------------------

### Shlex for_each() Method

Source: https://docs.rs/shlex/1.3.0/shlex/bytes/struct.Shlex.html

Executes a closure for each element yielded by the Shlex iterator, consuming the iterator.

```rust
fn for_each<F>(self, f: F)
where
    Self: Sized,
    F: FnMut(Self::Item),
```

--------------------------------

### join

Source: https://docs.rs/shlex/1.3.0/shlex/fn.join.html

Convenience function that consumes an iterable of words and turns it into a single string, quoting words when necessary. Consecutive words will be separated by a single space. Uses default settings except that nul bytes are passed through, which may be dangerous, leading to this function being deprecated. Equivalent to `Quoter::new().allow_nul(true).join(words).unwrap()`. (That configuration never returns `Err`, so this function does not panic.) The bytes equivalent is bytes::join.

```APIDOC
## join

### Description
Convenience function that consumes an iterable of words and turns it into a single string, quoting words when necessary. Consecutive words will be separated by a single space.

Uses default settings except that nul bytes are passed through, which may be dangerous, leading to this function being deprecated.

Equivalent to `Quoter::new().allow_nul(true).join(words).unwrap()`.
(That configuration never returns `Err`, so this function does not panic.)
The bytes equivalent is bytes::join.

**Deprecated since 1.3.0**: replace with `try_join(words)?` to avoid nul byte danger.

### Signature
```rust
pub fn join<'a, I: IntoIterator<Item = &'a str>>(words: I) -> String
```
```

--------------------------------

### Shell command substitution with printf

Source: https://docs.rs/shlex/1.3.0/shlex/quoting_warning/index.html

Demonstrates how printf can be used within shell command substitution to escape special characters like octal escapes. This method relies on the shell's ability to execute commands.

```shell
printf '\001'
```

--------------------------------

### Shlex enumerate() Method

Source: https://docs.rs/shlex/1.3.0/shlex/bytes/struct.Shlex.html

Creates an iterator that yields pairs of (index, element) for each item from the Shlex iterator.

```rust
fn enumerate(self) -> Enumerate<Self>
where
    Self: Sized,
```

--------------------------------

### Tunneling commands over SSH with shlex::join

Source: https://docs.rs/shlex/1.3.0/shlex/quoting_warning/index.html

Demonstrates how `shlex::join` can be used to pass command arguments over SSH. If any argument contains a nul byte, the `std::process::Command` will fail to launch because command arguments cannot contain nul bytes.

```rust
std::process::Command::new("ssh")
    .arg("myhost")
    .arg("--")
    .arg(join(my_cmd_args))
```

--------------------------------

### Test join function with byte slices

Source: https://docs.rs/shlex/1.3.0/src/shlex/bytes.rs.html

This test suite validates the `join` function's behavior when joining a vector of byte slices, including handling invalid UTF-8 and empty inputs.

```rust
#[test]
#[allow(deprecated)]
fn test_join() {
    // Validate behavior with invalid UTF-8:
    assert_eq!(join(vec![INVALID_UTF8]), INVALID_UTF8_SINGLEQUOTED);
    // Replicate a few tests from lib.rs.  No need to replicate all of them.
    assert_eq!(join(vec![]), &b""[..]);
    assert_eq!(join(vec![&b""[..]]), b"''");
}
```

--------------------------------

### by_ref

Source: https://docs.rs/shlex/1.3.0/shlex/struct.Shlex.html

Creates a “by reference” adapter for this instance of `Iterator`. This method is available from version 1.0.0.

```APIDOC
## fn by_ref(&mut self) -> &mut Self

### Description
Creates a “by reference” adapter for this instance of `Iterator`.

### Returns
A mutable reference to `self`.
```

--------------------------------

### Demonstration of \xa0 as a word separator

Source: https://docs.rs/shlex/1.3.0/shlex/quoting_warning/index.html

Shows how the byte \xa0 can act as a word separator in Bash on macOS with UTF-8 locale when the input is invalid UTF-8, causing 'ls' to treat 'a' and 'b' as separate arguments.

```shell
echo -e 'ls a\xa0b' | bash
ls: a: No such file or directory
ls: b: No such file or directory
```

--------------------------------

### fn partial_cmp_by<I, F>(self, other: I, partial_cmp: F) -> Option<Ordering>

Source: https://docs.rs/shlex/1.3.0/shlex/bytes/struct.Shlex.html

Lexicographically compares the elements of this Iterator with those of another with respect to the specified comparison function. This is a nightly-only experimental API.

```APIDOC
## fn partial_cmp_by<I, F>(self, other: I, partial_cmp: F) -> Option<Ordering>

### Description
Lexicographically compares the elements of this `Iterator` with those of another with respect to the specified comparison function. This is a nightly-only experimental API.

### Parameters
- `other`: An iterator to compare against.
- `partial_cmp`: A closure that takes two elements and returns an `Option<Ordering>`.

### Returns
- `Option<Ordering>`: An `Option` containing the `Ordering` if a comparison could be made, otherwise `None`.
```

--------------------------------

### partition

Source: https://docs.rs/shlex/1.3.0/shlex/bytes/struct.Shlex.html

Consumes an iterator, creating two collections based on a predicate. Elements for which the predicate returns true go into the first collection, and the rest go into the second.

```APIDOC
## fn partition<B, F>(self, f: F) -> (B, B)

### Description
Consumes an iterator, creating two collections from it.

### Parameters
#### Path Parameters
- **f** (F) - Description: A closure that takes a reference to an item and returns a boolean.

### Constraints
- Self: Sized
- B: Default + Extend<Self::Item>
- F: FnMut(&Self::Item) -> bool

### Returns
- (B, B): A tuple containing two collections, partitioned based on the predicate.
```

--------------------------------

### Convenience function to join words with default settings (deprecated)

Source: https://docs.rs/shlex/1.3.0/src/shlex/lib.rs.html

A deprecated convenience function that joins an iterable of words into a single shell-escaped string. It uses default settings but allows NUL bytes, which can be dangerous. Use `try_join` instead.

```rust
#[deprecated(since = "1.3.0", note = "replace with `try_join(words)?` to avoid nul byte danger")]
pub fn join<'a, I: IntoIterator<Item = &'a str>>(words: I) -> String {
    Quoter::new().allow_nul(true).join(words).unwrap()
}
```

--------------------------------

### Demonstration of \xa0 as Word Separator

Source: https://docs.rs/shlex/1.3.0/src/shlex/quoting_warning.md.html

Shows how the \xa0 byte can cause issues with word separation in Bash on macOS when the input is invalid UTF-8. The shlex crate avoids this by always quoting arguments containing this byte.

```bash
$ echo -e 'ls a\xa0b' | bash
ls: a: No such file or directory
ls: b: No such file or directory
```

--------------------------------

### Try to quote bytes with default settings

Source: https://docs.rs/shlex/1.3.0/src/shlex/bytes.rs.html

Use this function to quote a byte slice into a shell argument using default settings. It may return `QuoteError::Nul` if NUL bytes are encountered.

```rust
pub fn try_quote(in_bytes: &[u8]) -> Result<Cow<[u8]>, QuoteError> {
    Quoter::new().quote(in_bytes)
}
```

--------------------------------

### Shlex::new

Source: https://docs.rs/shlex/1.3.0/shlex/struct.Shlex.html

Constructs a new Shlex iterator from a string slice. This iterator will yield words parsed according to shell syntax.

```APIDOC
## Shlex::new

### Description
Constructs a new `Shlex` iterator from a string slice. This iterator will yield words parsed according to shell syntax.

### Signature
```rust
pub fn new(in_str: &'a str) -> Self
```

### Parameters
* `in_str` (&'a str): The input string slice to be parsed.
```

--------------------------------

### split

Source: https://docs.rs/shlex/1.3.0/shlex/bytes/index.html

Convenience function that consumes the whole byte string at once. Returns None if the input was erroneous.

```APIDOC
## split

### Description
Convenience function that consumes the whole byte string at once. Returns None if the input was erroneous.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **return value** (Option<Vec<Vec<u8>>>) - A vector of byte strings representing the split words, or None if the input was erroneous.

### Response Example
None
```

--------------------------------

### Shlex peekable() Method

Source: https://docs.rs/shlex/1.3.0/shlex/bytes/struct.Shlex.html

Creates a peekable iterator, allowing inspection of the next element without consuming it.

```rust
fn peekable(self) -> Peekable<Self>
where
    Self: Sized,
```

--------------------------------

### Clone to Uninitialized Memory (Nightly)

Source: https://docs.rs/shlex/1.3.0/shlex/bytes/struct.Quoter.html

An experimental, nightly-only API that performs copy-assignment from the Quoter instance to an uninitialized memory location. Use with caution.

```rust
unsafe fn clone_to_uninit(&self, dest: *mut u8)
```

--------------------------------

### partition

Source: https://docs.rs/shlex/1.3.0/shlex/struct.Shlex.html

Consumes an iterator, creating two collections from it. This method is available from version 1.0.0.

```APIDOC
## fn partition<B, F>(self, f: F) -> (B, B)

### Description
Consumes an iterator, creating two collections from it.

### Parameters
- `f`: A closure that takes a reference to an item and returns a boolean, determining which partition the item belongs to.

### Type Parameters
- `B`: The type of the collections, which must implement `Default` and `Extend`.

### Returns
A tuple containing two collections.
```

--------------------------------

### Workaround for caret expansion in single quotes

Source: https://docs.rs/shlex/1.3.0/shlex/quoting_warning/index.html

Demonstrates the crate's workaround for the Bash caret expansion bug by forcing '^' to appear immediately after an opening single quote, preventing expansion.

```shell
'"''^'"'
```

--------------------------------

### Shlex intersperse_with() Method (Nightly)

Source: https://docs.rs/shlex/1.3.0/shlex/bytes/struct.Shlex.html

Creates an iterator that inserts elements generated by a closure between original elements. This is a nightly-only experimental API.

```rust
fn intersperse_with<G>(self, separator: G) -> IntersperseWith<Self, G>
where
    Self: Sized,
    G: FnMut() -> Self::Item,
```

--------------------------------

### From<Quoter> for Quoter implementation

Source: https://docs.rs/shlex/1.3.0/shlex/struct.Quoter.html

Allows converting a Quoter into itself. This implementation is often a no-op or used for type compatibility within generic contexts.

```rust
fn from(inner: Quoter) -> Quoter
```

```rust
fn from(quoter: Quoter) -> Quoter
```

--------------------------------

### Shell-quote a string with default settings

Source: https://docs.rs/shlex/1.3.0/shlex/fn.try_quote.html

Use `try_quote` to encode a single word as a shell argument. This function uses default settings and is equivalent to `Quoter::new().quote(in_str)`. It will only return an error if the input contains a null byte.

```rust
pub fn try_quote(in_str: &str) -> Result<Cow<'_, str>, QuoteError>
```

--------------------------------

### Test Shlex Splitting

Source: https://docs.rs/shlex/1.3.0/src/shlex/lib.rs.html

Tests the `split` function with various inputs, including spaces, quotes, and escaped characters. It asserts that the output matches the expected tokenized list or indicates an error.

```rust
static SPLIT_TEST_ITEMS: &'static [(&'static str, Option<&'static [&'static str]>)] = &[
    ("foo$baz", Some(&["foo$baz"])),
    ("foo baz", Some(&["foo", "baz"])),
    ("foo\"bar\"baz", Some(&["foobarbaz"])),
    ("foo \"bar\"baz", Some(&["foo", "barbaz"])),
    ("   foo \nbar", Some(&["foo", "bar"])),
    ("foo\
bar", Some(&["foobar"])),
    ("\"foo\
bar\"", Some(&["foobar"])),
    ("'baz\$b'", Some(&["baz\$b"])),
    ("'baz\
'", None),
    ("\", None),
    ("\"\", None),
    ("'\", None),
    ("\"", None),
    ("'", None),
    ("foo #bar
baz", Some(&["foo", "baz"])),
    ("foo #bar", Some(&["foo"])),
    ("foo#bar", Some(&["foo#bar"])),
    ("foo\"#bar", None),
    ("'\n'", Some(&["\n"])),
    ("'\\n'", Some(&["\\n"])),
];

#[test]
fn test_split() {
    for &(input, output) in SPLIT_TEST_ITEMS {
        assert_eq!(split(input), output.map(|o| o.iter().map(|&x| x.to_owned()).collect()));
    }
}
```

--------------------------------

### fn any<F>(&mut self, f: F) -> bool

Source: https://docs.rs/shlex/1.3.0/shlex/struct.Shlex.html

Tests if any element of the iterator matches a predicate.

```APIDOC
## fn any<F>(&mut self, f: F) -> bool

### Description
Tests if any element of the iterator matches a predicate.

### Parameters
- **f**: A closure that takes an item of the iterator and returns a boolean.

### Returns
- `true` if at least one element matches the predicate, `false` otherwise.
```

--------------------------------

### fn min(self) -> Option<Self::Item>

Source: https://docs.rs/shlex/1.3.0/shlex/struct.Shlex.html

Returns the minimum element of an iterator.

```APIDOC
## fn min(self) -> Option<Self::Item>

### Description
Returns the minimum element of an iterator.

### Constraints
- `Self::Item` must implement the `Ord` trait.

### Returns
- `Some(min_element)` if the iterator is not empty, `None` otherwise.
```

--------------------------------

### fn cmp_by<I, F>(self, other: I, cmp: F) -> Ordering

Source: https://docs.rs/shlex/1.3.0/shlex/struct.Shlex.html

Lexicographically compares elements using a custom comparison function. This is a nightly-only experimental API.

```APIDOC
## fn cmp_by<I, F>(self, other: I, cmp: F) -> Ordering

### Description
Lexicographically compares the elements of this `Iterator` with those of another with respect to the specified comparison function. This is a nightly-only experimental API.

### Parameters
- **other**: Another `IntoIterator`.
- **cmp**: A closure that takes two items and returns an `Ordering`.

### Returns
- An `Ordering` value indicating the comparison result.
```

--------------------------------

### Shlex intersperse() Method (Nightly)

Source: https://docs.rs/shlex/1.3.0/shlex/bytes/struct.Shlex.html

Creates an iterator that inserts a separator between elements. This is a nightly-only experimental API.

```rust
fn intersperse(self, separator: Self::Item) -> Intersperse<Self>
where
    Self: Sized,
    Self::Item: Clone,
```

--------------------------------

### Quoter::join

Source: https://docs.rs/shlex/1.3.0/shlex/bytes/struct.Quoter.html

Takes an iterable of byte string slices (words) and joins them into a single byte string, applying necessary quoting. Words are separated by a single space.

```APIDOC
## Quoter::join

### Description
Convenience function that consumes an iterable of words and turns it into a single byte string, quoting words when necessary. Consecutive words will be separated by a single space.

### Method
`pub fn join<'a, I: IntoIterator<Item = &'a [u8]>>( &self, words: I, ) -> Result<Vec<u8>, QuoteError>`

### Parameters
- **words** (I) - An iterable collection of byte string slices to be joined and quoted.

### Returns
A `Result` containing the joined and quoted byte string, or a `QuoteError` if quoting fails.
```

--------------------------------

### Shlex count() Method

Source: https://docs.rs/shlex/1.3.0/shlex/bytes/struct.Shlex.html

Consumes the Shlex iterator and returns the total number of items it yielded.

```rust
fn count(self) -> usize
where
    Self: Sized,
```

--------------------------------

### any

Source: https://docs.rs/shlex/1.3.0/shlex/bytes/struct.Shlex.html

Tests if any element of the iterator matches a predicate.

```APIDOC
## fn any<F>(&mut self, f: F) -> bool
where Self: Sized, F: FnMut(Self::Item) -> bool,

### Description
Tests if any element of the iterator matches a predicate.
```

--------------------------------

### map_windows

Source: https://docs.rs/shlex/1.3.0/shlex/bytes/struct.Shlex.html

Calls the given function `f` for each contiguous window of size `N` over `self` and returns an iterator over the outputs of `f`. Windows overlap.

```APIDOC
## fn map_windows<F, R, const N: usize>(self, f: F) -> MapWindows<Self, F, N>

### Description
Calls the given function `f` for each contiguous window of size `N` over `self` and returns an iterator over the outputs of `f`. Like `slice::windows()`, the windows during mapping overlap as well.

### Parameters
#### Path Parameters
- **f** (F) - Description: A closure that takes a slice representing the window and returns a value.

### Constraints
- Self: Sized
- F: FnMut(&[Self::Item; N]) -> R

### Returns
- MapWindows<Self, F, N>: An iterator over the results of applying `f` to each window.
```

--------------------------------

### join

Source: https://docs.rs/shlex/1.3.0/src/shlex/bytes.rs.html

Convenience function that consumes an iterable of words (byte slices) and turns it into a single byte string, quoting words when necessary. Consecutive words are separated by a single space. This function allows NUL bytes, which is potentially dangerous and leads to deprecation.

```APIDOC
## join

### Description
Convenience function that consumes an iterable of words and turns it into a single byte string, quoting words when necessary. Consecutive words will be separated by a single space.

Uses default settings except that nul bytes are passed through, which [may be dangerous](quoting_warning#nul-bytes), leading to this function being deprecated.

Equivalent to [`Quoter::new().allow_nul(true).join(words).unwrap()`](Quoter).

(That configuration never returns `Err`, so this function does not panic.)

The string equivalent is [shlex::join].

### Parameters
- `words`: An iterable of byte slices (`&[u8]`).

### Returns
A `Vec<u8>` representing the joined and quoted string.
```

--------------------------------

### fn unzip<A, B, FromA, FromB>(self) -> (FromA, FromB)

Source: https://docs.rs/shlex/1.3.0/shlex/struct.Shlex.html

Converts an iterator of pairs into a pair of containers.

```APIDOC
## fn unzip<A, B, FromA, FromB>(self) -> (FromA, FromB)

### Description
Converts an iterator of pairs into a pair of containers.

### Constraints
- `Self` must be an `Iterator` with `Item = (A, B)`.
- `FromA` must implement `Default` and `Extend<A>`.
- `FromB` must implement `Default` and `Extend<B>`.

### Returns
- A tuple `(FromA, FromB)` containing the collected elements.
```

--------------------------------

### Shlex chain() Method

Source: https://docs.rs/shlex/1.3.0/shlex/bytes/struct.Shlex.html

Combines the Shlex iterator with another iterator, yielding elements from both sequentially.

```rust
fn chain<U>(self, other: U) -> Chain<Self, <U as IntoIterator>::IntoIter>
where
    Self: Sized,
    U: IntoIterator<Item = Self::Item>,
```

--------------------------------

### Format Quoter for Debugging

Source: https://docs.rs/shlex/1.3.0/shlex/bytes/struct.Quoter.html

Formats the Quoter instance for debugging output. This implementation allows the Quoter's state to be inspected when using debug formatting.

```rust
fn fmt(&self, f: &mut Formatter<'_>) -> Result
```

--------------------------------

### Clone From Another Quoter Instance

Source: https://docs.rs/shlex/1.3.0/shlex/bytes/struct.Quoter.html

Performs copy-assignment from a source Quoter instance to the current one. This allows efficient duplication of Quoter state.

```rust
fn clone_from(&mut self, source: &Self)
```

--------------------------------

### try_quote

Source: https://docs.rs/shlex/1.3.0/shlex

Given a single word, returns a string suitable to encode it as a shell argument. This is a convenience function for default quoting.

```APIDOC
## try_quote

### Description
Given a single word, return a string suitable to encode it as a shell argument. This is a convenience function for default quoting.

### Function Signature
`fn try_quote(word: &str) -> Option<String>`
```

--------------------------------

### split

Source: https://docs.rs/shlex/1.3.0/shlex/index.html

Splits a string into words based on POSIX shell syntax. Returns None if the input is erroneous.

```APIDOC
## split

### Description
Convenience function that consumes the whole string at once. Returns None if the input was erroneous.

### Function Signature
`fn split(input: &str) -> Option<Vec<&str>>`
```

--------------------------------

### split

Source: https://docs.rs/shlex/1.3.0/index.html

Convenience function that consumes the whole string at once and splits it into words using POSIX shell syntax. Returns None if the input was erroneous.

```APIDOC
## split

### Description
Convenience function that consumes the whole string at once. Returns None if the input was erroneous.

### Function Signature
`fn split(input: &str) -> Option<Vec<&str>>`

### Parameters
- **input** (`&str`) - The string to be split.

### Returns
- `Option<Vec<&str>>` - A vector of string slices representing the words, or None if the input was erroneous.
```

--------------------------------

### try_quote

Source: https://docs.rs/shlex/1.3.0/shlex/fn.try_quote.html

Given a single word, return a string suitable to encode it as a shell argument. Uses default settings. The only error that can be returned is `QuoteError::Nul`. Equivalent to `Quoter::new().quote(in_str)`. (That configuration never returns `Err`, so this function does not panic.)

```APIDOC
## Function try_quote

### Description
Given a single word, return a string suitable to encode it as a shell argument. Uses default settings. The only error that can be returned is `QuoteError::Nul`. Equivalent to `Quoter::new().quote(in_str)`. (That configuration never returns `Err`, so this function does not panic.)

### Signature
```rust
pub fn try_quote(in_str: &str) -> Result<Cow<'_, str>, QuoteError>
```

### Parameters
* `in_str` (*str*) - The input string to be quoted.

### Returns
* `Result<Cow<'_, str>, QuoteError>` - A `Cow` containing the quoted string, or a `QuoteError` if the input contains a null byte.
```

--------------------------------

### shlex::bytes::split

Source: https://docs.rs/shlex/1.3.0/shlex/bytes/fn.split.html

Convenience function that consumes the whole byte string at once. Returns None if the input was erroneous.

```APIDOC
## Function split

### Summary
```
pub fn split(in_bytes: &[u8]) -> Option<Vec<Vec<u8>>>
```

### Description
Convenience function that consumes the whole byte string at once. Returns None if the input was erroneous.
```

--------------------------------

### Deprecated: Join Byte Slices with Default Quoting (Allow NUL)

Source: https://docs.rs/shlex/1.3.0/src/shlex/bytes.rs.html

Deprecated function that joins an iterable of byte slices into a single byte string, applying quoting as necessary. It allows NUL bytes, which can be dangerous. Use `try_join` instead.

```rust
pub fn join<'a, I: IntoIterator<Item = &'a [u8]>>(words: I) -> Vec<u8> {
    Quoter::new().allow_nul(true).join(words).unwrap()
}
```

--------------------------------

### Shlex map() Method

Source: https://docs.rs/shlex/1.3.0/shlex/bytes/struct.Shlex.html

Applies a closure to each element yielded by the Shlex iterator, transforming the elements.

```rust
fn map<B, F>(self, f: F) -> Map<Self, F>
where
    Self: Sized,
    F: FnMut(Self::Item) -> B,
```

--------------------------------

### cloned

Source: https://docs.rs/shlex/1.3.0/shlex/bytes/struct.Shlex.html

Creates an iterator which `clone`s all of its elements.

```APIDOC
## fn cloned<'a, T>(self) -> Cloned<Self>
where T: Clone + 'a, Self: Sized + Iterator<Item = &'a T>,

### Description
Creates an iterator which `clone`s all of its elements.
```

--------------------------------

### fn all<F>(&mut self, f: F) -> bool

Source: https://docs.rs/shlex/1.3.0/shlex/struct.Shlex.html

Tests if every element of the iterator matches a predicate.

```APIDOC
## fn all<F>(&mut self, f: F) -> bool

### Description
Tests if every element of the iterator matches a predicate.

### Parameters
- **f**: A closure that takes an item of the iterator and returns a boolean.

### Returns
- `true` if all elements match the predicate, `false` otherwise.
```

--------------------------------

### split

Source: https://docs.rs/shlex/1.3.0/shlex/fn.split.html

Convenience function that consumes the whole string at once. Returns None if the input was erroneous.

```APIDOC
## split

### Description
Convenience function that consumes the whole string at once. Returns None if the input was erroneous.

### Signature
```rust
pub fn split(in_str: &str) -> Option<Vec<String>>
```
```

--------------------------------

### try_quote

Source: https://docs.rs/shlex/1.3.0/shlex/bytes/fn.try_quote.html

Given a single word, return a string suitable to encode it as a shell argument. Uses default settings. The only error that can be returned is QuoteError::Nul. Equivalent to Quoter::new().quote(in_bytes). The string equivalent is shlex::try_quote.

```APIDOC
## Function try_quote

### Summary
```
pub fn try_quote(in_bytes: &[u8]) -> Result<Cow<'_, [u8]>, QuoteError>
```

### Description
Given a single word, return a string suitable to encode it as a shell argument. Uses default settings. The only error that can be returned is `QuoteError::Nul`. Equivalent to `Quoter::new().quote(in_bytes)`. (That configuration never returns `Err`, so this function does not panic.) The string equivalent is shlex::try_quote.
```

--------------------------------

### fn min_by_key<B, F>(self, f: F) -> Option<Self::Item>

Source: https://docs.rs/shlex/1.3.0/shlex/struct.Shlex.html

Returns the element that yields the minimum value from a specified function.

```APIDOC
## fn min_by_key<B, F>(self, f: F) -> Option<Self::Item>

### Description
Returns the element that gives the minimum value from the specified function.

### Parameters
- **f**: A closure that takes a reference to an item of the iterator and returns a value of type `B`.

### Constraints
- `B` must implement the `Ord` trait.

### Returns
- `Some(element)` where `element` yields the minimum value according to `f`, `None` if the iterator is empty.
```

--------------------------------

### try_into

Source: https://docs.rs/shlex/1.3.0/shlex/bytes/struct.Shlex.html

Performs a conversion from the current type to another type `U` that implements `TryFrom`. Returns a `Result` which is either the converted value or an error if the conversion fails.

```APIDOC
## fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

### Description
Performs the conversion.

### Method
`try_into`

### Parameters
None

### Return Value
- `Result<U, <U as TryFrom<T>>::Error>`: Ok(U) on success, Err(E) on failure.
```

--------------------------------

### Shlex skip_while() Method

Source: https://docs.rs/shlex/1.3.0/shlex/bytes/struct.Shlex.html

Creates an iterator that skips elements as long as a predicate closure returns true.

```rust
fn skip_while<P>(self, predicate: P) -> SkipWhile<Self, P>
where
    Self: Sized,
    P: FnMut(&Self::Item) -> bool,
```

--------------------------------

### inspect

Source: https://docs.rs/shlex/1.3.0/shlex/struct.Shlex.html

Does something with each element of an iterator, passing the value on. This method is available from version 1.0.0.

```APIDOC
## fn inspect<F>(self, f: F) -> Inspect<Self, F>

### Description
Does something with each element of an iterator, passing the value on.

### Parameters
- `f`: A closure that takes a reference to the item.

### Returns
An `Inspect` iterator.
```

--------------------------------

### Test splitting byte slices

Source: https://docs.rs/shlex/1.3.0/src/shlex/bytes.rs.html

This test suite validates the `split` function's behavior with various shell-like inputs, including spaces, quotes, backslashes, and comments.

```rust
#[cfg(test)]
static SPLIT_TEST_ITEMS: &'static [(&'static [u8], Option<&'static [&'static [u8]]>)] = &[
    (b"foo$baz", Some(&[b"foo$baz"])),
    (b"foo baz", Some(&[b"foo", b"baz"])),
    (b"foo\"bar\"baz", Some(&[b"foobarbaz"])),
    (b"foo \"bar\"baz", Some(&[b"foo", b"barbaz"])),
    (b"   foo \nbar", Some(&[b"foo", b"bar"])),
    (b"foo\
bar", Some(&[b"foobar"])),
    (b"\"foo\
bar\"", Some(&[b"foobar"])),
    (b"'baz\$b'", Some(&[b"baz\$b"])),
    (b"'baz\'"'", None),
    (b"\", None),
    (b"\"\", None),
    (b"'\", None),
    (b"\"", None),
    (b"'", None),
    (b"foo #bar
baz", Some(&[b"foo", b"baz"])),
    (b"foo #bar", Some(&[b"foo"])),
    (b"foo#bar", Some(&[b"foo#bar"])),
    (b"foo\"#bar", None),
    (b"'\n'", Some(&[b"\n"])),
    (b"'\\n'", Some(&[b"\\n"])),
    (INVALID_UTF8, Some(&[INVALID_UTF8])),
];

#[test]
fn test_split() {
    for &(input, output) in SPLIT_TEST_ITEMS {
        assert_eq!(split(input), output.map(|o| o.iter().map(|&x| x.to_owned()).collect()));
    }
}
```

--------------------------------

### fn position<P>(&mut self, predicate: P) -> Option<usize>

Source: https://docs.rs/shlex/1.3.0/shlex/struct.Shlex.html

Searches for an element in an iterator and returns its index.

```APIDOC
## fn position<P>(&mut self, predicate: P) -> Option<usize>

### Description
Searches for an element in an iterator, returning its index.

### Parameters
- **predicate**: A closure that takes an item of the iterator and returns a boolean.

### Returns
- `Some(index)` if an element satisfying the predicate is found, `None` otherwise.
```

--------------------------------

### shlex::fn::join Function Signature

Source: https://docs.rs/shlex/1.3.0/shlex/fn.join.html

This is the function signature for `shlex::fn::join`. It is deprecated since version 1.3.0 and recommends using `try_join` to avoid null byte dangers.

```rust
pub fn join<'a, I: IntoIterator<Item = &'a str>>(words: I) -> String
```

--------------------------------

### Shlex last() Method

Source: https://docs.rs/shlex/1.3.0/shlex/bytes/struct.Shlex.html

Consumes the Shlex iterator and returns the last item it yielded.

```rust
fn last(self) -> Option<Self::Item>
where
    Self: Sized,
```

--------------------------------

### Convenience function to join words with default settings

Source: https://docs.rs/shlex/1.3.0/src/shlex/lib.rs.html

A convenience function that joins an iterable of words into a single shell-escaped string using default `Quoter` settings. It returns a `Result` and the only possible error is `QuoteError::Nul`.

```rust
pub fn try_join<'a, I: IntoIterator<Item = &'a str>>(words: I) -> Result<String, QuoteError> {
    Quoter::new().join(words)
}
```

--------------------------------

### Convenience function to quote a string with default settings (deprecated)

Source: https://docs.rs/shlex/1.3.0/src/shlex/lib.rs.html

A deprecated convenience function that quotes a single string for shell argument safety using default settings but allowing NUL bytes. Use `try_quote` instead.

```rust
#[deprecated(since = "1.3.0", note = "replace with `try_quote(str)?` to avoid nul byte danger")]
pub fn quote(in_str: &str) -> Cow<str> {
    Quoter::new().allow_nul(true).quote(in_str).unwrap()
}
```

--------------------------------

### shlex::bytes::split Function Signature

Source: https://docs.rs/shlex/1.3.0/shlex/bytes/fn.split.html

This is the function signature for `shlex::bytes::split`. It takes a byte slice as input and returns an `Option` containing a vector of byte vectors if successful, or `None` if the input is erroneous.

```rust
pub fn split(in_bytes: &[u8]) -> Option<Vec<Vec<u8>>>
```

--------------------------------

### Configure Quoter to Allow Null Bytes

Source: https://docs.rs/shlex/1.3.0/shlex/bytes/struct.Quoter.html

Sets whether the Quoter should allow null bytes in the strings it processes. By default, null bytes are not allowed and will result in a QuoteError::Nul.

```rust
pub fn allow_nul(self, allow: bool) -> Self
```

--------------------------------

### copied

Source: https://docs.rs/shlex/1.3.0/shlex/bytes/struct.Shlex.html

Creates an iterator which copies all of its elements.

```APIDOC
## fn copied<'a, T>(self) -> Copied<Self>
where T: Copy + 'a, Self: Sized + Iterator<Item = &'a T>,

### Description
Creates an iterator which copies all of its elements.
```