### Lexicographical Sort Example

Source: https://docs.rs/alphanumeric-sort/latest/alphanumeric_sort

Demonstrates the default lexicographical sorting behavior in Rust, which can lead to unintuitive ordering for filenames with numbers.

```rust
let mut names = ["shot-2", "shot-1", "shot-11"];

names.sort();

assert_eq!(["shot-1", "shot-11", "shot-2"], names);
```

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

### Running Benchmarks

Source: https://docs.rs/alphanumeric-sort/latest/alphanumeric_sort/index.html

Provides the command to execute the benchmarks for the `alphanumeric-sort` crate using Cargo.

```bash
cargo bench
```

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

### Custom Sorting with `compare_path`

Source: https://docs.rs/alphanumeric-sort/latest/alphanumeric_sort

Illustrates how to use the `compare_path` function with `sort_by` for custom sorting of path slices. This method is less performant than `sort_path_slice` due to repeated data conversions.

```rust
use std::path::Path;

let mut paths = [Path::new("shot-2"), Path::new("shot-1"), Path::new("shot-11")];

paths.sort_by(|a, b| alphanumeric_sort::compare_path(a, b));

assert_eq!([Path::new("shot-1"), Path::new("shot-2"), Path::new("shot-11")], paths);
```

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

### Compare two Path in Rust

Source: https://docs.rs/alphanumeric-sort/latest/src/alphanumeric_sort/std_functions.rs.html

Compares two `Path` values by leveraging the `compare_os_str` function. This allows for consistent alphanumeric comparison of file paths.

```rust
/// Compare two `Path`.
#[inline]
pub fn compare_path<A: AsRef<Path>, B: AsRef<Path>>(a: A, b: B) -> Ordering {
    compare_os_str(a.as_ref(), b.as_ref())
}
```

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

### Sort Slice by Path Key (Fallback)

Source: https://docs.rs/alphanumeric-sort/latest/src/alphanumeric_sort/std_functions.rs.html

Provides a stable sorting mechanism for slices based on a path key. It uses a fallback comparison function for OsStr.

```rust
fn sort_slice_by_path_key_fallback<A, T: ?Sized + AsRef<Path>, F: FnMut(&A) -> &T>(
    slice: &mut [A],
    mut f: F,
) {
    slice.sort_by(|a, b| {
        compare_os_str_fallback(f(a).as_ref().as_os_str(), f(b).as_ref().as_os_str())
    });
}
```

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

### compare_path

Source: https://docs.rs/alphanumeric-sort/latest/src/alphanumeric_sort/std_functions.rs.html

Compares two Path types using the alphanumeric comparison of their OsStr representations.

```APIDOC
## compare_path

### Description
Compares two values that can be referenced as `Path` by utilizing the `compare_os_str` function on their underlying `OsStr` representations.

### Signature
```rust
pub fn compare_path<A: AsRef<Path>, B: AsRef<Path>>(a: A, b: B) -> Ordering
```

### Parameters
- `a`: The first value implementing `AsRef<Path>`.
- `b`: The second value implementing `AsRef<Path>`.

### Returns
An `Ordering` enum (`Less`, `Equal`, `Greater`) indicating the comparison result.
```

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

### Sorting a string slice

Source: https://docs.rs/alphanumeric-sort/latest/index.html

Demonstrates how to sort a slice of strings alphanumerically using `sort_str_slice`.

```APIDOC
## sort_str_slice

### Description
Sort a `str` slice.

### Usage Example
```rust
let mut names = ["shot-2", "shot-1", "shot-11"];
alphanumeric_sort::sort_str_slice(&mut names);
assert_eq!(["shot-1", "shot-2", "shot-11"], names);
```
```

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

### Sorting a path slice

Source: https://docs.rs/alphanumeric-sort/latest/index.html

Demonstrates how to sort a slice of `Path` objects alphanumerically using `sort_path_slice`.

```APIDOC
## sort_path_slice

### Description
Sort a `Path` slice.

### Usage Example
```rust
use std::path::Path;

let mut paths = [Path::new("shot-2"), Path::new("shot-1"), Path::new("shot-11")];
alphanumeric_sort::sort_path_slice(&mut paths);
assert_eq!([Path::new("shot-1"), Path::new("shot-2"), Path::new("shot-11")], paths);
```
```

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

### compare_os_str

Source: https://docs.rs/alphanumeric-sort/latest/src/alphanumeric_sort/std_functions.rs.html

Compares two OsStr types for alphanumeric sorting. Falls back to standard comparison if conversion to string fails.

```APIDOC
## compare_os_str

### Description
Compares two values that can be referenced as `OsStr` using alphanumeric sorting. If either `OsStr` cannot be converted to a string slice, it falls back to a standard `OsStr` comparison.

### Signature
```rust
pub fn compare_os_str<A: AsRef<OsStr>, B: AsRef<OsStr>>(a: A, b: B) -> Ordering
```

### Parameters
- `a`: The first value implementing `AsRef<OsStr>`.
- `b`: The second value implementing `AsRef<OsStr>`.

### Returns
An `Ordering` enum (`Less`, `Equal`, `Greater`) indicating the comparison result.
```

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

### Sorting a slice using a custom comparison function

Source: https://docs.rs/alphanumeric-sort/latest/index.html

Shows how to sort a slice of `Path` objects using the `compare_path` function with `sort_by`.

```APIDOC
## compare_path and sort_by

### Description
Compare two `Path` objects and use the comparison function with `sort_by` for custom sorting.

### Usage Example
```rust
use std::path::Path;

let mut paths = [Path::new("shot-2"), Path::new("shot-1"), Path::new("shot-11")];

paths.sort_by(|a, b| alphanumeric_sort::compare_path(a, b));

assert_eq!([Path::new("shot-1"), Path::new("shot-2"), Path::new("shot-11")], paths);
```

### Note
While functional, using `sort_*` functions is generally recommended for better performance over `compare_*` functions with `sort_by`.
```

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

### Function Signature for sort_slice_rev_by_os_str_key

Source: https://docs.rs/alphanumeric-sort/latest/alphanumeric_sort/fn.sort_slice_rev_by_os_str_key.html

This is the function signature for `sort_slice_rev_by_os_str_key`. It takes a mutable slice and a closure that extracts an OsStr key for sorting. Available on crate feature `std` only.

```rust
pub fn sort_slice_rev_by_os_str_key<A, T: ?Sized + AsRef<OsStr>, F: FnMut(&A) -> &T>(
    slice: &mut [A],
    f: F,
)
```

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

### Reversely sorting a string slice

Source: https://docs.rs/alphanumeric-sort/latest/index.html

Demonstrates how to sort a slice of strings in reverse alphanumeric order using `sort_str_slice_rev`.

```APIDOC
## sort_str_slice_rev

### Description
Reversely sort a `str` slice.

### Usage Example
```rust
let mut names = ["shot-2", "shot-1", "shot-11"];
alphanumeric_sort::sort_str_slice_rev(&mut names);
assert_eq!(["shot-11", "shot-2", "shot-1"], names);
```
```

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

### Reversely sorting a path slice

Source: https://docs.rs/alphanumeric-sort/latest/index.html

Demonstrates how to sort a slice of `Path` objects in reverse alphanumeric order using `sort_path_slice_rev`.

```APIDOC
## sort_path_slice_rev

### Description
Reversely sort a `Path` slice.

### Usage Example
```rust
use std::path::Path;

let mut paths = [Path::new("shot-2"), Path::new("shot-1"), Path::new("shot-11")];
alphanumeric_sort::sort_path_slice_rev(&mut paths);
assert_eq!([Path::new("shot-11"), Path::new("shot-2"), Path::new("shot-1")], paths);
```
```

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

### Alphanumeric Sort for String Slices

Source: https://docs.rs/alphanumeric-sort/latest/alphanumeric_sort

Shows how to use the `sort_str_slice` function from the alphanumeric_sort crate to achieve intuitive sorting for string slices containing numbers.

```rust
let mut names = ["shot-2", "shot-1", "shot-11"];

alphanumeric_sort::sort_str_slice(&mut names);

assert_eq!(["shot-1", "shot-2", "shot-11"], names);
```

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

### compare_str Function

Source: https://docs.rs/alphanumeric-sort/latest/alphanumeric_sort/fn.compare_str.html

Compares two strings lexicographically. It takes two arguments, `a` and `b`, which can be any type that implements `AsRef<str>`, and returns an `Ordering` enum value.

```APIDOC
## compare_str

### Description
Compare two strings.

### Signature
```rust
pub fn compare_str<A: AsRef<str>, B: AsRef<str>>(a: A, b: B) -> Ordering
```

### Parameters
* `a`: A type that implements `AsRef<str>`.
* `b`: A type that implements `AsRef<str>`.

### Returns
An `Ordering` enum value indicating the lexicographical order of the two strings.
```

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

### Function Signature for sort_slice_rev_by_path_key

Source: https://docs.rs/alphanumeric-sort/latest/alphanumeric_sort/fn.sort_slice_rev_by_path_key.html

This is the function signature for `sort_slice_rev_by_path_key`. It takes a mutable slice and a closure that extracts a Path key for sorting. Available on crate feature `std` only.

```rust
pub fn sort_slice_rev_by_path_key<A, T: ?Sized + AsRef<Path>, F: FnMut(&A) -> &T>(
    slice: &mut [A],
    f: F,
)
```

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

### Reverse Sort Slice by Path Key (Fallback)

Source: https://docs.rs/alphanumeric-sort/latest/src/alphanumeric_sort/std_functions.rs.html

Provides a reverse stable sorting mechanism for slices based on a path key. It uses a fallback comparison function for OsStr.

```rust
fn sort_slice_rev_by_path_key_fallback<A, T: ?Sized + AsRef<Path>, F: FnMut(&A) -> &T>(
    slice: &mut [A],
    mut f: F,
) {
    slice.sort_by(|a, b| {
        compare_os_str_fallback(f(b).as_ref().as_os_str(), f(a).as_ref().as_os_str())
    });
}
```

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

### compare_path

Source: https://docs.rs/alphanumeric-sort/latest/alphanumeric_sort/fn.compare_path.html

Compares two paths using alphanumeric sorting. This function is available only when the `std` feature is enabled.

```APIDOC
## compare_path

### Description
Compares two `Path` objects using alphanumeric sorting logic.

### Signature
```rust
pub fn compare_path<A: AsRef<Path>, B: AsRef<Path>>(a: A, b: B) -> Ordering
```

### Parameters
* `a`: The first path to compare. It must implement `AsRef<Path>`.
* `b`: The second path to compare. It must implement `AsRef<Path>`.

### Returns
An `Ordering` enum value indicating the lexicographical relationship between the two paths.

### Availability
Available on crate feature `std` only.
```

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

### Function Signature for sort_slice_rev_unstable_by_str_key

Source: https://docs.rs/alphanumeric-sort/latest/alphanumeric_sort/fn.sort_slice_rev_unstable_by_str_key.html

This is the function signature for `sort_slice_rev_unstable_by_str_key`. It takes a mutable slice and a closure that extracts a string key for comparison.

```rust
pub fn sort_slice_rev_unstable_by_str_key<A, T: ?Sized + AsRef<str>, F: FnMut(&A) -> &T>(
    slice: &mut [A],
    f: F,
)
```

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

### Reverse Unstable Sort Slice by Path Key (Fallback)

Source: https://docs.rs/alphanumeric-sort/latest/src/alphanumeric_sort/std_functions.rs.html

Provides a reverse unstable sorting mechanism for slices based on a path key. It uses a fallback comparison function for OsStr.

```rust
fn sort_slice_rev_unstable_by_path_key_fallback<A, T: ?Sized + AsRef<Path>, F: FnMut(&A) -> &T>(
    slice: &mut [A],
    mut f: F,
) {
    slice.sort_unstable_by(|a, b| {
        compare_os_str_fallback(f(b).as_ref().as_os_str(), f(a).as_ref().as_os_str())
    });
}
```

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

### Sort Slice by Permutation (Cycle Decomposition)

Source: https://docs.rs/alphanumeric-sort/latest/src/alphanumeric_sort/std_functions.rs.html

Sorts a slice in-place according to a given permutation vector using the cycle decomposition method.

```rust
fn sort_slice_ref_indexes<S>(slice: &mut [S], mut permutation: Vec<usize>) {
    // Cycle Decomposition
    for i in 0..permutation.len() {
        let mut current = i;

```

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

### Unstable Sort Slice by Path Key (Fallback)

Source: https://docs.rs/alphanumeric-sort/latest/src/alphanumeric_sort/std_functions.rs.html

Provides an unstable sorting mechanism for slices based on a path key. It uses a fallback comparison function for OsStr.

```rust
fn sort_slice_unstable_by_path_key_fallback<A, T: ?Sized + AsRef<Path>, F: FnMut(&A) -> &T>(
    slice: &mut [A],
    mut f: F,
) {
    slice.sort_unstable_by(|a, b| {
        compare_os_str_fallback(f(a).as_ref().as_os_str(), f(b).as_ref().as_os_str())
    });
}
```

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

### Disabling Default Features for No Std

Source: https://docs.rs/alphanumeric-sort/latest/alphanumeric_sort

Configuration snippet for Cargo.toml to compile the alphanumeric-sort crate without the `std` feature, enabling its use in `no_std` environments.

```toml
[dependencies.alphanumeric-sort]
version = "*"
default-features = false
```

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

### Convert String Pairs to Indexes (Reverse Stable)

Source: https://docs.rs/alphanumeric-sort/latest/src/alphanumeric_sort/std_functions.rs.html

Sorts a vector of (index, string) pairs by the string component in reverse order using a stable sort, then extracts the original indexes.

```rust
fn ref_index_str_pairs_to_ref_indexes_rev(
    mut ref_index_str_pairs: Vec<(usize, &str)>,
) -> Vec<usize> {
    ref_index_str_pairs.sort_by(|a, b| compare_str(b.1, a.1));

    ref_index_str_pairs_to_ref_indexes_inner(ref_index_str_pairs)
}
```

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

### Convert String Pairs to Indexes (Reverse Unstable)

Source: https://docs.rs/alphanumeric-sort/latest/src/alphanumeric_sort/std_functions.rs.html

Sorts a vector of (index, string) pairs by the string component in reverse order using an unstable sort, then extracts the original indexes.

```rust
fn ref_index_str_pairs_to_ref_indexes_rev_unstable(
    mut ref_index_str_pairs: Vec<(usize, &str)>,
) -> Vec<usize> {
    ref_index_str_pairs.sort_unstable_by(|a, b| compare_str(b.1, a.1));

    ref_index_str_pairs_to_ref_indexes_inner(ref_index_str_pairs)
}
```

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

### Function Signature for sort_slice_rev_unstable_by_path_key

Source: https://docs.rs/alphanumeric-sort/latest/alphanumeric_sort/fn.sort_slice_rev_unstable_by_path_key.html

This is the function signature for `sort_slice_rev_unstable_by_path_key`. It is available on the `std` crate feature only. It sorts a mutable slice in reverse order based on a Path key provided by a closure.

```rust
pub fn sort_slice_rev_unstable_by_path_key<A, T: ?Sized + AsRef<Path>, F: FnMut(&A) -> &T>(
    slice: &mut [A],
    f: F,
)
```

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

### Alphanumeric Sort for Path Slices

Source: https://docs.rs/alphanumeric-sort/latest/alphanumeric_sort

Demonstrates the usage of `sort_path_slice` for sorting slices of `std::path::Path` alphanumerically, ensuring correct ordering of paths with numerical components.

```rust
use std::path::Path;

let mut paths = [Path::new("shot-2"), Path::new("shot-1"), Path::new("shot-11")];

alphanumeric_sort::sort_path_slice(&mut paths);

assert_eq!([Path::new("shot-1"), Path::new("shot-2"), Path::new("shot-11")], paths);
```

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

### Inner sorting logic for Path keys

Source: https://docs.rs/alphanumeric-sort/latest/src/alphanumeric_sort/std_functions.rs.html

Internal helper function for sorting slices by Path keys. It attempts to convert Path to string slices and falls back to a byte-wise comparison if conversion fails.

```rust
fn sort_slice_by_path_key_inner<A, T: ?Sized + AsRef<Path>, F: FnMut(&A) -> &T>(
    slice: &mut [A],
    mut f: F,
    ref_index_str_pairs_to_ref_indexes: impl Fn(Vec<(usize, &str)>) -> Vec<usize>,
    fallback: impl Fn(&mut [A], F),
) {
    let mut use_str = true;

    let mut ref_index_str_pairs = Vec::with_capacity(slice.len());

    for (i, p) in slice.iter().enumerate() {
        let s = match f(p).as_ref().to_str() {
            Ok(s) => s,
            Err(_) => {
                use_str = false;
                break;
            },
        };

        ref_index_str_pairs.push((i, s));
    }

    if use_str {
        let ref_indexes = ref_index_str_pairs_to_ref_indexes(ref_index_str_pairs);

        sort_slice_ref_indexes(slice, ref_indexes);
    } else {
        fallback(slice, f);
    }
}
```

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

### compare_os_str

Source: https://docs.rs/alphanumeric-sort/latest/alphanumeric_sort/fn.compare_os_str.html

Compares two `OsStr` values. This function is available only when the `std` feature is enabled.

```APIDOC
## compare_os_str

### Description
Compares two `OsStr` values.

### Signature
```rust
pub fn compare_os_str<A: AsRef<OsStr>, B: AsRef<OsStr>>(a: A, b: B) -> Ordering
```

### Availability
Available on `crate feature`std` only.`
```

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

### Fallback stable sort for Path keys

Source: https://docs.rs/alphanumeric-sort/latest/src/alphanumeric_sort/std_functions.rs.html

Stable sorting fallback for Path keys when direct string conversion fails. It uses a byte-wise comparison.

```rust
fn sort_slice_by_path_key_fallback<A, T: ?Sized + AsRef<Path>, F: FnMut(&A) -> &T>(
    slice: &mut [A],
    mut f: F,
) {
    slice.sort_by(|a, b| compare_path_fallback(f(a), f(b)));
}
```

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

### sort_slice_rev_by_os_str_key

Source: https://docs.rs/alphanumeric-sort/latest/alphanumeric_sort/fn.sort_slice_rev_by_os_str_key.html

Reversely sort a slice by an `OsStr` key. This function is available on the `std` crate feature only.

```APIDOC
## Function sort_slice_rev_by_os_str_key

### Summary
```
pub fn sort_slice_rev_by_os_str_key<A, T: ?Sized + AsRef<OsStr>, F: FnMut(&A) -> &T>(
    slice: &mut [A],
    f: F,
)
```

Available on **crate feature`std`** only.

### Description
Reversely sort a slice by an `OsStr` key.
```

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

### sort_slice_rev_unstable_by_os_str_key

Source: https://docs.rs/alphanumeric-sort/latest/src/alphanumeric_sort/std_functions.rs.html

Sorts a slice unstable in reverse order by an OsStr key. May not preserve the order of equal elements.

```APIDOC
## sort_slice_rev_unstable_by_os_str_key

### Description
Sorts a slice of elements unstable in reverse order based on a key extracted as an `OsStr`. This sort may not preserve the relative order of elements that compare as equal.

### Signature
```rust
pub fn sort_slice_rev_unstable_by_os_str_key<A, T: ?Sized + AsRef<OsStr>, F: FnMut(&A) -> &T>(
    slice: &mut [A],
    f: F,
)
```

### Parameters
- `slice`: The mutable slice to sort.
- `f`: A closure that takes a reference to an element and returns a reference to an `OsStr` key.
```

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

### sort_slice_by_path_key Function Signature

Source: https://docs.rs/alphanumeric-sort/latest/alphanumeric_sort/fn.sort_slice_by_path_key.html

This function sorts a slice by a Path key. It requires the `std` feature to be enabled. The closure `f` extracts a reference to a Path from each element for comparison.

```rust
pub fn sort_slice_by_path_key<A, T: ?Sized + AsRef<Path>, F: FnMut(&A) -> &T>(
    slice: &mut [A],
    f: F,
)
```

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

### sort_slice_unstable_by_path_key

Source: https://docs.rs/alphanumeric-sort/latest/alphanumeric_sort/fn.sort_slice_unstable_by_path_key.html

Sorts a slice by a `Path` key, but may not preserve the order of equal elements. This function is available on `crate feature`std` only.

```APIDOC
## Function sort_slice_unstable_by_path_key

Source
```
pub fn sort_slice_unstable_by_path_key<A, T: ?Sized + AsRef<Path>, F: FnMut(&A) -> &T>(
    slice: &mut [A],
    f: F,
)
```

Available on **crate feature`std`** only.

### Description
Sort a slice by a `Path` key, but may not preserve the order of equal elements.
```

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

### Fallback reverse stable sort for Path keys

Source: https://docs.rs/alphanumeric-sort/latest/src/alphanumeric_sort/std_functions.rs.html

Reverse stable sorting fallback for Path keys when direct string conversion fails. It uses a byte-wise comparison in reverse.

```rust
fn sort_slice_rev_by_path_key_fallback<A, T: ?Sized + AsRef<Path>, F: FnMut(&A) -> &T>(
    slice: &mut [A],
    mut f: F,
) {
    slice.sort_by(|a, b| compare_path_fallback(f(b), f(a)));
}
```

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

### Convert String Pairs to Indexes (Stable)

Source: https://docs.rs/alphanumeric-sort/latest/src/alphanumeric_sort/std_functions.rs.html

Sorts a vector of (index, string) pairs by the string component using a stable sort, then extracts the original indexes.

```rust
fn ref_index_str_pairs_to_ref_indexes(mut ref_index_str_pairs: Vec<(usize, &str)>) -> Vec<usize> {
    ref_index_str_pairs.sort_by(|a, b| compare_str(a.1, b.1));

    ref_index_str_pairs_to_ref_indexes_inner(ref_index_str_pairs)
}
```

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

### Sort Slice Reverse by Path Key

Source: https://docs.rs/alphanumeric-sort/latest/src/alphanumeric_sort/std_functions.rs.html

Sorts a slice in reverse order using a Path key. This is a stable sort. Use when reverse order is needed and the order of equal elements must be maintained.

```rust
pub fn sort_slice_rev_by_path_key<A, T: ?Sized + AsRef<Path>, F: FnMut(&A) -> &T>(
    slice: &mut [A],
    f: F,
) {
    sort_slice_by_path_key_inner(
        slice,
        f,
        ref_index_str_pairs_to_ref_indexes_rev,
        sort_slice_rev_by_path_key_fallback,
    )
}
```

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

### sort_slice_rev_by_path_key

Source: https://docs.rs/alphanumeric-sort/latest/alphanumeric_sort/fn.sort_slice_rev_by_path_key.html

Reversely sort a slice by a `Path` key. This function is available on crate feature `std` only.

```APIDOC
## sort_slice_rev_by_path_key

### Description
Reversely sort a slice by a `Path` key.

### Signature
```rust
pub fn sort_slice_rev_by_path_key<A, T: ?Sized + AsRef<Path>, F: FnMut(&A) -> &T>(
    slice: &mut [A],
    f: F,
)
```

### Availability
Available on **crate feature`std`** only.
```

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

### compare_c_str

Source: https://docs.rs/alphanumeric-sort/latest/src/alphanumeric_sort/std_functions.rs.html

Compares two CStr types for alphanumeric sorting. Falls back to standard comparison if conversion to string fails.

```APIDOC
## compare_c_str

### Description
Compares two values that can be referenced as `CStr` using alphanumeric sorting. If either `CStr` cannot be converted to a string slice, it falls back to a standard `CStr` comparison.

### Signature
```rust
pub fn compare_c_str<A: AsRef<CStr>, B: AsRef<CStr>>(a: A, b: B) -> Ordering
```

### Parameters
- `a`: The first value implementing `AsRef<CStr>`.
- `b`: The second value implementing `AsRef<CStr>`.

### Returns
An `Ordering` enum (`Less`, `Equal`, `Greater`) indicating the comparison result.
```

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

### sort_slice_by_os_str_key

Source: https://docs.rs/alphanumeric-sort/latest/alphanumeric_sort/fn.sort_slice_by_os_str_key.html

Sorts a mutable slice in place based on a key extracted by a provided function. The key must be convertible to an `OsStr`. This function is available only when the `std` feature is enabled.

```APIDOC
## sort_slice_by_os_str_key

### Description
Sort a slice by an `OsStr` key.

### Signature
```rust
pub fn sort_slice_by_os_str_key<A, T: ?Sized + AsRef<OsStr>, F: FnMut(&A) -> &T>(
    slice: &mut [A],
    f: F,
)
```

### Constraints
Available on **crate feature`std`** only.
```

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

### sort_slice_rev_unstable_by_os_str_key

Source: https://docs.rs/alphanumeric-sort/latest/alphanumeric_sort/fn.sort_slice_rev_unstable_by_os_str_key.html

Reversely sort a slice by an `OsStr` key, but may not preserve the order of equal elements. This function is available only when the `std` crate feature is enabled.

```APIDOC
## Function sort_slice_rev_unstable_by_os_str_key

### Summary
```
pub fn sort_slice_rev_unstable_by_os_str_key<A, T: ?Sized + AsRef<OsStr>, F: FnMut(&A) -> &T>(
    slice: &mut [A],
    f: F,
)
```

Available on **crate feature`std`** only.

Reversely sort a slice by an `OsStr` key, but may not preserve the order of equal elements.
```

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

### Sort Slice by Path Key (Inner Logic)

Source: https://docs.rs/alphanumeric-sort/latest/src/alphanumeric_sort/std_functions.rs.html

Internal function to sort a slice based on a key extracted as a Path. It attempts to convert the path to a string for sorting and falls back to a custom comparison if conversion fails.

```rust
fn sort_slice_by_path_key_inner<A, T: ?Sized + AsRef<Path>, F: FnMut(&A) -> &T>(
    slice: &mut [A],
    mut f: F,
    ref_index_str_pairs_to_ref_indexes: impl Fn(Vec<(usize, &str)>) -> Vec<usize>,
    fallback: impl Fn(&mut [A], F),
) {
    let mut use_str = true;

    let mut ref_index_str_pairs = Vec::with_capacity(slice.len());

    for (i, p) in slice.iter().enumerate() {
        let s = match f(p).as_ref().to_str() {
            Some(s) => s,
            None => {
                use_str = false;
                break;
            },
        };

        ref_index_str_pairs.push((i, s));
    }

    if use_str {
        let ref_indexes = ref_index_str_pairs_to_ref_indexes(ref_index_str_pairs);

        sort_slice_ref_indexes(slice, ref_indexes);
    } else {
        fallback(slice, f);
    }
}
```

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

### sort_slice_unstable_by_os_str_key

Source: https://docs.rs/alphanumeric-sort/latest/src/alphanumeric_sort/std_functions.rs.html

Sorts a slice unstable by an OsStr key. May not preserve the order of equal elements.

```APIDOC
## sort_slice_unstable_by_os_str_key

### Description
Sorts a slice of elements unstable based on a key extracted as an `OsStr`. This sort may not preserve the relative order of elements that compare as equal.

### Signature
```rust
pub fn sort_slice_unstable_by_os_str_key<A, T: ?Sized + AsRef<OsStr>, F: FnMut(&A) -> &T>(
    slice: &mut [A],
    f: F,
)
```

### Parameters
- `slice`: The mutable slice to sort.
- `f`: A closure that takes a reference to an element and returns a reference to an `OsStr` key.
```

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

### Sort Path Slice

Source: https://docs.rs/alphanumeric-sort/latest/src/alphanumeric_sort/std_functions.rs.html

Sorts a slice of types that can be referenced as Path. It uses an unstable sorting algorithm.

```rust
pub fn sort_path_slice<P: AsRef<Path>>(slice: &mut [P]) {
    sort_slice_unstable_by_path_key(slice, |e| e.as_ref())
}
```

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

### Inner Sorting Logic for Slices by OsStr Key in Rust

Source: https://docs.rs/alphanumeric-sort/latest/src/alphanumeric_sort/std_functions.rs.html

The core internal logic for sorting slices by an `OsStr` key. It handles the conversion to string slices and delegates to either a specialized index sorting function or a fallback comparison.

```rust
fn sort_slice_by_os_str_key_inner<A, T: ?Sized + AsRef<OsStr>, F: FnMut(&A) -> &T>(
    slice: &mut [A],
    mut f: F,
    ref_index_str_pairs_to_ref_indexes: impl Fn(Vec<(usize, &str)>) -> Vec<usize>,
    fallback: impl Fn(&mut [A], F),
) {
    let mut use_str = true;

    let mut ref_index_str_pairs = Vec::with_capacity(slice.len());

    for (i, p) in slice.iter().enumerate() {
        let s = match f(p).as_ref().to_str() {
            Some(s) => s,
            None => {
                use_str = false;
                break;
            },
        };

        ref_index_str_pairs.push((i, s));
    }

    if use_str {
        let ref_indexes = ref_index_str_pairs_to_ref_indexes(ref_index_str_pairs);

        sort_slice_ref_indexes(slice, ref_indexes);
    } else {
        fallback(slice, f);
    }
}
```

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

### Fallback reverse unstable sort for Path keys

Source: https://docs.rs/alphanumeric-sort/latest/src/alphanumeric_sort/std_functions.rs.html

Reverse unstable sorting fallback for Path keys when direct string conversion fails. It uses a byte-wise comparison in reverse.

```rust
fn sort_slice_rev_unstable_by_path_key_fallback<A, T: ?Sized + AsRef<Path>, F: FnMut(&A) -> &T>(
    slice: &mut [A],
    mut f: F,
) {
    slice.sort_unstable_by(|a, b| compare_path_fallback(f(b), f(a)));
}
```

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

### compare_c_str

Source: https://docs.rs/alphanumeric-sort/latest/alphanumeric_sort/fn.compare_c_str.html

Compares two CStr objects. This function is available only when the `std` crate feature is enabled.

```APIDOC
## compare_c_str

### Description
Compare two `CStr`.

### Signature
```rust
pub fn compare_c_str<A: AsRef<CStr>, B: AsRef<CStr>>(a: A, b: B) -> Ordering
```

### Availability
Available on crate feature `std` only.
```

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

### Compare two OsStr in Rust

Source: https://docs.rs/alphanumeric-sort/latest/src/alphanumeric_sort/std_functions.rs.html

Compares two `OsStr` values. It attempts to convert them to strings for comparison using `compare_str`. If conversion fails, it falls back to a direct byte-wise comparison.

```rust
use core::cmp::Ordering;
use std::{
    ffi::{CStr, OsStr},
    path::Path,
};

use crate::compare_str;

/// Compare two `OsStr`.
#[inline]
pub fn compare_os_str<A: AsRef<OsStr>, B: AsRef<OsStr>>(a: A, b: B) -> Ordering {
    let sa = match a.as_ref().to_str() {
        Some(s) => s,
        None => {
            return compare_os_str_fallback(a, b);
        },
    };

    let sb = match b.as_ref().to_str() {
        Some(s) => s,
        None => {
            return compare_os_str_fallback(a, b);
        },
    };

    compare_str(sa, sb)
}

#[inline]
fn compare_os_str_fallback<A: AsRef<OsStr>, B: AsRef<OsStr>>(a: A, b: B) -> Ordering {
    a.as_ref().cmp(b.as_ref())
}
```

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

### sort_slice_rev_by_path_key

Source: https://docs.rs/alphanumeric-sort/latest/src/alphanumeric_sort/std_functions.rs.html

Sorts a slice by a Path key in reverse order, stably. The order of equal elements is preserved.

```APIDOC
## sort_slice_rev_by_path_key

### Description
Reversely sorts a slice by a `Path` key.

### Signature
```rust
pub fn sort_slice_rev_by_path_key<A, T: ?Sized + AsRef<Path>, F: FnMut(&A) -> &T>(
    slice: &mut [A],
    f: F,
)
```

### Parameters
- `slice`: A mutable slice of elements to be sorted.
- `f`: A closure that takes a reference to an element and returns a reference to a `Path` key.
```

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

### sort_slice_by_path_key

Source: https://docs.rs/alphanumeric-sort/latest/src/alphanumeric_sort/std_functions.rs.html

Sorts a slice by a Path key in a stable manner. The order of equal elements is preserved.

```APIDOC
## sort_slice_by_path_key

### Description
Sorts a slice by a `Path` key.

### Signature
```rust
pub fn sort_slice_by_path_key<A, T: ?Sized + AsRef<Path>, F: FnMut(&A) -> &T>(
    slice: &mut [A],
    f: F,
)
```

### Parameters
- `slice`: A mutable slice of elements to be sorted.
- `f`: A closure that takes a reference to an element and returns a reference to a `Path` key.
```

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

### Convert String Pairs to Indexes (Unstable)

Source: https://docs.rs/alphanumeric-sort/latest/src/alphanumeric_sort/std_functions.rs.html

Sorts a vector of (index, string) pairs by the string component using an unstable sort, then extracts the original indexes.

```rust
fn ref_index_str_pairs_to_ref_indexes_unstable(
    mut ref_index_str_pairs: Vec<(usize, &str)>,
) -> Vec<usize> {
    ref_index_str_pairs.sort_unstable_by(|a, b| compare_str(a.1, b.1));

    ref_index_str_pairs_to_ref_indexes_inner(ref_index_str_pairs)
}
```

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

### sort_slice_by_os_str_key

Source: https://docs.rs/alphanumeric-sort/latest/src/alphanumeric_sort/std_functions.rs.html

Sorts a slice stably by an OsStr key.

```APIDOC
## sort_slice_by_os_str_key

### Description
Sorts a slice of elements stably based on a key extracted as an `OsStr`. This sort preserves the relative order of elements that compare as equal.

### Signature
```rust
pub fn sort_slice_by_os_str_key<A, T: ?Sized + AsRef<OsStr>, F: FnMut(&A) -> &T>(
    slice: &mut [A],
    f: F,
)
```

### Parameters
- `slice`: The mutable slice to sort.
- `f`: A closure that takes a reference to an element and returns a reference to an `OsStr` key.
```

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

### sort_slice_rev_unstable_by_path_key

Source: https://docs.rs/alphanumeric-sort/latest/src/alphanumeric_sort/std_functions.rs.html

Sorts a slice by a Path key in reverse order, unstably. The order of equal elements is not guaranteed to be preserved.

```APIDOC
## sort_slice_rev_unstable_by_path_key

### Description
Reversely sorts a slice by a `Path` key, but may not preserve the order of equal elements.

### Signature
```rust
pub fn sort_slice_rev_unstable_by_path_key<A, T: ?Sized + AsRef<Path>, F: FnMut(&A) -> &T>(
    slice: &mut [A],
    f: F,
)
```

### Parameters
- `slice`: A mutable slice of elements to be sorted.
- `f`: A closure that takes a reference to an element and returns a reference to a `Path` key.
```

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

### Fallback Stable Sort for OsStr Key in Rust

Source: https://docs.rs/alphanumeric-sort/latest/src/alphanumeric_sort/std_functions.rs.html

A fallback sorting function for slices by `OsStr` key when direct string conversion is not possible. It uses `sort_by` with `compare_os_str_fallback`.

```rust
#[inline]
fn sort_slice_by_os_str_key_fallback<A, T: ?Sized + AsRef<OsStr>, F: FnMut(&A) -> &T>(
    slice: &mut [A],
    mut f: F,
) {
    slice.sort_by(|a, b| compare_os_str_fallback(f(a), f(b)));
}
```

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

### Sort Slice by Path Key

Source: https://docs.rs/alphanumeric-sort/latest/src/alphanumeric_sort/std_functions.rs.html

Sorts a slice using a Path key. This is a stable sort, preserving the relative order of equal elements. Use when the order of equal elements must be maintained.

```rust
pub fn sort_slice_by_path_key<A, T: ?Sized + AsRef<Path>, F: FnMut(&A) -> &T>(
    slice: &mut [A],
    f: F,
) {
    sort_slice_by_path_key_inner(
        slice,
        f,
        ref_index_str_pairs_to_ref_indexes,
        sort_slice_by_path_key_fallback,
    )
}
```

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

### Sort Slice Reverse Unstable by Path Key

Source: https://docs.rs/alphanumeric-sort/latest/src/alphanumeric_sort/std_functions.rs.html

Sorts a slice in reverse order using a Path key. This is an unstable sort. Use when reverse order is needed and the order of equal elements is not important.

```rust
pub fn sort_slice_rev_unstable_by_path_key<A, T: ?Sized + AsRef<Path>, F: FnMut(&A) -> &T>(
    slice: &mut [A],
    f: F,
) {
    sort_slice_by_path_key_inner(
        slice,
        f,
        ref_index_str_pairs_to_ref_indexes_rev_unstable,
        sort_slice_rev_unstable_by_path_key_fallback,
    )
}
```

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

### Fallback unstable sort for Path keys

Source: https://docs.rs/alphanumeric-sort/latest/src/alphanumeric_sort/std_functions.rs.html

Unstable sorting fallback for Path keys when direct string conversion fails. It uses a byte-wise comparison.

```rust
fn sort_slice_unstable_by_path_key_fallback<A, T: ?Sized + AsRef<Path>, F: FnMut(&A) -> &T>(
    slice: &mut [A],
    mut f: F,
) {
    slice.sort_unstable_by(|a, b| compare_path_fallback(f(a), f(b)));
}
```

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

### Sort Slice by String Key

Source: https://docs.rs/alphanumeric-sort/latest/src/alphanumeric_sort/lib.rs.html

Sorts a slice using a string key extracted by a closure. This is a stable sort, preserving the relative order of equal elements.

```rust
pub fn sort_slice_by_str_key<A, T: ?Sized + AsRef<str>, F: FnMut(&A) -> &T>(
    slice: &mut [A],
    mut f: F,
) {
    slice.sort_by(|a, b| compare_str(f(a), f(b)));
}
```

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

### Reverse Sort Slice by String Key

Source: https://docs.rs/alphanumeric-sort/latest/src/alphanumeric_sort/lib.rs.html

Sorts a slice in reverse order using a string key extracted by a closure. This is a stable sort.

```rust
pub fn sort_slice_rev_by_str_key<A, T: ?Sized + AsRef<str>, F: FnMut(&A) -> &T>(
    slice: &mut [A],
    mut f: F,
) {
    slice.sort_by(|a, b| compare_str(f(b), f(a)));
}
```

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

### Fallback Unstable Sort for OsStr Key in Rust

Source: https://docs.rs/alphanumeric-sort/latest/src/alphanumeric_sort/std_functions.rs.html

A fallback sorting function for slices by `OsStr` key when direct string conversion is not possible. It uses `sort_unstable_by` with `compare_os_str_fallback`.

```rust
#[inline]
fn sort_slice_unstable_by_os_str_key_fallback<A, T: ?Sized + AsRef<OsStr>, F: FnMut(&A) -> &T>(
    slice: &mut [A],
    mut f: F,
) {
    slice.sort_unstable_by(|a, b| compare_os_str_fallback(f(a), f(b)));
}
```

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

### Sorting String Slices

Source: https://docs.rs/alphanumeric-sort/latest/src/alphanumeric_sort/lib.rs.html

Sorts a mutable slice of strings using alphanumeric comparison. This is the recommended way to sort string slices for natural ordering.

```APIDOC
## sort_str_slice

### Description
Sorts a mutable slice of strings using alphanumeric comparison, ensuring that numbers within strings are treated numerically.

### Function Signature
```rust
pub fn sort_str_slice(slice: &mut [impl AsRef<str>])
```

### Example
```rust
let mut names = ["shot-2", "shot-1", "shot-11"];
alphanumeric_sort::sort_str_slice(&mut names);
assert_eq!(names, ["shot-1", "shot-2", "shot-11"]);
```
```

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

### Reverse Sort Path Slice

Source: https://docs.rs/alphanumeric-sort/latest/src/alphanumeric_sort/std_functions.rs.html

Reversely sorts a slice of types that can be referenced as Path. It uses an unstable sorting algorithm.

```rust
pub fn sort_path_slice_rev<P: AsRef<Path>>(slice: &mut [P]) {
    sort_slice_rev_unstable_by_path_key(slice, |e| e.as_ref())
}
```

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

### sort_slice_rev_unstable_by_str_key

Source: https://docs.rs/alphanumeric-sort/latest/alphanumeric_sort/fn.sort_slice_rev_unstable_by_str_key.html

Reversely sorts a slice by a `str` key, with no guarantee of preserving the order of equal elements.

```APIDOC
## Function sort_slice_rev_unstable_by_str_key

### Summary
```
pub fn sort_slice_rev_unstable_by_str_key<A, T: ?Sized + AsRef<str>, F: FnMut(&A) -> &T>(
    slice: &mut [A],
    f: F,
)
```

### Description
Reversely sort a slice by a `str` key, but may not preserve the order of equal elements.
```

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

### Fallback Reverse Stable Sort for OsStr Key in Rust

Source: https://docs.rs/alphanumeric-sort/latest/src/alphanumeric_sort/std_functions.rs.html

A fallback sorting function for slices in reverse order by `OsStr` key when direct string conversion is not possible. It uses `sort_by` with a reversed comparison.

```rust
#[inline]
fn sort_slice_rev_by_os_str_key_fallback<A, T: ?Sized + AsRef<OsStr>, F: FnMut(&A) -> &T>(
    slice: &mut [A],
    mut f: F,
) {
    slice.sort_by(|a, b| compare_os_str_fallback(f(b), f(a)));
}
```

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

### Reverse Unstable Sort Slice by String Key

Source: https://docs.rs/alphanumeric-sort/latest/src/alphanumeric_sort/lib.rs.html

Sorts a slice in reverse order using a string key extracted by a closure. This sort is unstable.

```rust
pub fn sort_slice_rev_unstable_by_str_key<A, T: ?Sized + AsRef<str>, F: FnMut(&A) -> &T>(
    slice: &mut [A],
    mut f: F,
) {
    slice.sort_unstable_by(|a, b| compare_str(f(b), f(a)));
}
```

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

### sort_slice_by_path_key

Source: https://docs.rs/alphanumeric-sort/latest/alphanumeric_sort/fn.sort_slice_by_path_key.html

Sorts a mutable slice in place using a provided function to extract a Path key for comparison. This function is available only when the `std` feature is enabled.

```APIDOC
## sort_slice_by_path_key

### Description
Sort a slice by a `Path` key.

### Signature
```rust
pub fn sort_slice_by_path_key<A, T: ?Sized + AsRef<Path>, F: FnMut(&A) -> &T>(
    slice: &mut [A],
    f: F,
)
```

### Constraints
Available on crate feature `std` only.
```

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

### sort_path_slice_rev

Source: https://docs.rs/alphanumeric-sort/latest/alphanumeric_sort/fn.sort_path_slice_rev.html

Reversely sort a `Path` slice. This function is available on `crate feature`std` only.

```APIDOC
## Function sort_path_slice_rev

### Summary
```
pub fn sort_path_slice_rev<P: AsRef<Path>>(slice: &mut [P])
```

Available on **crate feature`std`** only.

### Description
Reversely sort a `Path` slice.
```

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

### Sorting Path Slices

Source: https://docs.rs/alphanumeric-sort/latest/src/alphanumeric_sort/lib.rs.html

Sorts a mutable slice of paths using alphanumeric comparison. This function is useful for sorting file or directory names naturally.

```APIDOC
## sort_path_slice

### Description
Sorts a mutable slice of paths using alphanumeric comparison. This is particularly useful for sorting file system paths where numerical components should be ordered naturally.

### Function Signature
```rust
#[cfg(feature = "std")]
pub fn sort_path_slice(slice: &mut [impl AsRef<std::path::Path>])
```

### Example
```rust
use std::path::Path;

let mut paths = [Path::new("shot-2"), Path::new("shot-1"), Path::new("shot-11")];
alphanumeric_sort::sort_path_slice(&mut paths);
assert_eq!(paths, [Path::new("shot-1"), Path::new("shot-2"), Path::new("shot-11")]);
```
```

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

### Fallback Reverse Unstable Sort for OsStr Key in Rust

Source: https://docs.rs/alphanumeric-sort/latest/src/alphanumeric_sort/std_functions.rs.html

A fallback sorting function for slices in reverse order by `OsStr` key when direct string conversion is not possible. It uses `sort_unstable_by` with a reversed comparison.

```rust
#[inline]
fn sort_slice_rev_unstable_by_os_str_key_fallback<
    A,
    T: ?Sized + AsRef<OsStr>,
    F: FnMut(&A) -> &T,
>(
    slice: &mut [A],
    mut f: F,
) {
    slice.sort_unstable_by(|a, b| compare_os_str_fallback(f(b), f(a)));
}
```

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

### Fallback stable sort for CStr keys

Source: https://docs.rs/alphanumeric-sort/latest/src/alphanumeric_sort/std_functions.rs.html

Stable sorting fallback for CStr keys when direct string conversion fails. It uses a byte-wise comparison.

```rust
fn sort_slice_by_c_str_key_fallback<A, T: ?Sized + AsRef<CStr>, F: FnMut(&A) -> &T>(
    slice: &mut [A],
    mut f: F,
) {
    slice.sort_by(|a, b| compare_c_str_fallback(f(a), f(b)));
}
```

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

### sort_slice_rev_unstable_by_c_str_key

Source: https://docs.rs/alphanumeric-sort/latest/src/alphanumeric_sort/std_functions.rs.html

Sorts a slice by a CStr key in reverse order, unstably. The order of equal elements is not guaranteed to be preserved.

```APIDOC
## sort_slice_rev_unstable_by_c_str_key

### Description
Reversely sorts a slice by a `CStr` key, but may not preserve the order of equal elements.

### Signature
```rust
pub fn sort_slice_rev_unstable_by_c_str_key<A, T: ?Sized + AsRef<CStr>, F: FnMut(&A) -> &T>(
    slice: &mut [A],
    f: F,
)
```

### Parameters
- `slice`: A mutable slice of elements to be sorted.
- `f`: A closure that takes a reference to an element and returns a reference to a `CStr` key.
```

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

### Sort OsStr Slice

Source: https://docs.rs/alphanumeric-sort/latest/src/alphanumeric_sort/std_functions.rs.html

Sorts a slice of types that can be referenced as OsStr. It uses an unstable sorting algorithm.

```rust
pub fn sort_os_str_slice<S: AsRef<OsStr>>(slice: &mut [S]) {
    sort_slice_unstable_by_os_str_key(slice, |e| e.as_ref())
}
```

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

### sort_slice_rev_by_c_str_key

Source: https://docs.rs/alphanumeric-sort/latest/src/alphanumeric_sort/std_functions.rs.html

Sorts a slice by a CStr key in reverse order, stably. The order of equal elements is preserved.

```APIDOC
## sort_slice_rev_by_c_str_key

### Description
Reversely sorts a slice by a `CStr` key.

### Signature
```rust
pub fn sort_slice_rev_by_c_str_key<A, T: ?Sized + AsRef<CStr>, F: FnMut(&A) -> &T>(
    slice: &mut [A],
    f: F,
)
```

### Parameters
- `slice`: A mutable slice of elements to be sorted.
- `f`: A closure that takes a reference to an element and returns a reference to a `CStr` key.
```

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

### sort_slice_unstable_by_os_str_key

Source: https://docs.rs/alphanumeric-sort/latest/alphanumeric_sort/fn.sort_slice_unstable_by_os_str_key.html

Sorts a mutable slice using a provided function that extracts an `OsStr` key for comparison. This sort is unstable, meaning the relative order of equal elements is not guaranteed to be preserved. This function is available only when the `std` feature is enabled.

```APIDOC
## sort_slice_unstable_by_os_str_key

### Description
Sorts a mutable slice by an `OsStr` key, but may not preserve the order of equal elements. This function is available on `crate feature`std` only.

### Signature
```rust
pub fn sort_slice_unstable_by_os_str_key<A, T: ?Sized + AsRef<OsStr>, F: FnMut(&A) -> &T>(
    slice: &mut [A],
    f: F,
)
```

### Parameters
* `slice`: A mutable reference to the slice to be sorted.
* `f`: A closure that takes a reference to an element of the slice and returns a reference to an `OsStr` key to be used for sorting.
```

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

### Cycle Sort Implementation for Permutation

Source: https://docs.rs/alphanumeric-sort/latest/src/alphanumeric_sort/std_functions.rs.html

This code implements a cycle sort algorithm to sort a permutation in-place. It's used internally for specific sorting tasks where direct element swapping is required.

```rust
while permutation[current] != i {
            let next = permutation[current];

            slice.swap(current, next);

            permutation[current] = current;
            current = next;
        }

        permutation[current] = current;
    }
}
```