extsort-lily

https://docs.rs/extsort-lily/
Admin
An efficient external sort implementation for Rust using merge sort with support for large datasets...
Tokens:12,900
Snippets:138
Trust Score:9.1
Update:5 months ago
Show doc for...
Tokens:
Raw
### ExtSortedIterator enumerate() Method

Source: https://docs.rs/extsort-lily/latest/extsort_lily/struct.ExtSortedIterator.html

Creates a new iterator that yields pairs of (index, element). The index starts at 0 and increments for each element yielded.

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

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

### ExtSortedIterator nth() Method

Source: https://docs.rs/extsort-lily/latest/extsort_lily/struct.ExtSortedIterator.html

Returns the nth element of the iterator. This method consumes elements up to and including the nth element. Subsequent calls will start from the element after the nth.

```rust
fn nth(&mut self, n: usize) -> Option<Self::Item>
```

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

### Create ExtSorter with default temporary directory

Source: https://docs.rs/extsort-lily/latest/extsort_lily/struct.ExtSorter.html

Initializes a new ExtSorter instance. It buffers a specified number of items in memory before writing them to temporary files. Use this when the default temporary directory is acceptable.

```rust
pub fn new(buffer_n_items: usize) -> Result<Self>
```

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

### ExtSorter::new_in

Source: https://docs.rs/extsort-lily/latest/src/extsort_lily/lib.rs.html

Creates a new `ExtSorter` with a specified buffer size and a custom directory for temporary files.

```APIDOC
## ExtSorter::new_in

### Description
Same as [`new`](fn@Self::new) but provides a directory to store temporary files instead of the system default.

### Method
`pub fn new_in<P: AsRef<Path>>(
    buffer_n_items: usize,
    tmp_dir: P,
) -> io::Result<Self>`

### Parameters
* `buffer_n_items` (usize) - The number of items to buffer in memory before sorting and writing to temporary files.
* `tmp_dir` (P: AsRef<Path>) - The path to the directory where temporary files will be stored.

### Returns
* `io::Result<Self>` - An `ExtSorter` instance or an I/O error.
```

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

### Create ExtSorter with custom temporary directory

Source: https://docs.rs/extsort-lily/latest/extsort_lily/struct.ExtSorter.html

Initializes a new ExtSorter instance, allowing you to specify a custom directory for temporary files. This is useful for managing disk space or performance.

```rust
pub fn new_in<P: AsRef<Path>>(buffer_n_items: usize, tmp_dir: P) -> Result<Self>
```

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

### Create an ExtSorter

Source: https://docs.rs/extsort-lily/latest/src/extsort_lily/lib.rs.html

Creates a new `ExtSorter` instance. It buffers a specified number of items in memory, sorts them, and writes them to temporary files. Uses the system's default temporary directory.

```rust
pub fn new(buffer_n_items: usize) -> io::Result<Self> {
    Ok(ExtSorter {
      buffer_n_items,
      tmp_dir: tempdir(None)?,
      phantom: PhantomData,
    })
  }
```

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

### ExtSorter::new_in

Source: https://docs.rs/extsort-lily/latest/extsort_lily/struct.ExtSorter.html

Creates a new ExtSorter instance, allowing specification of a directory for temporary files.

```APIDOC
## ExtSorter::new_in

### Description
Same as `new` but provides a directory to store temporary files instead of the system default.

### Method
`new_in`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
* **buffer_n_items** (usize) - Required - The number of items to buffer in memory.
* **tmp_dir** (P: AsRef<Path>) - Required - The directory path to store temporary files.

### Response
#### Success Response
- **Self** (Result<Self>) - An ExtSorter instance or an error.

### Example
```rust
use std::path::Path;
let tmp_path = Path::new("./tmp");
let sorter = ExtSorter::new_in(1000, tmp_path)?;
```
```

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

### Create Temporary Directory

Source: https://docs.rs/extsort-lily/latest/src/extsort_lily/lib.rs.html

Helper function to create a temporary directory. It uses `tempfile::Builder` and allows specifying a parent directory.

```rust
fn tempdir(path: Option<&Path>) -> io::Result<TempDir> {
  let mut builder = Builder::new();
  builder.prefix("extsort_lily");

  if let Some(p) = path {
    builder.tempdir_in(p)
  } else {
    builder.tempdir()
  }
}
```

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

### ExtSortedIterator step_by() Method

Source: https://docs.rs/extsort-lily/latest/extsort_lily/struct.ExtSortedIterator.html

Creates a new iterator that steps by a specified amount. The first element yielded will be the same as the original iterator, but subsequent elements will be skipped according to the step value.

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

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

### ExtSorter::new

Source: https://docs.rs/extsort-lily/latest/extsort_lily/struct.ExtSorter.html

Creates a new ExtSorter instance. It buffers a specified number of items in memory for sorting before writing to temporary files.

```APIDOC
## ExtSorter::new

### Description
Creates an `ExtSorter` to sort your data. It will buffer `buffer_n_items` items in memory and sort them, and then write them serialized into temporary files.

### Method
`new`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
* **buffer_n_items** (usize) - Required - The number of items to buffer in memory.

### Response
#### Success Response
- **Self** (Result<Self>) - An ExtSorter instance or an error.

### Example
```rust
let sorter = ExtSorter::new(1000)?;
```
```

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

### product

Source: https://docs.rs/extsort-lily/latest/extsort_lily/struct.ExtSortedIterator.html

Iterates over the entire iterator, multiplying all the elements.

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

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

### Parameters
* `self`: The iterator.

### Return Value
The product of the elements in the iterator.
```

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

### ExtSortedIterator::new Constructor

Source: https://docs.rs/extsort-lily/latest/src/extsort_lily/iter.rs.html

Constructor for `ExtSortedIterator`. It initializes the iterator by reading the first element from each provided reader and populating a min-heap (`BinaryHeap` with `Reverse`) to prepare for the merge sort process.

```rust
impl<T, R, W>
  where T: Sortable<W, R>,
        W: Write, R: Read,
{
  /// do merge sort on `readers`.
  pub fn new(mut readers: Vec<R>) -> Result<Self, T::Error> {
    let mut tips = BinaryHeap::with_capacity(readers.len());
    for (idx, r) in readers.iter_mut().enumerate() {
      let item = T::deserialize(r).unwrap()?;
      tips.push(Reverse((item, idx)));
    }

    Ok(Self {
      tips,
      readers,
      failed: false,
      phantom: PhantomData,
    })
  }
}

```

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

### ExtSortedIterator zip() Method

Source: https://docs.rs/extsort-lily/latest/extsort_lily/struct.ExtSortedIterator.html

Creates a new iterator that yields pairs of elements, one from each of the two zipped iterators. The iteration stops when the shorter of the two iterators is exhausted.

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

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

### ExtSortedIterator size_hint() Method

Source: https://docs.rs/extsort-lily/latest/extsort_lily/struct.ExtSortedIterator.html

Returns the lower and upper bounds of the remaining elements in the iterator. This can be useful for pre-allocating memory or estimating remaining work.

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

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

### ExtSortedIterator next_chunk() Method (Nightly)

Source: https://docs.rs/extsort-lily/latest/extsort_lily/struct.ExtSortedIterator.html

Advances the iterator and returns an array containing the next N values. This is an experimental API available only on nightly Rust versions.

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

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

### ExtSortedIterator peekable() Method

Source: https://docs.rs/extsort-lily/latest/extsort_lily/struct.ExtSortedIterator.html

Creates a new iterator that allows peeking at the next element without consuming it. The `peek()` and `peek_mut()` methods can be used to inspect the next item.

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

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

### ExtSortedIterator advance_by() Method (Nightly)

Source: https://docs.rs/extsort-lily/latest/extsort_lily/struct.ExtSortedIterator.html

Advances the iterator by a specified number of elements. Returns Ok(()) if successful, or Err(remaining) if the iterator is exhausted before advancing the full amount. This is an experimental API.

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

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

### any

Source: https://docs.rs/extsort-lily/latest/extsort_lily/struct.ExtSortedIterator.html

Tests if any element of the iterator matches a predicate.

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

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

### Parameters
* `self`: A mutable reference to the iterator.
* `f`: A closure that takes an item and returns `true` if it matches the predicate, `false` otherwise.

### Return Value
`true` if at least one element matches the predicate, `false` otherwise.
```

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

### cloned

Source: https://docs.rs/extsort-lily/latest/extsort_lily/struct.ExtSortedIterator.html

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

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

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

### Parameters
* `self`: The iterator yielding references to cloneable items.

### Return Value
A `Cloned` iterator that yields clones of the original elements.
```

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

### ExtSortedIterator intersperse_with() Method (Nightly)

Source: https://docs.rs/extsort-lily/latest/extsort_lily/struct.ExtSortedIterator.html

Creates a new iterator that inserts elements generated by a closure between each element of the original iterator. This is a nightly-only experimental API.

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

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

### ExtSortedIterator chain() Method

Source: https://docs.rs/extsort-lily/latest/extsort_lily/struct.ExtSortedIterator.html

Creates a new iterator that yields elements from the first iterator, followed by elements from the second iterator. Both iterators must yield the same item type.

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

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

### Write Chunk to Temporary File

Source: https://docs.rs/extsort-lily/latest/src/extsort_lily/lib.rs.html

A helper function to write a chunk of sorted data to a temporary file. It opens a file, creates a buffered writer, and serializes each item from the chunk.

```rust
fn write_chunk(&self, file: &Path, chunk: &mut Vec<T>) -> Result<(), T::Error> {
    let new_file = OpenOptions::new().create(true).write(true).truncate(true).open(file)?;
    let mut w = BufWriter::new(new_file);
    for s in chunk {
      s.serialize(&mut w)?;
    }

    Ok(())
  }
```

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

### into_iter

Source: https://docs.rs/extsort-lily/latest/extsort_lily/struct.ExtSortedIterator.html

Creates an iterator from an ExtSortedIterator value.

```APIDOC
## fn into_iter(self) -> I

### Description
Creates an iterator from a value.

### Method
`into_iter`

### Parameters
- `self`: The ExtSortedIterator value to convert into an iterator.
```

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

### ExtSortedIterator map() Method

Source: https://docs.rs/extsort-lily/latest/extsort_lily/struct.ExtSortedIterator.html

Creates a new iterator that applies a closure to each element of the original iterator, transforming the elements. The closure takes the original item and returns a new item of a potentially different type.

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

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

### copied

Source: https://docs.rs/extsort-lily/latest/extsort_lily/struct.ExtSortedIterator.html

Creates an iterator which copies all of its elements.

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

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

### Parameters
* `self`: The iterator yielding references to copyable items.

### Return Value
A `Copied` iterator that yields copies of the original elements.
```

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

### ExtSortedIterator for_each() Method

Source: https://docs.rs/extsort-lily/latest/extsort_lily/struct.ExtSortedIterator.html

Consumes the iterator, applying a closure to each element. This method is used for side effects, as it does not produce a new iterator or collect values.

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

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

### ExtSortedIterator intersperse() Method (Nightly)

Source: https://docs.rs/extsort-lily/latest/extsort_lily/struct.ExtSortedIterator.html

Creates a new iterator that inserts a separator element between each element of the original iterator. This is a nightly-only experimental API.

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

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

### partial_cmp_by

Source: https://docs.rs/extsort-lily/latest/extsort_lily/struct.ExtSortedIterator.html

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

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

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

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

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

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

### ExtSortedIterator next() Method

Source: https://docs.rs/extsort-lily/latest/extsort_lily/struct.ExtSortedIterator.html

Advances the iterator and returns the next value. The value returned is an Option containing a Result, which is either the next sorted item or an error.

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

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

### min_by_key

Source: https://docs.rs/extsort-lily/latest/extsort_lily/struct.ExtSortedIterator.html

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

```APIDOC
## fn min_by_key<B, F>(self, f: F) -> Option<Self::Item>
where
    B: Ord,
    Self: Sized,
    F: FnMut(&Self::Item) -> B,

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

### Parameters
* `self`: The iterator itself.
* `f`: A closure that takes a reference to an item and returns a value that implements `Ord`.

### Return Value
An `Option` containing the element that yields the minimum value according to the closure, or `None` if the iterator is empty.
```

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

### ExtSortedIterator filter_map() Method

Source: https://docs.rs/extsort-lily/latest/extsort_lily/struct.ExtSortedIterator.html

Creates a new iterator that both filters and maps elements. The closure should return an Option; if it returns Some(value), that value is yielded; if it returns None, the element is skipped.

```rust
fn filter_map<B, F>(self, f: F) -> FilterMap<Self, F>
where Self: Sized, F: FnMut(Self::Item) -> Option<B>,
```

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

### ExtSortedIterator skip_while() Method

Source: https://docs.rs/extsort-lily/latest/extsort_lily/struct.ExtSortedIterator.html

Creates a new iterator that skips elements as long as the provided closure returns true. Once the closure returns false, all subsequent elements are yielded, including the one that caused the condition to fail.

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

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

### Iterator Implementations for ExtSortedIterator

Source: https://docs.rs/extsort-lily/latest/extsort_lily/struct.ExtSortedIterator.html

Details the standard Iterator trait implementations for ExtSortedIterator, including methods like `next`, `next_chunk`, `size_hint`, and others.

```APIDOC
## Iterator Implementations for ExtSortedIterator

### Description
This section details the various methods provided by the `Iterator` trait as implemented for `ExtSortedIterator`.

### Methods

#### `type Item = Result<T, <T as Sortable<W, R>>::Error>`
*   **Description**: The type of elements yielded by the iterator. Each element is a `Result` containing either a successfully sorted item of type `T` or an error of type `<T as Sortable<W, R>>::Error`.

#### `fn next(&mut self) -> Option<Self::Item>`
*   **Description**: Advances the iterator and returns the next `Result<T, T::Error>`.

#### `fn next_chunk<const N: usize>(&mut self) -> Result<[Self::Item; N], IntoIter<Self::Item, N>>`
*   **Description**: (Nightly-only experimental API) Advances the iterator and returns an array of `N` items. This method is experimental and requires a nightly Rust toolchain.

#### `fn size_hint(&self) -> (usize, Option<usize>)`
*   **Description**: Returns the lower bound and an optional upper bound on the remaining number of elements in the iterator.

#### `fn count(self) -> usize`
*   **Description**: Consumes the iterator and returns the total number of elements it contained.

#### `fn last(self) -> Option<Self::Item>`
*   **Description**: Consumes the iterator and returns the last element yielded, if any.

#### `fn advance_by(&mut self, n: usize) -> Result<(), NonZero<usize>>`
*   **Description**: (Nightly-only experimental API) Advances the iterator by `n` elements. Returns `Ok(())` if successful, or `Err(NonZero<usize>)` indicating how many elements could not be advanced.

#### `fn nth(&mut self, n: usize) -> Option<Self::Item>`
*   **Description**: Returns the `n`-th element of the iterator (0-indexed), consuming elements before it.

#### `fn step_by(self, step: usize) -> StepBy<Self>`
*   **Description**: Creates a new iterator that yields elements from the original iterator at intervals of `step`.

#### `fn chain<U>(self, other: U) -> Chain<Self, <U as IntoIterator>::IntoIter>`
*   **Description**: Creates an iterator that yields elements from this iterator followed by elements from another iterator.

#### `fn zip<U>(self, other: U) -> Zip<Self, <U as IntoIterator>::IntoIter>`
*   **Description**: Creates an iterator that yields pairs of elements, one from each of the two zipped iterators.

#### `fn intersperse(self, separator: Self::Item) -> Intersperse<Self>`
*   **Description**: (Nightly-only experimental API) Creates an iterator that inserts a `separator` between elements of the original iterator.

#### `fn intersperse_with<G>(self, separator: G) -> IntersperseWith<Self, G>`
*   **Description**: (Nightly-only experimental API) Creates an iterator that inserts elements generated by a closure `separator` between elements of the original iterator.

#### `fn map<B, F>(self, f: F) -> Map<Self, F>`
*   **Description**: Creates an iterator that applies a closure `f` to each element, transforming it into a new type `B`.

#### `fn for_each<F>(self, f: F)`
*   **Description**: Executes a closure `f` for each element in the iterator, consuming the iterator.

#### `fn filter<P>(self, predicate: P) -> Filter<Self, P>`
*   **Description**: Creates an iterator that yields only the elements for which the closure `predicate` returns `true`.

#### `fn filter_map<B, F>(self, f: F) -> FilterMap<Self, F>`
*   **Description**: Creates an iterator that both filters and maps elements using a closure `f` that returns an `Option`.

#### `fn enumerate(self) -> Enumerate<Self>`
*   **Description**: Creates an iterator that yields pairs of `(index, element)` for each element.

#### `fn peekable(self) -> Peekable<Self>`
*   **Description**: Creates an iterator that allows peeking at the next element without consuming it.

#### `fn skip_while<P>(self, predicate: P) -> SkipWhile<Self, P>`
*   **Description**: Creates an iterator that skips elements as long as the closure `predicate` returns `true`.

```

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

### min

Source: https://docs.rs/extsort-lily/latest/extsort_lily/struct.ExtSortedIterator.html

Returns the minimum element of an iterator.

```APIDOC
## fn min(self) -> Option<Self::Item>
where
    Self: Sized,
    Self::Item: Ord,

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

### Parameters
* `self`: The iterator itself.

### Return Value
An `Option` containing the minimum element, or `None` if the iterator is empty.
```

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

### TryInto<U> for T

Source: https://docs.rs/extsort-lily/latest/extsort_lily/struct.ExtSortedIterator.html

Implementation of the TryInto trait for attempting conversion into another type.

```APIDOC
## impl<T, U> TryInto<U> for T

### Description
Provides functionality to attempt conversion from type `T` into type `U`.

### Associated Types
- `Error`: The type returned in the event of a conversion error. This is determined by the `Error` type of `U`'s `TryFrom<T>` implementation.

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

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

### unzip

Source: https://docs.rs/extsort-lily/latest/extsort_lily/struct.ExtSortedIterator.html

Converts an iterator of pairs into a pair of containers.

```APIDOC
## fn unzip<A, B, FromA, FromB>(self) -> (FromA, FromB)
where
    FromA: Default + Extend<A>,
    FromB: Default + Extend<B>,
    Self: Sized + Iterator<Item = (A, B)>,

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

### Parameters
* `self`: The iterator yielding pairs.

### Return Value
A tuple containing two containers, each collecting elements from one part of the pair.
```

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

### TryFrom<U> for T

Source: https://docs.rs/extsort-lily/latest/extsort_lily/struct.ExtSortedIterator.html

Implementation of the TryFrom trait for converting between types.

```APIDOC
## impl<T, U> TryFrom<U> for T

### Description
Provides functionality to attempt conversion from type `U` into type `T`.

### Associated Types
- `Error`: The type returned in the event of a conversion error. This is `Infallible` in this context, meaning errors are not expected.

### Methods
#### fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>
Performs the conversion from `value` of type `U` to type `T`.
```

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

### cmp_by

Source: https://docs.rs/extsort-lily/latest/extsort_lily/struct.ExtSortedIterator.html

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

```APIDOC
## fn cmp_by<I, F>(self, other: I, cmp: F) -> Ordering
where
    Self: Sized,
    I: IntoIterator,
    F: FnMut(Self::Item, <I as IntoIterator>::Item) -> Ordering,

### Description
Lexicographically compares the elements of this `Iterator` with those of another with respect to the specified comparison function.

### Experimental
This is a nightly-only experimental API.

### Parameters
* `self`: The first iterator.
* `other`: Another iterator or something that can be converted into an iterator.
* `cmp`: A closure that defines the comparison logic between elements of the two iterators.

### Return Value
An `Ordering` indicating whether the first iterator is less than, equal to, or greater than the second, based on the custom comparison function.
```

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

### all

Source: https://docs.rs/extsort-lily/latest/extsort_lily/struct.ExtSortedIterator.html

Tests if every element of the iterator matches a predicate.

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

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

### Parameters
* `self`: A mutable reference to the iterator.
* `f`: A closure that takes an item and returns `true` if it matches the predicate, `false` otherwise.

### Return Value
`true` if all elements match the predicate, `false` otherwise.
```

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

### try_reduce

Source: https://docs.rs/extsort-lily/latest/extsort_lily/struct.ExtSortedIterator.html

Reduces the elements to a single one by repeatedly applying a reducing operation. If the closure returns a failure, the failure is propagated back to the caller immediately. This is a nightly-only experimental API.

```APIDOC
## fn try_reduce<R>(
&mut self,
f: impl FnMut(Self::Item, Self::Item) -> R,
) -> <<R as Try>::Residual as Residual<Option<<R as Try>::Output>>>::TryType
where
    Self: Sized,
    R: Try<Output = Self::Item>,
    <R as Try>::Residual: Residual<Option<Self::Item>>,

### Description
Reduces the elements to a single one by repeatedly applying a reducing operation. If the closure returns a failure, the failure is propagated back to the caller immediately.

### Experimental
This is a nightly-only experimental API.

### Type Parameters
* `R`: The type returned by the reducing closure, which must implement `Try`.

### Parameters
* `self`: A mutable reference to the iterator.
* `f`: A closure that takes two items of the iterator and returns a `Try` type.

### Return Value
A type that represents the result of the reduction, potentially including a residual for failure cases.
```

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

### ExtSortedIterator::new

Source: https://docs.rs/extsort-lily/latest/src/extsort_lily/iter.rs.html

Constructs a new ExtSortedIterator by performing a merge sort on the provided readers. It initializes the internal state by reading the first element from each reader.

```APIDOC
/// The iterator type for producing results sorted by merge sort.
///
/// It produces `Result<T, T::Error>`s.
///
/// It can fail due to issues reading intermediate sorted chunks from disk, or due to
/// deserialization issues.
///
/// The writer `W` is not actually used by this struct.
pub struct ExtSortedIterator<T, R, W> {
  tips: BinaryHeap<Reverse<(T, usize)>>,
  readers: Vec<R>,
  failed: bool,
  phantom: PhantomData<W>,
}

impl<T, R, W>
  ExtSortedIterator<T, R, W>
where
  T: Sortable<W, R>,
  W: Write,
  R: Read,
{
  /// do merge sort on `readers`.
  pub fn new(mut readers: Vec<R>) -> Result<Self, T::Error> {
    let mut tips = BinaryHeap::with_capacity(readers.len());
    for (idx, r) in readers.iter_mut().enumerate() {
      let item = T::deserialize(r).unwrap()?;
      tips.push(Reverse((item, idx)));
    }

    Ok(Self {
      tips,
      readers,
      failed: false,
      phantom: PhantomData,
    })
  }
}
```

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

### try_find

Source: https://docs.rs/extsort-lily/latest/extsort_lily/struct.ExtSortedIterator.html

Applies a function to the elements of an iterator and returns the first true result or the first error. This is a nightly-only experimental API.

```APIDOC
## fn try_find<R>(
&mut self,
f: impl FnMut(&Self::Item) -> R,
) -> <<R as Try>::Residual as Residual<Option<Self::Item>>>::TryType
where
    Self: Sized,
    R: Try<Output = bool>,
    <R as Try>::Residual: Residual<Option<Self::Item>>,

### Description
Applies a function to the elements of an iterator and returns the first true result or the first error.

### Experimental
This is a nightly-only experimental API.

### Parameters
* `self`: A mutable reference to the iterator.
* `f`: A closure that takes a reference to an item and returns a `Try` type that resolves to a boolean.

### Return Value
A type that represents the result of the search, potentially including a residual for failure cases.
```

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

### position

Source: https://docs.rs/extsort-lily/latest/extsort_lily/struct.ExtSortedIterator.html

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

```APIDOC
## fn position<P>(&mut self, predicate: P) -> Option<usize>
where
    Self: Sized,
    P: FnMut(Self::Item) -> bool,

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

### Parameters
* `self`: A mutable reference to the iterator.
* `predicate`: A closure that takes an item and returns `true` if it matches the desired condition.

### Return Value
An `Option` containing the index of the first element that satisfies the predicate, or `None` if no such element is found.
```

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

### cmp

Source: https://docs.rs/extsort-lily/latest/extsort_lily/struct.ExtSortedIterator.html

Lexicographically compares the elements of this Iterator with those of another.

```APIDOC
## fn cmp<I>(self, other: I) -> Ordering
where
    I: IntoIterator<Item = Self::Item>,
    Self::Item: Ord,
    Self: Sized,

### Description
Lexicographically compares the elements of this `Iterator` with those of another.

### Parameters
* `self`: The first iterator.
* `other`: Another iterator or something that can be converted into an iterator.

### Return Value
An `Ordering` indicating whether the first iterator is less than, equal to, or greater than the second.
```

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

### ExtSortedIterator count() Method

Source: https://docs.rs/extsort-lily/latest/extsort_lily/struct.ExtSortedIterator.html

Consumes the iterator and returns the total number of elements it contained. This method will exhaust the iterator.

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

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

### min_by

Source: https://docs.rs/extsort-lily/latest/extsort_lily/struct.ExtSortedIterator.html

Returns the element that gives the minimum value with respect to the specified comparison function.

```APIDOC
## fn min_by<F>(self, compare: F) -> Option<Self::Item>
where
    Self: Sized,
    F: FnMut(&Self::Item, &Self::Item) -> Ordering,

### Description
Returns the element that gives the minimum value with respect to the specified comparison function.

### Parameters
* `self`: The iterator itself.
* `compare`: A closure that takes two references to items and returns an `Ordering`.

### Return Value
An `Option` containing the element that is considered minimum according to the comparison function, or `None` if the iterator is empty.
```

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

### Sort Data with ExtSorter

Source: https://docs.rs/extsort-lily/latest/src/extsort_lily/lib.rs.html

Sorts an iterator of `Sortable` items. The sort is unstable and returns an iterator that yields the sorted results. It first writes chunks to temporary files and then merges them.

```rust
pub fn sort<I>(
    &self, unsorted: I,
  ) -> Result<iter::ExtSortedIterator<T, BufReader<File>, BufWriter<File>>, T::Error>
  where
      I: Iterator<Item = T>,
  {
    let mut chunk_count = 0;

    {
      let mut current_count = 0;
      let mut chunk = Vec::new();

      // make the initial chunks on disk
      for seq in unsorted {
        current_count += 1;
        chunk.push(seq);
        if current_count >= self.buffer_n_items {
          chunk.sort_unstable();
          self.write_chunk(
            &self.tmp_dir.path().join(chunk_count.to_string()),
            &mut chunk,
          )?;
          chunk.clear();
          current_count = 0;
          chunk_count += 1;
        }
      }
      // write the last chunk
      if !chunk.is_empty() {
        chunk.sort_unstable();
        self.write_chunk(
          &self.tmp_dir.path().join(chunk_count.to_string()),
          &mut chunk,
        )?;
        chunk_count += 1;
      }
    }

    let readers = (0..chunk_count).map(|i| 
      File::open(self.tmp_dir.path().join(i.to_string())).map(BufReader::new)
    ).collect::<Result<Vec<_>, _>>()?;
    iter::ExtSortedIterator::new(readers)
  }
```

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

### ExtSortedIterator::new

Source: https://docs.rs/extsort-lily/latest/extsort_lily/struct.ExtSortedIterator.html

Constructs a new ExtSortedIterator by performing a merge sort on the provided readers. It returns a Result which can be an ExtSortedIterator or an error if sorting fails.

```APIDOC
## ExtSortedIterator::new

### Description
Performs merge sort on the provided readers.

### Method
`pub fn new(readers: Vec<R>) -> Result<Self, T::Error>`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
* `readers`: A vector of `R` types, representing the sources to be sorted.

### Response
#### Success Response
* `Result<Self, T::Error>`: An `Ok` variant containing the `ExtSortedIterator` if successful, or an `Err` variant with the associated error type `T::Error` if sorting fails.

### Request Example
```rust
// Assuming `readers` is a Vec<impl Read> and `T` is a suitable Sortable type
let sorted_iterator_result = ExtSortedIterator::<MySortableType, _, _>::new(readers);
```

### Response Example
```rust
// On success:
// Ok(ExtSortedIterator { ... })
// On failure:
// Err(T::Error { ... })
```
```

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

### Sortable Trait Documentation

Source: https://docs.rs/extsort-lily/latest/extsort_lily/trait.Sortable.html

This documentation outlines the Sortable trait, which is essential for types that need to be sorted. It includes details on the required associated type `Error` and the core methods `serialize` and `deserialize`.

```APIDOC
## Trait Sortable

### Description
Implement this trait for data to be sorted.

### Associated Types
#### type Error
Errors that may occur during serialization and deserialization. Note that it needs to implement `From<std::io::Error>`.

### Methods
#### fn serialize(&self, w: &mut W) -> Result<(), Self::Error>
Serialize itself and write into the writer.

#### fn deserialize(r: &mut R) -> Option<Result<Self, Self::Error>>
Read data and deserialize. If no more items to be read, return `None`.

### Dyn Compatibility
This trait is **not** dyn compatible.
```

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

### find

Source: https://docs.rs/extsort-lily/latest/extsort_lily/struct.ExtSortedIterator.html

Searches for an element of an iterator that satisfies a predicate.

```APIDOC
## fn find<P>(&mut self, predicate: P) -> Option<Self::Item>
where
    Self: Sized,
    P: FnMut(&Self::Item) -> bool,

### Description
Searches for an element of an iterator that satisfies a predicate.

### Parameters
* `self`: A mutable reference to the iterator.
* `predicate`: A closure that takes a reference to an item and returns `true` if it matches the desired condition.

### Return Value
An `Option` containing the first element that satisfies the predicate, or `None` if no such element is found.
```

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

### ExtSortedIterator Iterator Implementation

Source: https://docs.rs/extsort-lily/latest/src/extsort_lily/iter.rs.html

Implements the `Iterator` trait for `ExtSortedIterator`. The `next` method retrieves the smallest element from the heap, reads the next element from the corresponding reader, and pushes it back onto the heap, continuing the merge sort.

```rust
impl<T, R, W> Iterator for ExtSortedIterator<T, R, W>
where
    T: Sortable<W, R>,
    R: Read,
    W: Write,
{
    type Item = Result<T, T::Error>;

    fn next(&mut self) -> Option<Self::Item> {
        if self.failed {
            return None;
        }

        let Reverse((r, idx)) = self.tips.pop()?;
        match T::deserialize(&mut self.readers[idx]) {
          Some(Ok(n)) => {
            self.tips.push(Reverse((n, idx)));
          },
          Some(Err(e)) => {
            self.failed = true;
            return Some(Err(e));
          },
          None => { },
        };

        Some(Ok(r))
    }
}

```

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

### ExtSortedIterator Constructor

Source: https://docs.rs/extsort-lily/latest/extsort_lily/struct.ExtSortedIterator.html

Constructs a new ExtSortedIterator by performing a merge sort on the provided readers. This function can return an error if there are issues related to the Sortable trait implementation.

```rust
pub fn new(readers: Vec<R>) -> Result<Self, T::Error>
```

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

### ExtSortedIterator filter() Method

Source: https://docs.rs/extsort-lily/latest/extsort_lily/struct.ExtSortedIterator.html

Creates a new iterator that yields only the elements for which the provided closure returns true. The closure takes a reference to the item and returns a boolean.

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

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

### sum

Source: https://docs.rs/extsort-lily/latest/extsort_lily/struct.ExtSortedIterator.html

Sums the elements of an iterator.

```APIDOC
## fn sum<S>(self) -> S
where
    Self: Sized,
    S: Sum<Self::Item>,

### Description
Sums the elements of an iterator.

### Parameters
* `self`: The iterator.

### Return Value
The sum of the elements in the iterator.
```

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

### ExtSortedIterator::next

Source: https://docs.rs/extsort-lily/latest/src/extsort_lily/iter.rs.html

Advances the iterator and returns the next sorted item. It retrieves the smallest item from the internal heap, reads the next item from the corresponding reader, and updates the heap. Returns None if the iterator is exhausted or has encountered an error.

```APIDOC
impl<T, R, W>
  Iterator
  for ExtSortedIterator<T, R, W>
where
  T: Sortable<W, R>,
  R: Read,
  W: Write,
{
  type Item = Result<T, T::Error>;

  fn next(&mut self) -> Option<Self::Item> {
    if self.failed {
      return None;
    }

    let Reverse((r, idx)) = self.tips.pop()?;
    match T::deserialize(&mut self.readers[idx]) {
      Some(Ok(n)) => {
        self.tips.push(Reverse((n, idx)));
      },
      Some(Err(e)) => {
        self.failed = true;
        return Some(Err(e));
      },
      None => {},
    };

    Some(Ok(r))
  }
}
```

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

### max_by_key

Source: https://docs.rs/extsort-lily/latest/extsort_lily/struct.ExtSortedIterator.html

Returns the element that gives the maximum value from the specified function.

```APIDOC
## fn max_by_key<B, F>(self, f: F) -> Option<Self::Item>
where
    B: Ord,
    Self: Sized,
    F: FnMut(&Self::Item) -> B,

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

### Parameters
* `self`: The iterator itself.
* `f`: A closure that takes a reference to an item and returns a value that implements `Ord`.

### Return Value
An `Option` containing the element that yields the maximum value according to the closure, or `None` if the iterator is empty.
```

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

### ExtSortedIterator last() Method

Source: https://docs.rs/extsort-lily/latest/extsort_lily/struct.ExtSortedIterator.html

Consumes the iterator and returns the last element. If the iterator is empty, it returns None. This method will exhaust the iterator.

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

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

### array_chunks

Source: https://docs.rs/extsort-lily/latest/extsort_lily/struct.ExtSortedIterator.html

Returns an iterator over N elements of the iterator at a time. This is a nightly-only experimental API.

```APIDOC
## fn array_chunks<const N: usize>(self) -> ArrayChunks<Self, N>
where
    Self: Sized,

### Description
Returns an iterator over `N` elements of the iterator at a time.

### Experimental
This is a nightly-only experimental API.

### Type Parameters
* `N`: The size of the chunks.

### Parameters
* `self`: The iterator.

### Return Value
An `ArrayChunks` iterator that yields slices of size `N`.
```

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

### eq_by

Source: https://docs.rs/extsort-lily/latest/extsort_lily/struct.ExtSortedIterator.html

Determines if the elements of this Iterator are equal to those of another with respect to the specified equality function. This is a nightly-only experimental API.

```APIDOC
## fn eq_by<I, F>(self, other: I, eq: F) -> bool

### Description
Determines if the elements of this `Iterator` are equal to those of another with respect to the specified equality function. This is a nightly-only experimental API.

### Parameters
- `other`: An iterator to compare against.
- `eq`: A closure that takes two elements and returns a `bool` indicating equality.

### Returns
- `bool`: `true` if the elements are equal according to the provided function, `false` otherwise.
```

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

### partial_cmp

Source: https://docs.rs/extsort-lily/latest/extsort_lily/struct.ExtSortedIterator.html

Lexicographically compares the PartialOrd elements of this Iterator with those of another. The comparison works like short-circuit evaluation, returning a result without comparing the remaining elements.

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

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

### Parameters
- `other`: An iterator to compare against.

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

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

### Sort data using ExtSorter

Source: https://docs.rs/extsort-lily/latest/extsort_lily/struct.ExtSorter.html

Sorts an iterator of items of type T. It returns an iterator that yields the sorted results. The sort is unstable. Ensure T implements Sortable and handles potential errors.

```rust
pub fn sort<I>( &self, unsorted: I, ) -> Result<ExtSortedIterator<T, BufReader<File>, BufWriter<File>>, T::Error>
where I: Iterator<Item = T>,
```

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

### max_by

Source: https://docs.rs/extsort-lily/latest/extsort_lily/struct.ExtSortedIterator.html

Returns the element that gives the maximum value with respect to the specified comparison function.

```APIDOC
## fn max_by<F>(self, compare: F) -> Option<Self::Item>
where
    Self: Sized,
    F: FnMut(&Self::Item, &Self::Item) -> Ordering,

### Description
Returns the element that gives the maximum value with respect to the specified comparison function.

### Parameters
* `self`: The iterator itself.
* `compare`: A closure that takes two references to items and returns an `Ordering`.

### Return Value
An `Option` containing the element that is considered maximum according to the comparison function, or `None` if the iterator is empty.
```

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

### ExtSorter::sort

Source: https://docs.rs/extsort-lily/latest/extsort_lily/struct.ExtSorter.html

Sorts an iterator of items and returns an iterator that yields the sorted results. The sort is unstable.

```APIDOC
## ExtSorter::sort

### Description
Sorts the data provided by an iterator. It returns an iterator to produce sorted results. The sort is unstable.

### Method
`sort`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
* **unsorted** (I: Iterator<Item = T>) - Required - An iterator providing the unsorted data items.

### Response
#### Success Response
- **ExtSortedIterator<T, BufReader<File>, BufWriter<File>>** (Result<ExtSortedIterator<T, BufReader<File>, BufWriter<File>>, T::Error>) - An iterator yielding sorted results, or an error from the underlying sortable type.

### Example
```rust
let data = vec![3, 1, 4, 1, 5, 9, 2, 6];
let sorted_iterator = sorter.sort(data.into_iter())?;
for item in sorted_iterator {
    // Process sorted item
}
```
```

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

### max

Source: https://docs.rs/extsort-lily/latest/extsort_lily/struct.ExtSortedIterator.html

Returns the maximum element of an iterator.

```APIDOC
## fn max(self) -> Option<Self::Item>
where
    Self: Sized,
    Self::Item: Ord,

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

### Parameters
* `self`: The iterator itself.

### Return Value
An `Option` containing the maximum element, or `None` if the iterator is empty.
```

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

### ExtSortedIterator Struct Definition

Source: https://docs.rs/extsort-lily/latest/src/extsort_lily/iter.rs.html

Defines the `ExtSortedIterator` struct, which manages multiple readers and a binary heap to perform an external merge sort. It holds the state for the ongoing sorting process.

```rust
/// The iterator type for producing results sorted by merge sort.
///
/// It produces `Result<T, T::Error>`s.
///
/// It can fail due to issues reading intermediate sorted chunks from disk, or due to
/// deserialization issues.
///
/// The writer `W` is not actually used by this struct.
pub struct ExtSortedIterator<T, R, W> {
  tips: BinaryHeap<Reverse<(T, usize)>>,
  readers: Vec<R>,
  failed: bool,
  phantom: PhantomData<W>,
}

```

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

### find_map

Source: https://docs.rs/extsort-lily/latest/extsort_lily/struct.ExtSortedIterator.html

Applies a function to the elements of an iterator and returns the first non-none result.

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

### Description
Applies a function to the elements of an iterator and returns the first non-none result.

### Parameters
* `self`: A mutable reference to the iterator.
* `f`: A closure that takes an item and returns an `Option<B>`.

### Return Value
An `Option` containing the first non-`None` result produced by the closure, or `None` if the closure never returns a non-`None` value.
```

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

### le

Source: https://docs.rs/extsort-lily/latest/extsort_lily/struct.ExtSortedIterator.html

Determines if the elements of this Iterator are lexicographically less than or equal to those of another.

```APIDOC
## fn le<I>(self, other: I) -> bool

### Description
Determines if the elements of this `Iterator` are lexicographically less than or equal to those of another.

### Parameters
- `other`: An iterator to compare against.

### Returns
- `bool`: `true` if the elements are lexicographically less than or equal to, `false` otherwise.
```

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

### lt

Source: https://docs.rs/extsort-lily/latest/extsort_lily/struct.ExtSortedIterator.html

Determines if the elements of this Iterator are lexicographically less than those of another.

```APIDOC
## fn lt<I>(self, other: I) -> bool

### Description
Determines if the elements of this `Iterator` are lexicographically less than those of another.

### Parameters
- `other`: An iterator to compare against.

### Returns
- `bool`: `true` if the elements are lexicographically less than, `false` otherwise.
```

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

### gt

Source: https://docs.rs/extsort-lily/latest/extsort_lily/struct.ExtSortedIterator.html

Determines if the elements of this Iterator are lexicographically greater than those of another.

```APIDOC
## fn gt<I>(self, other: I) -> bool

### Description
Determines if the elements of this `Iterator` are lexicographically greater than those of another.

### Parameters
- `other`: An iterator to compare against.

### Returns
- `bool`: `true` if the elements are lexicographically greater than, `false` otherwise.
```

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

### ExtSortedIterator Struct Definition

Source: https://docs.rs/extsort-lily/latest/extsort_lily/struct.ExtSortedIterator.html

Defines the ExtSortedIterator struct, which is used for producing results sorted by merge sort. It can fail due to issues reading intermediate sorted chunks from disk or deserialization problems. The writer W is not used by this struct.

```rust
pub struct ExtSortedIterator<T, R, W> { /* private fields */ }
```

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

### is_sorted

Source: https://docs.rs/extsort-lily/latest/extsort_lily/struct.ExtSortedIterator.html

Checks if the elements of this iterator are sorted.

```APIDOC
## fn is_sorted(self) -> bool

### Description
Checks if the elements of this iterator are sorted.

### Returns
- `bool`: `true` if the elements are sorted, `false` otherwise.
```

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

### eq

Source: https://docs.rs/extsort-lily/latest/extsort_lily/struct.ExtSortedIterator.html

Determines if the elements of this Iterator are equal to those of another.

```APIDOC
## fn eq<I>(self, other: I) -> bool

### Description
Determines if the elements of this `Iterator` are equal to those of another.

### Parameters
- `other`: An iterator to compare against.

### Returns
- `bool`: `true` if the elements are equal, `false` otherwise.
```

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

### is_sorted_by_key

Source: https://docs.rs/extsort-lily/latest/extsort_lily/struct.ExtSortedIterator.html

Checks if the elements of this iterator are sorted using the given key extraction function.

```APIDOC
## fn is_sorted_by_key<F, K>(self, f: F) -> bool

### Description
Checks if the elements of this iterator are sorted using the given key extraction function.

### Parameters
- `f`: A closure that takes an element and returns a key of a type that implements `PartialOrd`.

### Returns
- `bool`: `true` if the elements are sorted based on the extracted keys, `false` otherwise.
```
Tokens:
Raw