Mitsein

https://docs.rs/mitsein/0.9.0
Admin
Mitsein is a Rust crate that provides strongly typed APIs for non-empty collections, iterators,...
Tokens:960,724
Snippets:5,328
Trust Score:9.1
Update:6 months ago
Show doc for...
Tokens:
Raw
### Trim Start Matches Example

Source: https://docs.rs/mitsein/0.9.0/mitsein/str1/type.Str1.html

Demonstrates `trim_start_matches` with a character, a numeric check, and a slice of characters.

```Rust
assert_eq!("11foo1bar11".trim_start_matches('1'), "foo1bar11");
```

```Rust
assert_eq!("123foo1bar123".trim_start_matches(char::is_numeric), "foo1bar123");
```

```Rust
let x: &[_] = &['1', '2'];
assert_eq!("12foo1bar12".trim_start_matches(x), "foo1bar12");
```

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

### Slice First Method Example

Source: https://docs.rs/mitsein/0.9.0/mitsein/array_vec1/type.Segment.html

Demonstrates getting the first element of a slice.

```rust
let v = [10, 40, 30];
assert_eq!(Some(&10), v.first());

let w: &[i32] = &[];
assert_eq!(None, w.first());
```

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

### Slice Len Method Example

Source: https://docs.rs/mitsein/0.9.0/mitsein/array_vec1/type.Segment.html

Demonstrates how to get the number of elements in a slice.

```rust
let a = [1, 2, 3];
assert_eq!(a.len(), 3);
```

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

### Get Start Index

Source: https://docs.rs/mitsein/0.9.0/src/mitsein/segment/range/index.rs.html

Returns the starting index of the IndexRange.

```rust
pub fn start(&self) -> usize {
        self.start
    }
```

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

### Unsafe Usage Example

Source: https://docs.rs/mitsein/0.9.0/src/mitsein/index_set1.rs.html

Example demonstrating the safety requirements when accessing the underlying IndexSet.

```rust
use mitsein::index_set1::IndexSet1;

    let mut xs = IndexSet1::from([0i32, 1, 2, 3]);
    // This block is unsound. The `&mut IndexSet` is dropped in the block and so `xs` can be
    // freely manipulated after the block despite violation of the non-empty guarantee.
    unsafe {
```

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

### Slice Is Empty Method Example

Source: https://docs.rs/mitsein/0.9.0/mitsein/array_vec1/type.Segment.html

Demonstrates checking if a slice is empty.

```rust
let a = [1, 2, 3];
assert!(!a.is_empty());

let b: &[i32] = &[];
assert!(b.is_empty());
```

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

### Slice Last Method Example

Source: https://docs.rs/mitsein/0.9.0/mitsein/array_vec1/type.Segment.html

Demonstrates getting the last element of a slice.

```rust
let v = [10, 40, 30];
assert_eq!(Some(&30), v.last());

let w: &[i32] = &[];
assert_eq!(None, w.last());
```

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

### Slice Split First Method Example

Source: https://docs.rs/mitsein/0.9.0/mitsein/array_vec1/type.Segment.html

Demonstrates splitting a slice into its first element and the rest.

```rust
let x = &[0, 1, 2];

if let Some((first, elements)) = x.split_first() {
    assert_eq!(first, &0);
    assert_eq!(elements, &[1, 2]);
}
```

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

### Using expect for Environment Variables

Source: https://docs.rs/mitsein/0.9.0/mitsein/iter1/type.Result.html

This example shows a recommended usage of `expect` for environment variables, providing a clear message about why the variable is expected to be set. This helps in debugging by indicating the expected source of the variable.

```rust
let path = std::env::var("IMPORTANT_PATH")
    .expect("env variable `IMPORTANT_PATH` should be set by `wrapper_script.sh`");
```

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

### Implement CloneToUninit (nightly)

Source: https://docs.rs/mitsein/0.9.0/mitsein/segment/enum.RangeError.html

Nightly-only experimental API for cloning to uninitialized memory.

```rust
impl<T> CloneToUninit for T
where T: Clone,
unsafe fn clone_to_uninit(&self, dest: *mut u8)
```

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

### Slice Last Mut Method Example

Source: https://docs.rs/mitsein/0.9.0/mitsein/array_vec1/type.Segment.html

Demonstrates getting a mutable reference to the last element of a slice.

```rust
let x = &mut [0, 1, 2];

if let Some(last) = x.last_mut() {
    *last = 10;
}
assert_eq!(x, &[0, 1, 10]);

let y: &mut [i32] = &mut [];
assert_eq!(None, y.last_mut());
```

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

### Create a new Arc

Source: https://docs.rs/mitsein/0.9.0/mitsein/sync1/type.ArcStr1.html

Basic example of creating a new `Arc` instance with a value.

```rust
use std::sync::Arc;

let five = Arc::new(5);
```

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

### Slice First Mut Method Example

Source: https://docs.rs/mitsein/0.9.0/mitsein/array_vec1/type.Segment.html

Demonstrates getting a mutable reference to the first element of a slice.

```rust
let x = &mut [0, 1, 2];

if let Some(first) = x.first_mut() {
    *first = 5;
}
assert_eq!(x, &[5, 1, 2]);

let y: &mut [i32] = &mut [];
assert_eq!(None, y.first_mut());
```

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

### Try Creating BTreeSet1 from Reference

Source: https://docs.rs/mitsein/0.9.0/mitsein/btree_set1/type.BTreeSet1.html

Attempts to create a BTreeSet1 from a reference to a BTreeSet. Returns an error if the BTreeSet is empty.

```rust
pub fn try_from_ref(
    items: &BTreeSet<T>,
) -> Result<&Self, EmptyError<&BTreeSet<T>>>
```

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

### Slice Last Mutable Element Example

Source: https://docs.rs/mitsein/0.9.0/mitsein/vec1/type.Segment.html

Demonstrates how to get a mutable reference to the last element of a slice, returning `None` if the slice is empty.

```rust
let v = [10, 40, 30];
let last_mut = v.last_mut();
assert_eq!(last_mut, Some(&mut 30));

let w: &mut [i32] = &mut [];
assert_eq!(w.last_mut(), None);
```

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

### Implementations for TakeIfMany<'a, T, U, N>

Source: https://docs.rs/mitsein/0.9.0/mitsein/small_vec1/type.RemoveIfMany.html

General implementations for TakeIfMany.

```APIDOC
### impl<'a, T, U, N> TakeIfMany<'a, T, U, N>

#### `pub fn or_else<E, F>(self, f: F) -> Result<U, E>`
where F: FnOnce() -> E

**Available on crate features `alloc` or `arrayvec` or `heapless` only.**

#### `pub fn or_none(self) -> Option<U>`

**Available on crate features `alloc` or `arrayvec` or `heapless` only.**

#### `pub fn or_false(self) -> bool`

**Available on crate features `alloc` or `arrayvec` or `heapless` only.**
```

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

### Manage Rc with Custom Allocators

Source: https://docs.rs/mitsein/0.9.0/mitsein/rc1/type.RcSlice1.html

Examples demonstrating the use of Rc with the allocator_api to manage raw pointers and custom allocators.

```rust
#![feature(allocator_api)]

use std::rc::Rc;
use std::alloc::System;

let x = Rc::new_in("hello".to_owned(), System);
let (x_ptr, _alloc) = Rc::into_raw_with_allocator(x);

unsafe {
    // Convert back to an `Rc` to prevent leak.
    let x = Rc::from_raw_in(x_ptr, System);
    assert_eq!(&*x, "hello");

    // Further calls to `Rc::from_raw(x_ptr)` would be memory-unsafe.
}

// The memory was freed when `x` went out of scope above, so `x_ptr` is now dangling!
```

```rust
#![feature(allocator_api)]

use std::rc::Rc;
use std::alloc::System;

let x: Rc<[u32], _> = Rc::new_in([1, 2, 3], System);
let x_ptr: *const [u32] = Rc::into_raw_with_allocator(x).0;

unsafe {
    let x: Rc<[u32; 3], _> = Rc::from_raw_in(x_ptr.cast::<[u32; 3]>(), System);
    assert_eq!(&*x, &[1, 2, 3]);
}
```

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

### Get Tail Segment

Source: https://docs.rs/mitsein/0.9.0/src/mitsein/btree_set1.rs.html

Returns a new segment representing the tail of the current segment. It calculates the start of the tail based on the current range's bounds.

```rust
fn tail(&mut self) -> Segment<'_, K, Self::Range> {
        if let Some(range) = self.range.clone() {
            let (start, end) = range.into_bounds();
            let start = match start {
                Bound::Excluded(start) => self.items.range(start..).nth(2),
                Bound::Included(start) => self.items.range(start..).nth(1),
                Bound::Unbounded => self.items.iter().nth(1),
            };
            let range = start
                .cloned()
                .and_then(|start| range::ordered_range_bounds((Bound::Included(start), end)).ok())
                .map(|(start, end)| ItemRange::unchecked(start, end));
            Segment::unchecked(self.items, range)
        }
        else {
            Segment::unchecked(self.items, None)
        }
    }
```

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

### Try Create IndexSet1 from Reference

Source: https://docs.rs/mitsein/0.9.0/mitsein/index_set1/type.IndexSet1.html

Attempts to create a reference to an IndexSet1 from a reference to an IndexSet. Returns an error if the IndexSet is empty.

```rust
pub fn try_from_ref( items: &IndexSet<T, S>, ) -> Result<&Self, EmptyError<&IndexSet<T, S>>>
```

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

### Implement ByTail for Segment

Source: https://docs.rs/mitsein/0.9.0/src/mitsein/heapless/vec1.rs.html

Provides methods to get the tail or reverse tail of a segment. `tail` returns the segment from the start index, and `rtail` returns the segment from the end.

```rust
impl<K, T, S> ByTail for Segment<'_, K>
where
    K: ClosedVec<Item = T, Storage = S> + Segmentation<Target = VecInner<T, usize, S>>,
    S: ?Sized + VecStorage<T>,
{
    type Range = IndexRange;

    fn tail(&mut self) -> Segment<'_, K> {
        self.project_tail_range()
    }

    fn rtail(&mut self) -> Segment<'_, K> {
        let n = self.len();
        self.project_rtail_range(n)
    }
}
```

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

### Get the First Element in a Segment

Source: https://docs.rs/mitsein/0.9.0/src/mitsein/btree_set1.rs.html

Returns an optional reference to the first element within the segment's defined range. Handles different bound types for the start of the range.

```rust
pub fn first(&self) -> Option<&T> {
        self.range
            .as_ref()
            .and_then(|range| match range.start_bound() {
                Bound::Excluded(start) => self.items.range(start..).nth(1),
                Bound::Included(start) => self.items.range(start..).next(),
                Bound::Unbounded => self.items.first(),
            })
    }
```

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

### HashSet1 Creation Methods

Source: https://docs.rs/mitsein/0.9.0/src/mitsein/hash_set1.rs.html

Methods for creating new HashSet1 instances.

```APIDOC
## POST /from_one

### Description
Creates a HashSet1 containing a single element.

### Method
POST

### Endpoint
/from_one

### Parameters
#### Request Body
- **item** (T) - Required - The single item to include in the HashSet1.

### Request Example
```json
{
  "item": "single_item"
}
```

### Response
#### Success Response (200)
- **HashSet1<T, RandomState>** - A new HashSet1 containing the specified item.
```

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

### String1 Conversions

Source: https://docs.rs/mitsein/0.9.0/mitsein/string1/type.String1.html

Demonstrates how String1 can be created from various input types like &Str1, &mut NonEmpty<str>, Box<NonEmpty<str>>, Cow<'a, NonEmpty<str>>, char, and iterators.

```APIDOC
## String1 Conversions

### `impl<'a> From<&'a Str1> for String1`

#### `fn from(items: &'a Str1) -> Self`
Converts to this type from the input type.

### `impl<'a> From<&'a mut NonEmpty<str>> for String1`

#### `fn from(items: &'a mut Str1) -> Self`
Converts to this type from the input type.

### `impl From<Box<NonEmpty<str>>> for String1`

#### `fn from(items: BoxedStr1) -> Self`
Converts to this type from the input type.

### `impl<'a> From<Cow<'a, NonEmpty<str>>> for String1`

#### `fn from(items: CowStr1<'a>) -> Self`
Converts to this type from the input type.

### `impl From<char> for String1`

#### `fn from(point: char) -> Self`
Converts to this type from the input type.

### `impl<'a> FromIterator1<&'a NonEmpty<str>> for String1`

#### `fn from_iter1<I>(items: I) -> Self`
where I: IntoIterator1<Item = &'a Str1>
Converts to this type from the input type.

#### `fn try_from_iter<I>(items: I) -> Result<Self, EmptyError<Peekable<I::IntoIter>>>`
where Self: Sized, I: IntoIterator<Item = T>
Attempts to convert from an iterator, returning an error if the iterator is empty.

### `impl<'a> FromIterator1<&'a char> for String1`

#### `fn from_iter1<I>(items: I) -> Self`
where I: IntoIterator1<Item = &'a char>
Converts to this type from the input type.

#### `fn try_from_iter<I>(items: I) -> Result<Self, EmptyError<Peekable<I::IntoIter>>>`
where Self: Sized, I: IntoIterator<Item = T>
Attempts to convert from an iterator, returning an error if the iterator is empty.

### `impl<'a> FromIterator1<Cow<'a, NonEmpty<str>>> for String1`

#### `fn from_iter1<I>(items: I) -> Self`
where I: IntoIterator1<Item = CowStr1<'a>>
Converts to this type from the input type.

#### `fn try_from_iter<I>(items: I) -> Result<Self, EmptyError<Peekable<I::IntoIter>>>`
where Self: Sized, I: IntoIterator<Item = T>
Attempts to convert from an iterator, returning an error if the iterator is empty.

### `impl FromIterator1<NonEmpty<String>> for String1`

#### `fn from_iter1<I>(items: I) -> Self`
where I: IntoIterator1<Item = String1>
Converts to this type from the input type.

#### `fn try_from_iter<I>(items: I) -> Result<Self, EmptyError<Peekable<I::IntoIter>>>`
where Self: Sized, I: IntoIterator<Item = T>
Attempts to convert from an iterator, returning an error if the iterator is empty.

### `impl FromIterator1<char> for String1`

#### `fn from_iter1<I>(items: I) -> Self`
where I: IntoIterator1<Item = char>
Converts to this type from the input type.

#### `fn try_from_iter<I>(items: I) -> Result<Self, EmptyError<Peekable<I::IntoIter>>>`
where Self: Sized, I: IntoIterator<Item = T>
Attempts to convert from an iterator, returning an error if the iterator is empty.

### `impl<'a> TryFrom<&'a String> for &'a String1`

#### `type Error = EmptyError<&'a String>`
The type returned in the event of a conversion error.

#### `fn try_from(items: &'a String) -> Result<Self, Self::Error>`
Performs the conversion.

### `impl<'a> TryFrom<&'a mut String> for &'a mut String1`

(No function signature provided for this impl block)
```

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

### Accessing Metadata with `and_then`

Source: https://docs.rs/mitsein/0.9.0/mitsein/index_map1/type.OrOnlyEntry.html

Demonstrates using `and_then` to chain operations that return a `Result`, such as getting file metadata. This example shows how to handle potential errors like file not found.

```rust
use std::{io::ErrorKind, path::Path};

// Note: on Windows "/" maps to "C:\"
let root_modified_time = Path::new("/").metadata().and_then(|md| md.modified());
assert!(root_modified_time.is_ok());

let should_fail = Path::new("/bad/path").metadata().and_then(|md| md.modified());
assert!(should_fail.is_err());
assert_eq!(should_fail.unwrap_err().kind(), ErrorKind::NotFound);
```

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

### Split string by various patterns

Source: https://docs.rs/mitsein/0.9.0/mitsein/str1/type.Str1.html

Demonstrates basic usage of the split method with characters, strings, and closures.

```rust
let v: Vec<&str> = "Mary had a little lamb".split(' ').collect();
assert_eq!(v, ["Mary", "had", "a", "little", "lamb"]);

let v: Vec<&str> = "".split('X').collect();
assert_eq!(v, [""]);

let v: Vec<&str> = "lionXXtigerXleopard".split('X').collect();
assert_eq!(v, ["lion", "", "tiger", "leopard"]);

let v: Vec<&str> = "lion::tiger::leopard".split("::").collect();
assert_eq!(v, ["lion", "tiger", "leopard"]);

let v: Vec<&str> = "AABBCC".split("DD").collect();
assert_eq!(v, ["AABBCC"]);

let v: Vec<&str> = "abc1def2ghi".split(char::is_numeric).collect();
assert_eq!(v, ["abc", "def", "ghi"]);

let v: Vec<&str> = "lionXtigerXleopard".split(char::is_uppercase).collect();
assert_eq!(v, ["lion", "tiger", "leopard"]);
```

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

### Get Element Offset in Slice (Unaligned Element)

Source: https://docs.rs/mitsein/0.9.0/mitsein/vec1/type.Segment.html

Demonstrates `element_offset` returning `None` when an element reference points between elements, not to the start of one. This is useful for understanding pointer alignment within flattened slices.

```rust
#![feature(substr_range)]

let arr: &[[u32; 2]] = &[[0, 1], [2, 3]];
let flat_arr: &[u32] = arr.as_flattened();

let ok_elm: &[u32; 2] = flat_arr[0..2].try_into().unwrap();
let weird_elm: &[u32; 2] = flat_arr[1..3].try_into().unwrap();

assert_eq!(ok_elm, &[0, 1]);
assert_eq!(weird_elm, &[1, 2]);

assert_eq!(arr.element_offset(ok_elm), Some(0)); // Points to element 0
assert_eq!(arr.element_offset(weird_elm), None); // Points between element 0 and 1
```

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

### Get Element Offset in Slice (Basic)

Source: https://docs.rs/mitsein/0.9.0/mitsein/vec1/type.Segment.html

Determines the byte offset of an element reference within a slice. This method uses pointer arithmetic and does not compare elements. It returns `None` if the element reference does not point to the start of an element.

```rust
#![feature(substr_range)]

let nums: &[u32] = &[1, 7, 1, 1];
let num = &nums[2];

assert_eq!(num, &1);
assert_eq!(nums.element_offset(num), Some(2));
```

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

### pub fn repeat(&self, n: usize) -> String

Source: https://docs.rs/mitsein/0.9.0/mitsein/str1/type.Str1.html

Creates a new String by repeating the string N times.

```APIDOC
## repeat

### Description
Creates a new String by repeating a string n times.

### Parameters
- **n** (usize) - Required - The number of times to repeat the string.

### Response
- **String** - The repeated string.
```

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

### Construction Methods

Source: https://docs.rs/mitsein/0.9.0/mitsein/index_set1/type.IndexSet1.html

Methods for creating new IndexSet1 instances.

```APIDOC
## POST /websites/rs_mitsein_0_9_0/from_one

### Description
Creates a new IndexSet1 containing a single item.

### Method
POST

### Endpoint
/websites/rs_mitsein_0_9_0/from_one

### Parameters
#### Request Body
- **item** (T) - Required - The item to include in the set.

### Response
#### Success Response (200)
- **Self** - The newly created IndexSet1.

#### Response Example
(Example not provided in source)
```

```APIDOC
## POST /websites/rs_mitsein_0_9_0/from_one_with_hasher

### Description
Creates a new IndexSet1 containing a single item with a specified hasher.

### Method
POST

### Endpoint
/websites/rs_mitsein_0_9_0/from_one_with_hasher

### Parameters
#### Request Body
- **item** (T) - Required - The item to include in the set.
- **hasher** (S) - Required - The hasher to use for the set.

### Response
#### Success Response (200)
- **Self** - The newly created IndexSet1.

#### Response Example
(Example not provided in source)
```

```APIDOC
## POST /websites/rs_mitsein_0_9_0/from_iter1_with_hasher

### Description
Creates a new IndexSet1 from an iterator of items with a specified hasher.

### Method
POST

### Endpoint
/websites/rs_mitsein_0_9_0/from_iter1_with_hasher

### Parameters
#### Request Body
- **items** (U) - Required - An iterator yielding items to include in the set.
- **hasher** (S) - Required - The hasher to use for the set.

### Response
#### Success Response (200)
- **Self** - The newly created IndexSet1.

#### Response Example
(Example not provided in source)
```

```APIDOC
## POST /websites/rs_mitsein_0_9_0/from_head_and_tail

### Description
Creates a new IndexSet1 from a head item and an iterator for the tail.

### Method
POST

### Endpoint
/websites/rs_mitsein_0_9_0/from_head_and_tail

### Parameters
#### Request Body
- **head** (T) - Required - The first item in the set.
- **tail** (I) - Required - An iterator yielding the remaining items.

### Response
#### Success Response (200)
- **Self** - The newly created IndexSet1.

#### Response Example
(Example not provided in source)
```

```APIDOC
## POST /websites/rs_mitsein_0_9_0/from_rtail_and_head

### Description
Creates a new IndexSet1 from an iterator for the tail and a head item.

### Method
POST

### Endpoint
/websites/rs_mitsein_0_9_0/from_rtail_and_head

### Parameters
#### Request Body
- **tail** (I) - Required - An iterator yielding the items for the tail.
- **head** (T) - Required - The last item in the set.

### Response
#### Success Response (200)
- **Self** - The newly created IndexSet1.

#### Response Example
(Example not provided in source)
```

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

### Get Element Offset (Nightly)

Source: https://docs.rs/mitsein/0.9.0/mitsein/array_vec1/type.Segment.html

Find the byte index of an element reference within a slice using pointer arithmetic. Returns `None` if the element reference is not aligned with the start of an element. Panics if `T` is zero-sized. This is a nightly-only experimental API.

```rust
#![feature(substr_range)]

let nums: &[u32] = &[1, 7, 1, 1];
let num = &nums[2];

assert_eq!(num, &1);
assert_eq!(nums.element_offset(num), Some(2));
```

```rust
#![feature(substr_range)]

let arr: &[[u32; 2]] = &[[0, 1], [2, 3]];
let flat_arr: &[u32] = arr.as_flattened();

let ok_elm: &[u32; 2] = flat_arr[0..2].try_into().unwrap();
let weird_elm: &[u32; 2] = flat_arr[1..3].try_into().unwrap();

assert_eq!(ok_elm, &[0, 1]);
assert_eq!(weird_elm, &[1, 2]);

assert_eq!(arr.element_offset(ok_elm), Some(0)); // Points to element 0
assert_eq!(arr.element_offset(weird_elm), None); // Points between element 0 and 1
```

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

### Box::from_non_null Example (Nightly)

Source: https://docs.rs/mitsein/0.9.0/mitsein/boxed1/type.BoxedStr1.html

Recreates a Box from a NonNull pointer, previously obtained via Box::into_non_null. This is a nightly-only experimental API.

```rust
#![feature(box_vec_non_null)]

let x = Box::new(5);
let non_null = Box::into_non_null(x);
let x = unsafe { Box::from_non_null(non_null) };
```

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

### Get Type ID of a Type

Source: https://docs.rs/mitsein/0.9.0/mitsein/array_vec1/enum.CardinalityError.html

Gets the TypeId of a type. This is a blanket implementation for any type T.

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

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

### Try clone from reference

Source: https://docs.rs/mitsein/0.9.0/mitsein/boxed1/type.BoxedStr1.html

Allocates memory on the heap and clones the source, returning an error if allocation fails.

```rust
#![feature(clone_from_ref)]
#![feature(allocator_api)]

let hello: Box<str> = Box::try_clone_from_ref("hello")?;
```

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

### Get Cause for CardinalityError (Deprecated)

Source: https://docs.rs/mitsein/0.9.0/mitsein/array_vec1/enum.CardinalityError.html

Deprecated method to get the underlying cause of the error. Replaced by Error::source.

```rust
fn cause(&self) -> Option<&dyn Error>
```

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

### Implementations for TakeIfMany with IndexMap (Alternative)

Source: https://docs.rs/mitsein/0.9.0/mitsein/index_map1/type.RemoveEntryIfMany.html

Details an alternative set of implementations for `TakeIfMany` with `IndexMap`, focusing on methods that return a `Result`.

```APIDOC
### impl<'a, K, V, S, U, N> TakeIfMany<'a, IndexMap<K, V, S>, U, N>

#### Methods
- **or_get_only()** -> `Result<U, IndexedOnlyEntry<'a, K, V>>`: Retrieves the entry, returning a `Result` indicating success or failure.
- **or_replace_only(value: V)** -> `Result<U, V>>`: Replaces the entry, returning a `Result`.
- **or_else_replace_only<F>(f: F)** -> `Result<U, V>>` where `F: FnOnce() -> V`: Replaces the entry using a closure, returning a `Result`.
```

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

### Get Underlying Array Reference

Source: https://docs.rs/mitsein/0.9.0/mitsein/heapless/vec1/type.Segment.html

Attempts to get a reference to the underlying array if the specified size `N` matches the slice length.

```APIDOC
## GET /slice/as_array/{N}

### Description
Gets a reference to the underlying array.

### Method
GET

### Endpoint
/slice/as_array/{N}

### Parameters
#### Path Parameters
- **N** (usize) - Required - The expected size of the array.

### Response
#### Success Response (200)
- **array_ref** (&[T; N]) - An optional reference to the underlying array if the size matches.

#### Response Example
```json
{
  "array_ref": [1, 2, 3]
}
```
```

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

### Try Creating Arc with Allocator API

Source: https://docs.rs/mitsein/0.9.0/mitsein/sync1/type.ArcStr1.html

Example of using `Arc::try_new` with the `allocator_api` feature to attempt creating an `Arc` and handle potential allocation errors.

```rust
#![feature(allocator_api)]
use std::sync::Arc;

let five = Arc::try_new(5)?;
```

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

### Construction Methods

Source: https://docs.rs/mitsein/0.9.0/mitsein/index_map1/type.IndexMap1.html

Methods for creating new IndexMap1 instances.

```APIDOC
## POST /api/indexmap1/from_one

### Description
Creates an IndexMap1 from a single key-value pair.

### Method
POST

### Endpoint
`/api/indexmap1/from_one`

### Parameters
#### Request Body
- **item** ((K, V)) - Required - The key-value pair to create the map from.

### Response
#### Success Response (200)
- **Self** - The newly created IndexMap1.

#### Response Example
```json
{
  "example": "IndexMap1 { ... }"
}
```

## POST /api/indexmap1/from_one_with_hasher

### Description
Creates an IndexMap1 from a single key-value pair with a specified hasher.

### Method
POST

### Endpoint
`/api/indexmap1/from_one_with_hasher`

### Parameters
#### Request Body
- **item** ((K, V)) - Required - The key-value pair to create the map from.
- **hasher** (S) - Required - The hasher to use for the map.

### Response
#### Success Response (200)
- **Self** - The newly created IndexMap1.

#### Response Example
```json
{
  "example": "IndexMap1 { ... }"
}
```

## POST /api/indexmap1/from_iter1_with_hasher

### Description
Creates an IndexMap1 from an iterator of key-value pairs with a specified hasher.

### Method
POST

### Endpoint
`/api/indexmap1/from_iter1_with_hasher`

### Parameters
#### Request Body
- **items** (I) - Required - An iterator yielding key-value pairs.
- **hasher** (S) - Required - The hasher to use for the map.

### Response
#### Success Response (200)
- **Self** - The newly created IndexMap1.

#### Response Example
```json
{
  "example": "IndexMap1 { ... }"
}
```

## POST /api/indexmap1/from_head_and_tail

### Description
Creates an IndexMap1 from a head element and an iterator for the tail.

### Method
POST

### Endpoint
`/api/indexmap1/from_head_and_tail`

### Parameters
#### Request Body
- **head** ((K, V)) - Required - The first key-value pair.
- **tail** (I) - Required - An iterator yielding the remaining key-value pairs.

### Response
#### Success Response (200)
- **Self** - The newly created IndexMap1.

#### Response Example
```json
{
  "example": "IndexMap1 { ... }"
}
```

## POST /api/indexmap1/from_rtail_and_head

### Description
Creates an IndexMap1 from an iterator for the tail and a head element.

### Method
POST

### Endpoint
`/api/indexmap1/from_rtail_and_head`

### Parameters
#### Request Body
- **tail** (I) - Required - An iterator yielding the key-value pairs.
- **head** ((K, V)) - Required - The last key-value pair.

### Response
#### Success Response (200)
- **Self** - The newly created IndexMap1.

#### Response Example
```json
{
  "example": "IndexMap1 { ... }"
}
```
```

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

### Get Description for CardinalityError (Deprecated)

Source: https://docs.rs/mitsein/0.9.0/mitsein/array_vec1/enum.CardinalityError.html

Deprecated method to get a string description of the error. Use the Display impl or to_string() instead.

```rust
fn description(&self) -> &str
```

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

### ItemRange::bounded Method

Source: https://docs.rs/mitsein/0.9.0/src/mitsein/segment/range/item.rs.html

Creates a new ItemRange with inclusive start and exclusive end bounds. Returns an error if the start is greater than the end.

```rust
pub fn bounded(start: N, end: N) -> Result<Self, UnorderedError<N>>
where
    N: Ord,
{
    if start <= end {
        Ok(ItemRange::unchecked(
            Bound::Included(start),
            Bound::Excluded(end),
        ))
    }
    else {
        Err(UnorderedError(start, end))
    }
}
```

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

### Split Slice into SIMD Types (Nightly Rust)

Source: https://docs.rs/mitsein/0.9.0/mitsein/array_vec1/type.Segment.html

Example of using the experimental `as_simd` method to split a slice into prefix, middle SIMD types, and suffix. Panics if SIMD type size is incompatible.

```rust
#![feature(portable_simd)]
use core::simd::prelude::*;

let short = &[1, 2, 3];
let (prefix, middle, suffix) = short.as_simd::<4>();
assert_eq!(middle, []); // Not enough elements for anything in the middle

// They might be split in any possible way between prefix and suffix
let it = prefix.iter().chain(suffix).copied();
assert_eq!(it.collect::<Vec<_>>(), vec![1, 2, 3]);

fn basic_simd_sum(x: &[f32]) -> f32 {
    use std::ops::Add;
    let (prefix, middle, suffix) = x.as_simd();
    let sums = f32x4::from_array([
        prefix.iter().copied().sum(),
        0.0,
        0.0,
        suffix.iter().copied().sum(),
    ]);
    let sums = middle.iter().copied().fold(sums, f32x4::add);
    sums.reduce_sum()
}

let numbers: Vec<f32> = (1..101).map(|x| x as _).collect();
assert_eq!(basic_simd_sum(&numbers[1..99]), 4949.0);
```

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

### Get Strong Reference Count of Rc

Source: https://docs.rs/mitsein/0.9.0/mitsein/rc1/type.RcStr1.html

Demonstrates how to get the number of strong (Rc) pointers to an allocation. This count determines when the allocation will be deallocated.

```rust
use std::rc::Rc;

let five = Rc::new(5);
let _also_five = Rc::clone(&five);

assert_eq!(2, Rc::strong_count(&five));

```

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

### Rc Utility Methods

Source: https://docs.rs/mitsein/0.9.0/mitsein/rc1/type.RcSlice1.html

Methods for pinning and mapping Rc instances.

```APIDOC
## pub fn pin(value: T) -> Pin<Rc<T>>

### Description
Constructs a new Pin<Rc<T>>. If T does not implement Unpin, the value will be pinned in memory.

## pub fn map<U>(this: Rc<T>, f: impl FnOnce(&T) -> U) -> Rc<U>

### Description
Maps the value in an Rc, reusing the allocation if possible. Must be called as Rc::map(r, f).
```

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

### Get Slice as Array Reference

Source: https://docs.rs/mitsein/0.9.0/mitsein/vec1/type.Segment.html

Attempts to get a reference to the underlying array if the slice length exactly matches `N`. Returns `None` otherwise.

```rust
let slice = &[1, 2, 3];
let arr_ref: Option<&[i32; 3]> = slice.as_array();
assert!(arr_ref.is_some());

let arr_ref_wrong_size: Option<&[i32; 2]> = slice.as_array();
assert!(arr_ref_wrong_size.is_none());
```

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

### IndexedEntry Get Methods

Source: https://docs.rs/mitsein/0.9.0/src/mitsein/index_map1.rs.html

Provides methods to get immutable or mutable references to values within an IndexedEntry, handling both single and multiple entry cases.

```rust
pub fn get(&self) -> &V {
        match self {
            IndexedEntry::Many(many) => many.get(),
            IndexedEntry::One(only) => only.get(),
        }
    }

    pub fn get_mut(&mut self) -> &mut V {
        match self {
            IndexedEntry::Many(many) => many.get_mut(),
            IndexedEntry::One(only) => only.get_mut(),
        }
    }

    pub fn key(&self) -> &K {
        match self {
            IndexedEntry::Many(many) => many.key(),
            IndexedEntry::One(only) => only.key(),
        }
    }

    pub fn index(&self) -> usize {
        match self {
            IndexedEntry::Many(many) => many.index(),
            IndexedEntry::One(only) => only.index(),
        }
    }
```

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

### Trim Prefix Example (Nightly)

Source: https://docs.rs/mitsein/0.9.0/mitsein/str1/type.Str1.html

Shows the nightly-only `trim_prefix` method, which removes a prefix if present and always returns a string slice, suitable for chaining.

```Rust
#![feature(trim_prefix_suffix)]

// Prefix present - removes it
assert_eq!("foo:bar".trim_prefix("foo:"), "bar");
```

```Rust
#![feature(trim_prefix_suffix)]

assert_eq!("foofoo".trim_prefix("foo"), "foo");
```

```Rust
#![feature(trim_prefix_suffix)]

// Prefix absent - returns original string
assert_eq!("foo:bar".trim_prefix("bar"), "foo:bar");
```

```Rust
#![feature(trim_prefix_suffix)]

// Method chaining example
assert_eq!("<https://example.com/>".trim_prefix('<').trim_suffix('>'), "https://example.com/");
```

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

### Get Mutable Underlying Array Reference

Source: https://docs.rs/mitsein/0.9.0/mitsein/heapless/vec1/type.Segment.html

Attempts to get a mutable reference to the underlying array if the specified size `N` matches the slice length.

```APIDOC
## GET /slice/as_mut_array/{N}

### Description
Gets a mutable reference to the slice’s underlying array.

### Method
GET

### Endpoint
/slice/as_mut_array/{N}

### Parameters
#### Path Parameters
- **N** (usize) - Required - The expected size of the array.

### Response
#### Success Response (200)
- **array_mut_ref** (&mut [T; N]) - An optional mutable reference to the underlying array if the size matches.

#### Response Example
```json
{
  "array_mut_ref": [1, 2, 3]
}
```
```

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

### Create Weak Pointer with Allocator

Source: https://docs.rs/mitsein/0.9.0/mitsein/rc1/type.WeakSlice1.html

Demonstrates creating a `Weak` pointer using a specific allocator and converting it back from raw pointers. This example requires the `allocator_api` nightly feature.

```rust
#![feature(allocator_api)]
use std::rc::{Rc, Weak};
use std::alloc::System;

let strong = Rc::new_in("hello".to_owned(), System);
let weak = Rc::downgrade(&strong);
let (raw, alloc) = weak.into_raw_with_allocator();

assert_eq!(1, Rc::weak_count(&strong));
assert_eq!("hello", unsafe { &*raw });

drop(unsafe { Weak::from_raw_in(raw, alloc) });
assert_eq!(0, Rc::weak_count(&strong));
```

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

### Create Arc with Uninitialized Contents

Source: https://docs.rs/mitsein/0.9.0/mitsein/sync1/type.ArcStr1.html

Demonstrates creating an `Arc` with uninitialized memory using `Arc::new_uninit` and then initializing it using `Arc::get_mut` and `write`.

```rust
use std::sync::Arc;

let mut five = Arc::<u32>::new_uninit();

// Deferred initialization:
Arc::get_mut(&mut five).unwrap().write(5);

let five = unsafe { five.assume_init() };

assert_eq!(*five, 5)
```

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

### Get Mutable Reference to Last Chunk

Source: https://docs.rs/mitsein/0.9.0/mitsein/array_vec1/type.Segment.html

Use `last_chunk_mut` to get a mutable reference to the last N items. Returns `None` if the slice is shorter than N.

```rust
let x = &mut [0, 1, 2];

if let Some(last) = x.last_chunk_mut::<2>() {
    last[0] = 10;
    last[1] = 20;
}
assert_eq!(x, &[0, 10, 20]);

assert_eq!(None, x.last_chunk_mut::<4>());
```

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

### TakeIfMany Struct Overview

Source: https://docs.rs/mitsein/0.9.0/mitsein/struct.TakeIfMany.html

Provides a summary of the TakeIfMany struct and its generic parameters.

```APIDOC
## Struct TakeIfMany

`pub struct TakeIfMany<'a, T, U, N = ()>
where
    T: MaybeEmpty + ?Sized,
{ /* private fields */ }`

Available on **crate features`arrayvec` or `alloc`** only.
```

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

### Get Mutable Reference to First Chunk

Source: https://docs.rs/mitsein/0.9.0/mitsein/array_vec1/type.Segment.html

Use `first_chunk_mut` to get a mutable reference to the first N items. Returns `None` if the slice is shorter than N.

```rust
let x = &mut [0, 1, 2];

if let Some(first) = x.first_chunk_mut::<2>() {
    first[0] = 5;
    first[1] = 4;
}
assert_eq!(x, &[5, 4, 2]);

assert_eq!(None, x.first_chunk_mut::<4>());
```

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

### Get Slice as Mutable Array Reference

Source: https://docs.rs/mitsein/0.9.0/mitsein/vec1/type.Segment.html

Attempts to get a mutable reference to the underlying array if the slice length exactly matches `N`. Returns `None` otherwise.

```rust
let mut slice = &mut [1, 2, 3];
let arr_mut_ref: Option<&mut [i32; 3]> = slice.as_mut_array();
assert!(arr_mut_ref.is_some());

let arr_mut_ref_wrong_size: Option<&mut [i32; 2]> = slice.as_mut_array();
assert!(arr_mut_ref_wrong_size.is_none());
```

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

### Create a Default Weak Pointer

Source: https://docs.rs/mitsein/0.9.0/mitsein/rc1/type.WeakSlice1.html

Shows how to create a `Weak` pointer using `Default::default()`. This results in a `Weak` pointer that does not allocate memory and always returns `None` when `upgrade` is called.

```rust
use std::rc::Weak;

let empty: Weak<i64> = Default::default();
assert!(empty.upgrade().is_none());
```

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

### Slice Split First Mut Method Example

Source: https://docs.rs/mitsein/0.9.0/mitsein/array_vec1/type.Segment.html

Demonstrates splitting a mutable slice into its first element and the rest.

```rust
let x = &mut [0, 1, 2];

if let Some((first, elements)) = x.split_first_mut() {
    *first = 3;
    elements[0] = 4;
    elements[1] = 5;
}
assert_eq!(x, &[3, 4, 5]);
```

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

### Get a raw pointer to the string slice's data

Source: https://docs.rs/mitsein/0.9.0/mitsein/str1/type.Str1.html

Use `as_ptr` to get a `*const u8` pointer to the first byte of the string slice. This pointer must not be written to.

```rust
let s = "Hello";
let ptr = s.as_ptr();
```

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

### Split Off Slice Starting with Third Element

Source: https://docs.rs/mitsein/0.9.0/mitsein/array_vec1/type.Segment.html

Use `split_off` with a range to remove and return a sub-slice starting from the third element. The original slice is updated to contain elements before the split point.

```rust
let mut slice: &[_] = &['a', 'b', 'c', 'd'];
let mut tail = slice.split_off(2..).unwrap();

assert_eq!(slice, &['a', 'b']);
assert_eq!(tail, &['c', 'd']);
```

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

### Box::new_uninit

Source: https://docs.rs/mitsein/0.9.0/mitsein/boxed1/type.BoxedStr1.html

Constructs a new Box with uninitialized contents. Useful for deferred initialization.

```APIDOC
## Box::new_uninit

### Description
Constructs a new box with uninitialized contents.

Available on non-`no_global_oom_handling` only.

### Method
Associated Function

### Endpoint
N/A (Rust function)

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
N/A

### Response
#### Success Response (200)
N/A (Rust function returns a value)

#### Response Example
N/A

### Examples
```rust
let mut five = Box::<u32>::new_uninit();
// Deferred initialization:
five.write(5);
let five = unsafe { five.assume_init() };

assert_eq!(*five, 5)
```
```

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

### Box Transformation and Lifecycle Methods

Source: https://docs.rs/mitsein/0.9.0/mitsein/boxed1/type.BoxedStr1.html

Methods for pinning, converting, and consuming Box instances.

```APIDOC
## pin_in

### Description
Constructs a new `Pin<Box<T, A>>`. If `T` does not implement `Unpin`, then `x` will be pinned in memory.

## into_boxed_slice

### Description
Converts a `Box<T>` into a `Box<[T]>` without allocating on the heap.

## into_inner

### Description
Consumes the `Box`, returning the wrapped value.

## take

### Description
Consumes the `Box` without consuming its allocation, returning the wrapped value and a `Box` to the uninitialized memory.
```

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

### Get Immutable Reference to Last Chunk

Source: https://docs.rs/mitsein/0.9.0/mitsein/array_vec1/type.Segment.html

Use `last_chunk` to get an immutable reference to the last N items. Returns `None` if the slice is shorter than N. Handles N=0 correctly.

```rust
let u = [10, 40, 30];
assert_eq!(Some(&[40, 30]), u.last_chunk::<2>());

let v: &[i32] = &[10];
assert_eq!(None, v.last_chunk::<2>());

let w: &[i32] = &[];
assert_eq!(Some(&[]), w.last_chunk::<0>());
```

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

### Rc::new_uninit_in

Source: https://docs.rs/mitsein/0.9.0/mitsein/rc1/type.RcStr1.html

Constructs a new Rc with uninitialized contents in the provided allocator. Memory is filled with 0 bytes. This is a nightly-only experimental API.

```APIDOC
## POST /api/users

### Description
Creates a new user in the system.

### Method
POST

### Endpoint
/api/users

### Parameters
#### Request Body
- **username** (string) - Required - The desired username.
- **email** (string) - Required - The user's email address.
- **password** (string) - Required - The user's password.

### Request Example
```json
{
  "username": "johndoe",
  "email": "john.doe@example.com",
  "password": "securepassword123"
}
```

### Response
#### Success Response (201)
- **id** (string) - The unique identifier for the newly created user.
- **username** (string) - The username of the created user.
- **email** (string) - The email of the created user.

#### Response Example
```json
{
  "id": "usr_12345abcde",
  "username": "johndoe",
  "email": "john.doe@example.com"
}
```
```

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

### Safely get a subslice of a string

Source: https://docs.rs/mitsein/0.9.0/mitsein/str1/type.Str1.html

Use `get` to retrieve a subslice of a string slice. It returns `Some(&str)` if the indices are valid and on UTF-8 character boundaries, and `None` otherwise. This is a non-panicking alternative to indexing.

```rust
let v = String::from("🗻∈🌏");

assert_eq!(Some("🗻"), v.get(0..4));

// indices not on UTF-8 sequence boundaries
assert!(v.get(1..).is_none());
assert!(v.get(..8).is_none());

// out of bounds
assert!(v.get(..42).is_none());
```

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

### strip_circumfix

Source: https://docs.rs/mitsein/0.9.0/mitsein/array_vec1/type.Segment.html

Returns a subslice with the prefix and suffix removed. If the slice starts with prefix and ends with suffix, returns the subslice after the prefix and before the suffix, wrapped in Some. If the slice does not start with prefix or does not end with suffix, returns None.

```APIDOC
## strip_circumfix

### Description
Returns a subslice with the prefix and suffix removed. If the slice starts with `prefix` and ends with `suffix`, returns the subslice after the prefix and before the suffix, wrapped in `Some`. If the slice does not start with `prefix` or does not end with `suffix`, returns `None`.

### Method
`strip_circumfix`

### Endpoint
N/A (Method on slice type)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```rust
let v = &[10, 20, 30, 40];
v.strip_circumfix(&[10], &[40])
```

### Response
#### Success Response (Some)
- **subslice** (&[T]) - The subslice after the prefix and before the suffix.

#### Success Response (None)
Returns `None` if the slice does not start with the `prefix` or does not end with the `suffix`.

#### Response Example
```json
{
  "example": "Some(&[20, 30][..])"
}
```
```

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

### Box::new_in with System allocator

Source: https://docs.rs/mitsein/0.9.0/mitsein/boxed1/type.BoxedStr1.html

Example of allocating a Box using a specific allocator, in this case, the `System` allocator, for fine-grained memory management.

```rust
#![feature(allocator_api)]

use std::alloc::System;

let five = Box::new_in(5, System);
```

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

### Box::from_raw Example

Source: https://docs.rs/mitsein/0.9.0/mitsein/boxed1/type.BoxedStr1.html

Recreates a Box from a raw pointer obtained via Box::into_raw. The raw pointer must point to memory allocated by the global allocator.

```rust
let x = Box::new(5);
let ptr = Box::into_raw(x);
let x = unsafe { Box::from_raw(ptr) };
```
Tokens:
Raw