### 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::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 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 ### 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 where Self: Sized, ``` ### Parameters - **n** (usize) - Required - The number of elements to yield. ### Return Value - **Take** - 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 NonEmpty { /// Alias for [`NonEmpty::singleton`]. pub const fn new(e: T) -> Self { Self::singleton(e) } /// Converts from `&NonEmpty` 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(iter: I) -> Option> where I: IntoIterator, { 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 { 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 where Self: Sized ### Parameters - **n** (usize) - Required - The number of elements to yield. ### Returns - **Take** - 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 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 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> { // 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::, _>( &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) - 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 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 { 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 NonEmpty { /// Alias for [`NonEmpty::singleton`]. pub const fn new(e: T) -> Self { Self::singleton(e) } /// Converts from `&NonEmpty` 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(iter: I) -> Option> where I: IntoIterator, { 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

(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

(self) -> P ### Description Iterates over the entire iterator, multiplying all the elements. ### Method product ### Signature ```rust fn product

(self) -> P where Self: Sized, P: Product, ``` ### 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) ```