nonempty

https://docs.rs/nonempty
Admin
nonempty is a Rust library providing a non-empty growable vector type that guarantees the presence...
Tokens:95,233
Snippets:651
Trust Score:9.1
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### from_slice example

Source: https://docs.rs/nonempty/latest/nonempty/struct.NonEmpty.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Example for from_slice: converts a slice to NonEmpty, returning None for empty slices.

```rust
use nonempty::NonEmpty;

let non_empty_vec = NonEmpty::from_slice(&[1, 2, 3, 4, 5]);
assert_eq!(non_empty_vec, Some(NonEmpty::from((1, vec![2, 3, 4, 5]))));

let empty_vec: Option<NonEmpty<&u32>> = NonEmpty::from_slice(&[]);
assert!(empty_vec.is_none());
```

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

### tail method with doc examples

Source: https://docs.rs/nonempty/latest/src/nonempty/lib.rs.html?search=u32+-%3E+bool

Returns the possibly-empty tail slice. The doc example shows an empty tail for a singleton and a populated tail for a larger list.

```rust
pub fn tail(&self) -> &[T] {
    &self.tail
}
```

```rust
use nonempty::NonEmpty;

let non_empty = NonEmpty::new(42);
assert_eq!(non_empty.tail(), &[]);

let non_empty = NonEmpty::from((1, vec![4, 2, 3]));
assert_eq!(non_empty.tail(), &[4, 2, 3]);
```

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

### minimum_by example

Source: https://docs.rs/nonempty/latest/nonempty/nonzero/struct.NonEmpty.html?search=std%3A%3Avec

Returns the element with the minimum value according to a comparison function. The example uses a vector of pairs and compares by the first element.

```rust
use nonempty::NonEmpty;

let non_empty = NonEmpty::new((0, 42));
assert_eq!(non_empty.minimum_by(|(k, _), (l, _)| k.cmp(l)), &(0, 42));

let non_empty = NonEmpty::from(((2, 1), vec![(2, -34), (4, 42), (0, 76), (1, 4), (3, 5)]));
assert_eq!(non_empty.minimum_by(|(k, _), (l, _)| k.cmp(l)), &(0, 76));
```

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

### minimum_by_key example

Source: https://docs.rs/nonempty/latest/nonempty/nonzero/struct.NonEmpty.html?search=std%3A%3Avec

Returns the element with the minimum value according to a key extraction function. The example uses a vector of pairs and extracts the first element as the key, also showing a negative key.

```rust
use nonempty::NonEmpty;

let non_empty = NonEmpty::new((0, 42));
assert_eq!(non_empty.minimum_by_key(|(k, _)| *k), &(0, 42));

let non_empty = NonEmpty::from(((2, 1), vec![(2, -34), (4, 42), (0, 76), (1, 4), (3, 5)]));
assert_eq!(non_empty.minimum_by_key(|(k, _)| *k), &(0, 76));
assert_eq!(non_empty.minimum_by_key(|(k, _)| -k), &(4, 42));
```

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

### binary_search_by_key example

Source: https://docs.rs/nonempty/latest/nonempty/nonzero/struct.NonEmpty.html?search=std%3A%3Avec

Searches a sorted non-empty vector by a key extraction function. The example uses a vector of pairs sorted by their second elements and checks four lookups: found, not found, and a range match.

```rust
use nonempty::NonEmpty;

let non_empty = NonEmpty::from((
    (0, 0),
    vec![(2, 1), (4, 1), (5, 1), (3, 1),
         (1, 2), (2, 3), (4, 5), (5, 8), (3, 13),
         (1, 21), (2, 34), (4, 55)]
));

assert_eq!(non_empty.binary_search_by_key(&0, |&(a,b)| b),  Ok(0));
assert_eq!(non_empty.binary_search_by_key(&13, |&(a,b)| b),  Ok(9));
assert_eq!(non_empty.binary_search_by_key(&4, |&(a,b)| b),   Err(7));
assert_eq!(non_empty.binary_search_by_key(&100, |&(a,b)| b), Err(13));
let r = non_empty.binary_search_by_key(&1, |&(a,b)| b);
assert!(match r { Ok(1..=4) => true, _ => false, });
```

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

### insert method with doc examples

Source: https://docs.rs/nonempty/latest/src/nonempty/lib.rs.html?search=u32+-%3E+bool

Inserts an element at a given index, shifting subsequent elements right. Panics if index > len. The doc example demonstrates inserting at various positions.

```rust
pub fn insert(&mut self, index: usize, element: T) {
    let len = self.len();
    assert!(index <= len);

    if index == 0 {
        // ... (implementation continues)
```

```rust
use nonempty::NonEmpty;

let mut non_empty = NonEmpty::from((1, vec![2, 3]));
non_empty.insert(1, 4);
assert_eq!(non_empty, NonEmpty::from((1, vec![4, 2, 3])));
non_empty.insert(4, 5);
assert_eq!(non_empty, NonEmpty::from((1, vec![4, 2, 3, 5])));
non_empty.insert(0, 42);
assert_eq!(non_empty, NonEmpty::from((42, vec![1, 4, 2, 3, 5])));
```

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

### maximum_by example

Source: https://docs.rs/nonempty/latest/nonempty/nonzero/struct.NonEmpty.html?search=std%3A%3Avec

Returns the element with the maximum value according to a comparison function. The example uses a vector of pairs and compares by the first element.

```rust
use nonempty::NonEmpty;

let non_empty = NonEmpty::new((0, 42));
assert_eq!(non_empty.maximum_by(|(k, _), (l, _)| k.cmp(l)), &(0, 42));

let non_empty = NonEmpty::from(((2, 1), vec![(2, -34), (4, 42), (0, 76), (1, 4), (3, 5)]));
assert_eq!(non_empty.maximum_by(|(k, _), (l, _)| k.cmp(l)), &(4, 42));
```

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

### minimum example

Source: https://docs.rs/nonempty/latest/nonempty/nonzero/struct.NonEmpty.html?search=std%3A%3Avec

Returns the minimum element in a non-empty vector. The example shows a single-element vector and a multi-element vector, with the expected minimum values.

```rust
use nonempty::NonEmpty;

let non_empty = NonEmpty::new(42);
assert_eq!(non_empty.minimum(), &42);

let non_empty = NonEmpty::from((1, vec![-34, 42, 76, 4, 5]));
assert_eq!(non_empty.minimum(), &-34);
```

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

### Deconstructing a NonEmpty List with split_first

Source: https://docs.rs/nonempty/latest/nonempty/nonzero/struct.NonEmpty.html?search=std%3A%3Avec

Demonstrates using split_first to get the head and tail of a NonEmpty list. The example shows both a multi-element list and a single-element list.

```rust
use nonempty::NonEmpty;

let mut non_empty = NonEmpty::from((1, vec![2, 3, 4, 5]));

// Guaranteed to have the head and we also get the tail.
assert_eq!(non_empty.split_first(), (&1, &[2, 3, 4, 5][..]));

let non_empty = NonEmpty::new(1);

// Guaranteed to have the head element.
assert_eq!(non_empty.split_first(), (&1, &[][..]));
```

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

### maximum_by_key example

Source: https://docs.rs/nonempty/latest/nonempty/nonzero/struct.NonEmpty.html?search=std%3A%3Avec

Returns the element with the maximum value according to a key extraction function. The example uses a vector of pairs and extracts the first element as the key, also showing a negative key.

```rust
use nonempty::NonEmpty;

let non_empty = NonEmpty::new((0, 42));
assert_eq!(non_empty.maximum_by_key(|(k, _)| *k), &(0, 42));

let non_empty = NonEmpty::from(((2, 1), vec![(2, -34), (4, 42), (0, 76), (1, 4), (3, 5)]));
assert_eq!(non_empty.maximum_by_key(|(k, _)| *k), &(4, 42));
assert_eq!(non_empty.maximum_by_key(|(k, _)| -k), &(0, 76));
```

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

### first_mut method with doc examples

Source: https://docs.rs/nonempty/latest/src/nonempty/lib.rs.html?search=u32+-%3E+bool

Returns a mutable reference to the first element. The doc example shows incrementing and multiplying the head value.

```rust
pub fn first_mut(&mut self) -> &mut T {
    &mut self.head
}
```

```rust
use nonempty::NonEmpty;

let mut non_empty = NonEmpty::new(42);
let head = non_empty.first_mut();
*head += 1;
assert_eq!(non_empty.first(), &43);

let mut non_empty = NonEmpty::from((1, vec![4, 2, 3]));
let head = non_empty.first_mut();
*head *= 42;
assert_eq!(non_empty.first(), &42);
```

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

### maximum example

Source: https://docs.rs/nonempty/latest/nonempty/nonzero/struct.NonEmpty.html?search=std%3A%3Avec

Returns the maximum element in a non-empty vector. The example shows a single-element vector and a multi-element vector, with the expected maximum values.

```rust
use nonempty::NonEmpty;

let non_empty = NonEmpty::new(42);
assert_eq!(non_empty.maximum(), &42);

let non_empty = NonEmpty::from((1, vec![-34, 42, 76, 4, 5]));
assert_eq!(non_empty.maximum(), &76);
```

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

### nonempty! usage example

Source: https://docs.rs/nonempty/latest/nonempty/macro.nonempty.html?search=

Usage example for the `nonempty!` macro. It constructs `NonEmpty` values with one or more elements, supports trailing commas, and notes that an empty invocation does not compile.

```rust
use nonempty::{NonEmpty, nonempty};

let v = nonempty![1, 2, 3];
assert_eq!(v, NonEmpty { head: 1, tail: vec![2, 3] });

let v = nonempty![1];
assert_eq!(v, NonEmpty { head: 1, tail: Vec::new() });

// Accepts trailing commas
let v = nonempty![1,];
assert_eq!(v, NonEmpty { head: 1, tail: Vec::new() });

// Doesn't compile!
// let v = nonempty![];
```

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

### split() example

Source: https://docs.rs/nonempty/latest/nonempty/nonzero/struct.NonEmpty.html?search=std%3A%3Avec

Shows how to deconstruct a NonEmpty into its first, last, and middle elements. When there are two or more elements, the last is Some; with only one element, the last is None.

```rust
use nonempty::NonEmpty;

let mut non_empty = NonEmpty::from((1, vec![2, 3, 4, 5]));

// When there are two or more elements, the last element is represented
// as a `Some`. Elements preceding it, except for the first, are returned
// in the middle.
assert_eq!(non_empty.split(), (&1, &[2, 3, 4][..], Some(&5)));

let non_empty = NonEmpty::new(1);

// The last element is `None` when there's only one element.
assert_eq!(non_empty.split(), (&1, &[][..], None));
```

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

### binary_search() example

Source: https://docs.rs/nonempty/latest/nonempty/nonzero/struct.NonEmpty.html?search=std%3A%3Avec

Binary searches a sorted NonEmpty for a value. Returns Ok(index) if found, or Err(insertion_index) if not found. Multiple matches may return any matching index.

```rust
use nonempty::NonEmpty;

let non_empty = NonEmpty::from((0, vec![1, 1, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55]));
assert_eq!(non_empty.binary_search(&0),   Ok(0));
assert_eq!(non_empty.binary_search(&13),  Ok(9));
assert_eq!(non_empty.binary_search(&4),   Err(7));
assert_eq!(non_empty.binary_search(&100), Err(13));
let r = non_empty.binary_search(&1);
assert!(match r { Ok(1..=4) => true, _ => false, });
```

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

### Sort a NonEmpty vector with sort()

Source: https://docs.rs/nonempty/latest/nonempty/nonzero/struct.NonEmpty.html?search=std%3A%3Avec

Example for the `sort` method on `NonEmpty`. It creates a non-empty vector with the `nonempty!` macro, sorts it in place, and asserts the sorted order.

```rust
use nonempty::nonempty;

let mut non_empty = nonempty![-5, 4, 1, -3, 2];

non_empty.sort();
assert!(non_empty == nonempty![-5, -3, 1, 2, 4]);
```

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

### append() example

Source: https://docs.rs/nonempty/latest/nonempty/nonzero/struct.NonEmpty.html?search=std%3A%3Avec

Appends a Vec to the tail of a NonEmpty. The Vec is consumed by the append method, and the resulting NonEmpty is compared to an expected value.

```rust
use nonempty::NonEmpty;

let mut non_empty = NonEmpty::new(1);
let mut vec = vec![2, 3, 4, 5];
non_empty.append(&mut vec);

let mut expected = NonEmpty::from((1, vec![2, 3, 4, 5]));

assert_eq!(non_empty, expected);
```

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

### binary_search_by() example

Source: https://docs.rs/nonempty/latest/nonempty/nonzero/struct.NonEmpty.html?search=std%3A%3Avec

Binary searches a sorted NonEmpty using a comparator function. The comparator must be consistent with the sort order. Returns Ok(index) or Err(insertion_index).

```rust
use nonempty::NonEmpty;

let non_empty = NonEmpty::from((0, vec![1, 1, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55]));
let seek = 0;
assert_eq!(non_empty.binary_search_by(|probe| probe.cmp(&seek)), Ok(0));
let seek = 13;
assert_eq!(non_empty.binary_search_by(|probe| probe.cmp(&seek)), Ok(9));
let seek = 4;
assert_eq!(non_empty.binary_search_by(|probe| probe.cmp(&seek)), Err(7));
let seek = 100;
assert_eq!(non_empty.binary_search_by(|probe| probe.cmp(&seek)), Err(13));
let seek = 1;
let r = non_empty.binary_search_by(|probe| probe.cmp(&seek));
assert!(match r { Ok(1..=4) => true, _ => false, });
```

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

### Iterating Over a NonEmpty List with iter

Source: https://docs.rs/nonempty/latest/nonempty/nonzero/struct.NonEmpty.html?search=std%3A%3Avec

Demonstrates iterating over a NonEmpty list using iter, which yields references to elements. The example shows checking the length and retrieving elements in order.

```rust
use nonempty::NonEmpty;

let mut l = NonEmpty::from((42, vec![36, 58]));

let mut l_iter = l.iter();

assert_eq!(l_iter.len(), 3);
assert_eq!(l_iter.next(), Some(&42));
assert_eq!(l_iter.next(), Some(&36));
assert_eq!(l_iter.next(), Some(&58));
assert_eq!(l_iter.next(), None);
```

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

### Mutating Elements with iter_mut

Source: https://docs.rs/nonempty/latest/nonempty/nonzero/struct.NonEmpty.html?search=std%3A%3Avec

Shows how to use iter_mut to modify each element in place. The example multiplies each element by 10 and then verifies the results.

```rust
use nonempty::NonEmpty;

let mut l = NonEmpty::new(42);
l.push(36);
l.push(58);

for i in l.iter_mut() {
    *i *= 10;
}

let mut l_iter = l.iter();

assert_eq!(l_iter.next(), Some(&420));
assert_eq!(l_iter.next(), Some(&360));
assert_eq!(l_iter.next(), Some(&580));
assert_eq!(l_iter.next(), None);
```

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

### Inserting Elements into a NonEmpty List

Source: https://docs.rs/nonempty/latest/nonempty/nonzero/struct.NonEmpty.html?search=std%3A%3Avec

Demonstrates the insert method, which inserts an element at a specific index and panics if the index is greater than the length. The examples show insertion at the end, beginning, and middle.

```rust
use nonempty::NonEmpty;

let mut non_empty = NonEmpty::from((1, vec![2, 3]));
non_empty.insert(1, 4);
assert_eq!(non_empty, NonEmpty::from((1, vec![4, 2, 3])));
non_empty.insert(4, 5);
assert_eq!(non_empty, NonEmpty::from((1, vec![4, 2, 3, 5])));
non_empty.insert(0, 42);
assert_eq!(non_empty, NonEmpty::from((42, vec![1, 4, 2, 3, 5])));
```

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

### NonEmpty::first

Source: https://docs.rs/nonempty/latest/nonempty/struct.NonEmpty.html?search=

Gets the first element of the NonEmpty.

```APIDOC
## NonEmpty::first

### Description
Gets the first element. Never fails.

### Method
`pub const fn first(&self) -> &T`

### Parameters
- `self` - The NonEmpty.

### Returns
- `&T` - Reference to the first element.

```

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

### NonEmpty::singleton

Source: https://docs.rs/nonempty/latest/nonempty/struct.NonEmpty.html?search=

Creates a new non-empty list with an initial element.

```APIDOC
## NonEmpty::singleton

### Description
Creates a new non-empty list with an initial element.

### Method
`pub const fn singleton(head: T) -> Self`

### Parameters
- `head` (T) - The initial element.

### Returns
- `Self` - A NonEmpty containing the single element.

```

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

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

Source: https://docs.rs/nonempty/latest/nonempty/struct.Iter.html?search=std%3A%3Avec

Creates an iterator that yields the first n elements.

```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.

### Method
`take`

### Signature
```rust
fn take(self, n: usize) -> Take<Self>
where
    Self: Sized,
```

### Parameters
- **n** (usize) - Required - The number of elements to yield.

### Return Value
- **Take<Self>** - An iterator that yields at most `n` elements.

### Availability
- Stable since 1.0.0 (const: unstable)
```

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

### NonEmpty constructors and basic accessors

Source: https://docs.rs/nonempty/latest/src/nonempty/lib.rs.html?search=

Provides constructors and basic accessors: new, as_ref, collect, singleton, is_empty, first, first_mut, tail, push, pop, insert.

```rust
impl<T> NonEmpty<T> {
    /// Alias for [`NonEmpty::singleton`].
    pub const fn new(e: T) -> Self {
        Self::singleton(e)
    }

    /// Converts from `&NonEmpty<T>` to `NonEmpty<&T>`.
    pub fn as_ref(&self) -> NonEmpty<&T> {
        NonEmpty {
            head: &self.head,
            tail: self.tail.iter().collect(),
        }
    }

    /// Attempt to convert an iterator into a `NonEmpty` vector.
    /// Returns `None` if the iterator was empty.
    pub fn collect<I>(iter: I) -> Option<NonEmpty<T>>
    where
        I: IntoIterator<Item = T>,
    {
        let mut iter = iter.into_iter();
        let head = iter.next()?;
        Some(Self {
            head,
            tail: iter.collect(),
        })
    }

    /// Create a new non-empty list with an initial element.
    pub const fn singleton(head: T) -> Self {
        NonEmpty {
            head,
            tail: Vec::new(),
        }
    }

    /// Always returns false.
    pub const fn is_empty(&self) -> bool {
        false
    }

    /// Get the first element. Never fails.
    pub const fn first(&self) -> &T {
        &self.head
    }

    /// Get the mutable reference to the first element. Never fails.
    ///
    /// # Examples
    ///
    /// ```
    /// use nonempty::NonEmpty;
    ///
    /// let mut non_empty = NonEmpty::new(42);
    /// let head = non_empty.first_mut();
    /// *head += 1;
    /// assert_eq!(non_empty.first(), &43);
    ///
    /// let mut non_empty = NonEmpty::from((1, vec![4, 2, 3]));
    /// let head = non_empty.first_mut();
    /// *head *= 42;
    /// assert_eq!(non_empty.first(), &42);
    /// ```
    pub fn first_mut(&mut self) -> &mut T {
        &mut self.head
    }

    /// Get the possibly-empty tail of the list.
    ///
    /// ```
    /// use nonempty::NonEmpty;
    ///
    /// let non_empty = NonEmpty::new(42);
    /// assert_eq!(non_empty.tail(), &[]);
    ///
    /// let non_empty = NonEmpty::from((1, vec![4, 2, 3]));
    /// assert_eq!(non_empty.tail(), &[4, 2, 3]);
    /// ```
    pub fn tail(&self) -> &[T] {
        &self.tail
    }

    /// Push an element to the end of the list.
    pub fn push(&mut self, e: T) {
        self.tail.push(e)
    }

    /// Pop an element from the end of the list.
    pub fn pop(&mut self) -> Option<T> {
        self.tail.pop()
    }

    /// Inserts an element at position index within the vector, shifting all elements after it to the right.
    ///
    /// # Panics
    ///
    /// Panics if index > len.
    ///
    /// # Examples
    ///
    /// ```
    /// use nonempty::NonEmpty;
    ///
    /// let mut non_empty = NonEmpty::from((1, vec![2, 3]));
    /// non_empty.insert(1, 4);
    /// assert_eq!(non_empty, NonEmpty::from((1, vec![4, 2, 3])));
    /// non_empty.insert(4, 5);
    /// assert_eq!(non_empty, NonEmpty::from((1, vec![4, 2, 3, 5])));
    /// non_empty.insert(0, 42);
    /// assert_eq!(non_empty, NonEmpty::from((42, vec![1, 4, 2, 3, 5])));
    /// ```
    pub fn insert(&mut self, index: usize, element: T) {
        let len = self.len();
        assert!(index <= len);

        if index == 0 {

```

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

### NonEmpty::get

Source: https://docs.rs/nonempty/latest/nonempty/struct.NonEmpty.html?search=

Gets an element by index.

```APIDOC
## NonEmpty::get

### Description
Gets an element by index.

### Method
`pub fn get(&self, index: usize) -> Option<&T>`

### Parameters
- `index` (usize) - The index to retrieve.

### Returns
- `Option<&T>` - Reference to the element if present, otherwise None.

```

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

### NonEmpty::last

Source: https://docs.rs/nonempty/latest/nonempty/struct.NonEmpty.html?search=

Gets the last element.

```APIDOC
## NonEmpty::last

### Description
Gets the last element. Never fails.

### Method
`pub fn last(&self) -> &T`

### Parameters
- `self` - The NonEmpty.

### Returns
- `&T` - Reference to the last element.

```

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

### take

Source: https://docs.rs/nonempty/latest/nonempty/struct.Iter.html

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

```APIDOC
## take

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

### Method
take

### Signature
fn take(self, n: usize) -> Take<Self> where Self: Sized

### Parameters
- **n** (usize) - Required - The number of elements to yield.

### Returns
- **Take<Self>** - An iterator that yields at most n elements.

### Example
```rust
let a = [1, 2, 3, 4];
let mut iter = a.iter().take(2);
assert_eq!(iter.next(), Some(&1));
```
```

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

### NonEmpty::capacity

Source: https://docs.rs/nonempty/latest/nonempty/struct.NonEmpty.html?search=

Gets the capacity of the list.

```APIDOC
## NonEmpty::capacity

### Description
Gets the capacity of the list.

### Method
`pub fn capacity(&self) -> NonZeroUsize`

### Parameters
- `self` - The NonEmpty.

### Returns
- `NonZeroUsize` - The capacity as a non-zero value.

```

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

### NonEmpty::len_nonzero

Source: https://docs.rs/nonempty/latest/nonempty/struct.NonEmpty.html?search=

Gets the length as a NonZeroUsize.

```APIDOC
## NonEmpty::len_nonzero

### Description
Gets the length of the list as a NonZeroUsize.

### Method
`pub fn len_nonzero(&self) -> NonZeroUsize`

### Parameters
- `self` - The NonEmpty.

### Returns
- `NonZeroUsize` - The length as a non-zero value.

```

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

### NonEmpty::len

Source: https://docs.rs/nonempty/latest/nonempty/struct.NonEmpty.html?search=

Gets the length of the list.

```APIDOC
## NonEmpty::len

### Description
Gets the length of the list.

### Method
`pub fn len(&self) -> usize`

### Parameters
- `self` - The NonEmpty.

### Returns
- `usize` - The length of the list.

```

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

### get

Source: https://docs.rs/nonempty/latest/src/nonempty/lib.rs.html?search=std%3A%3Avec

Returns a reference to the element at the given index.

```APIDOC
## `get`

### Description
Get an element by index. Returns `None` if the index is out of bounds.

### Method
`pub fn get(&self, index: usize) -> Option<&T>`

### Parameters
- `index: usize` - The index of the element.

### Returns
- `Option<&T>` - `Some(&T)` if the index is valid, `None` otherwise.

### Example
```rust
use nonempty::NonEmpty;

let l = NonEmpty::from((1, vec![2, 3]));
assert_eq!(l.get(0), Some(&1));
assert_eq!(l.get(2), Some(&3));
assert_eq!(l.get(3), None);
```
```

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

### NonEmpty::get_mut

Source: https://docs.rs/nonempty/latest/nonempty/struct.NonEmpty.html?search=

Gets an element by index, mutably.

```APIDOC
## NonEmpty::get_mut

### Description
Gets an element by index, mutably.

### Method
`pub fn get_mut(&mut self, index: usize) -> Option<&mut T>`

### Parameters
- `index` (usize) - The index to retrieve.

### Returns
- `Option<&mut T>` - Mutable reference to the element if present, otherwise None.

```

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

### NonEmpty::last_mut

Source: https://docs.rs/nonempty/latest/nonempty/struct.NonEmpty.html?search=

Gets the last element mutably.

```APIDOC
## NonEmpty::last_mut

### Description
Gets the last element mutably.

### Method
`pub fn last_mut(&mut self) -> &mut T`

### Parameters
- `self` - The NonEmpty.

### Returns
- `&mut T` - Mutable reference to the last element.

```

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

### NonEmpty::tail

Source: https://docs.rs/nonempty/latest/nonempty/struct.NonEmpty.html?search=

Gets the tail of the NonEmpty as a slice.

```APIDOC
## NonEmpty::tail

### Description
Gets the possibly-empty tail of the list.

### Method
`pub fn tail(&self) -> &[T]`

### Parameters
- `self` - The NonEmpty.

### Returns
- `&[T]` - Slice of the tail elements.

### Examples
```rust
use nonempty::NonEmpty;

let non_empty = NonEmpty::new(42);
assert_eq!(non_empty.tail(), &[]);

let non_empty = NonEmpty::from((1, vec![4, 2, 3]));
assert_eq!(non_empty.tail(), &[4, 2, 3]);
```

```

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

### Indexing a NonEmpty with Index<usize>

Source: https://docs.rs/nonempty/latest/nonempty/struct.NonEmpty.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Shows how to index into a NonEmpty using the Index<usize> implementation. Constructs a NonEmpty from a tuple and verifies element access with assert_eq.

```rust
use nonempty::NonEmpty;

let non_empty = NonEmpty::from((1, vec![2, 3, 4, 5]));

assert_eq!(non_empty[0], 1);
assert_eq!(non_empty[1], 2);
assert_eq!(non_empty[3], 4);

```

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

### NonEmpty::first_mut

Source: https://docs.rs/nonempty/latest/nonempty/struct.NonEmpty.html?search=

Gets a mutable reference to the first element.

```APIDOC
## NonEmpty::first_mut

### Description
Gets a mutable reference to the first element. Never fails.

### Method
`pub fn first_mut(&mut self) -> &mut T`

### Parameters
- `self` - The NonEmpty.

### Returns
- `&mut T` - Mutable reference to the first element.

### Examples
```rust
use nonempty::NonEmpty;

let mut non_empty = NonEmpty::new(42);
let head = non_empty.first_mut();
*head += 1;
assert_eq!(non_empty.first(), &43);

let mut non_empty = NonEmpty::from((1, vec![4, 2, 3]));
let head = non_empty.first_mut();
*head *= 42;
assert_eq!(non_empty.first(), &42);
```

```

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

### Encode and decode NonEmpty with bincode

Source: https://docs.rs/nonempty/latest/src/nonempty/lib.rs.html?search=std%3A%3Avec

Tests bincode encoding and decoding of NonEmpty. Requires the 'bincode' feature. Uses bincode::config::standard() and verifies round-trip equality.

```rust
#[cfg(feature = "bincode")]
mod bincode {
    use crate::NonEmpty;
    use alloc::boxed::Box;

    #[derive(Clone, Debug, Eq, PartialEq, bincode::Encode, bincode::Decode)]
    pub struct SimpleSerializable(pub i32);

    #[test]
    fn test_simple_round_trip() -> Result<(), Box<dyn core::error::Error>> {
        // Given
        let mut non_empty = NonEmpty::new(SimpleSerializable(42));
        non_empty.push(SimpleSerializable(777));

        // When
        let config = bincode::config::standard();
        let (res, _) = bincode::decode_from_slice::<NonEmpty<SimpleSerializable>, _>(
            &bincode::encode_to_vec(non_empty.clone(), config)?,
            config,
        )?;

        // Then
        assert_eq!(res, non_empty);

        Ok(())
    }
}
```

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

### split_first

Source: https://docs.rs/nonempty/latest/nonempty/struct.NonEmpty.html?search=

Splits a NonEmpty into head and tail.

```APIDOC
## split_first(&self) -> (&T, &[T])

### Description
Deconstructs a `NonEmpty` into its head and tail. This operation never fails since there is always a head element.

### Method
split_first

### Parameters
- **self** (&NonEmpty<T>) - Required - The `NonEmpty` to split.

### Returns
- **(&T, &[T])** - A tuple containing a reference to the head and a slice of the tail.

### Example
```rust
use nonempty::NonEmpty;

let mut non_empty = NonEmpty::from((1, vec![2, 3, 4, 5]));
assert_eq!(non_empty.split_first(), (&1, &[2, 3, 4, 5][..]));

let non_empty = NonEmpty::new(1);
assert_eq!(non_empty.split_first(), (&1, &[][..]));
```
```

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

### impl<T> Any for T where T: 'static + ?Sized - fn type_id(&self) -> TypeId

Source: https://docs.rs/nonempty/latest/nonempty/struct.Iter.html?search=

Gets the TypeId of self. This method is part of the blanket implementation of the Any trait for all types that are 'static and ?Sized.

```APIDOC
## fn type_id(&self) -> TypeId

### Description
Gets the `TypeId` of `self`.

### Method
`type_id`

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

### Parameters
- `self` (&Self) - The value whose type ID is requested.

### Returns
- `TypeId` - The `TypeId` of the type of `self`.

### Notes
This method is available on all types that are `'static` and `?Sized`.
```

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

### push and pop methods

Source: https://docs.rs/nonempty/latest/src/nonempty/lib.rs.html

Defines push to append an element to the end and pop to remove and return the last element. pop returns None if the tail is empty.

```rust
    /// Push an element to the end of the list.
    pub fn push(&mut self, e: T) {
        self.tail.push(e)
    }

    /// Pop an element from the end of the list.
    pub fn pop(&mut self) -> Option<T> {
        self.tail.pop()
    }
```

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

### by_ref

Source: https://docs.rs/nonempty/latest/nonempty/struct.Iter.html

Creates a by-reference adapter for this instance of Iterator.

```APIDOC
## by_ref

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

### Method
by_ref

### Signature
fn by_ref(&mut self) -> &mut Self where Self: Sized

### Parameters
None

### Returns
- **&mut Self** - A mutable reference to the iterator.

### Example
```rust
let a = [1, 2, 3];
let mut iter = a.iter();
let mut iter2 = iter.by_ref();
assert_eq!(iter2.next(), Some(&1));
```
```

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

### Core NonEmpty methods: new, as_ref, collect, singleton, is_empty, first

Source: https://docs.rs/nonempty/latest/src/nonempty/lib.rs.html

Provides fundamental constructors and accessors for NonEmpty. new is an alias for singleton, as_ref converts to NonEmpty<&T>, collect attempts to build from an iterator, singleton creates a single-element list, is_empty always returns false, and first returns the head element.

```rust
impl<T> NonEmpty<T> {
    /// Alias for [`NonEmpty::singleton`].
    pub const fn new(e: T) -> Self {
        Self::singleton(e)
    }

    /// Converts from `&NonEmpty<T>` to `NonEmpty<&T>`.
    pub fn as_ref(&self) -> NonEmpty<&T> {
        NonEmpty {
            head: &self.head,
            tail: self.tail.iter().collect(),
        }
    }

    /// Attempt to convert an iterator into a `NonEmpty` vector.
    /// Returns `None` if the iterator was empty.
    pub fn collect<I>(iter: I) -> Option<NonEmpty<T>>
    where
        I: IntoIterator<Item = T>,
    {
        let mut iter = iter.into_iter();
        let head = iter.next()?;
        Some(Self {
            head,
            tail: iter.collect(),
        })
    }

    /// Create a new non-empty list with an initial element.
    pub const fn singleton(head: T) -> Self {
        NonEmpty {
            head,
            tail: Vec::new(),
        }
    }

    /// Always returns false.
    pub const fn is_empty(&self) -> bool {
        false
    }

    /// Get the first element. Never fails.
    pub const fn first(&self) -> &T {
        &self.head
    }
}
```

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

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

Source: https://docs.rs/nonempty/latest/nonempty/struct.Iter.html?search=u32+-%3E+bool

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.

### Method
product

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

### Return Value
- **P** - The product of all elements in the iterator.

### Version
1.5.0 (const: unstable)
```

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

### nonempty! macro requires at least one element

Source: https://docs.rs/nonempty/latest/src/nonempty/lib.rs.html

Illustrates that nonempty! enforces a non-empty argument; an empty invocation does not compile. Shows a valid single-element example and a commented-out invalid case.

```rust
# extern crate alloc;
# use alloc::vec::Vec;
use nonempty::nonempty;

let l = nonempty![1];

// Doesn't compile!
// let l = nonempty![];
```

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

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

Source: https://docs.rs/nonempty/latest/nonempty/struct.Iter.html?search=std%3A%3Avec

Creates a by-reference adapter for the iterator.

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

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

### Method
`by_ref`

### Signature
```rust
fn by_ref(&mut self) -> &mut Self
where
    Self: Sized,
```

### Parameters
None.

### Return Value
- **&mut Self** - A mutable reference to the iterator.

### Availability
- Stable since 1.0.0 (const: unstable)
```
Tokens:
Raw