Traits

Provides:

• SeekableIterator, SeekableLendingIterator, and SeekablePooledIterator traits, for circular iterators that can move backwards or forwards and seek.
• PooledIterator trait, for iterators that would normally be a lending iterator, but use a buffer pool to lend out multiple items at the same time.
• CursorIterator, CursorLendingIterator, and CursorPooledIterator traits, for circular iterators that can move backwards or forwards by one element.
• Seekable trait, with all the seeking methods required by the Seekable*Iterator traits.
• Comparator trait, for comparisons done to seek.
• LendItem and ItemToKey: helper traits for lending iterators.

Adapters to lender::Lender and lending_iterator::LendingIterator are provided for CursorLendingIterator and PooledIterator when the corresponding features are enabled.

Depending on features, MergingIter, PooledIter, and ThreadsafePooledIter iterator adapters are provided.

Semantics

The PooledIterator trait makes roughly the same semantic assumptions about the iterator as a normal iterator.

However, the Cursor*Iterator and Seekable*Iterator traits assume that an implementor is a circular iterator over some ordered collection; the iterator is made circular by adding a phantom element before the first element and after the last element of the ordered collection. The iterator is thus not a FusedIterator, as after iteration over the collection is completed, the iterator wraps back around to the start.

The PooledIterator and Cursor*Iterator traits do not expose any comparator that the ordered collection and iterator might be using, but the Seekable and Seekable*Iterator traits do expose it via a Comparator generic. An OrdComparator struct is provided that can compare keys that implement Ord, using their Ord implementation.

Features

• clone-behavior (enabled by default): Implements clone-behavior traits for OrdComparator.
• generic-container (enabled by default): Implements Comparator for containers of dyn Comparator, and for GenericContainer whenever GenericContainer wraps a container of a Comparator implementation.
• lender: provide adapters to lender::Lender.
• lending-iterator: provide adapters to lending_iterator::LendingIterator.
• alloc: provide MergingIter, which merges together several SeekableLendingIterators into one SeekableLendingIterator that iterates over all their items in order. Similar to adapters like itertools' kmerge, though somewhat more complicated in order to support switching the direction of iteration. Note: alloc isn't truly crucial for MergingIter; open an issue if you want it on no-alloc.
• std: doesn't do much alone. Enables alloc, as well as the std feature of a dependency.
• anchored-pool: provide PooledIter and ThreadsafePooledIter. PooledIter is an adapter from CursorLendingIterator to CursorPooledIterator, and ThreadsafePooledIter is a Send + Sync version. This feature enables std, though std isn't truly crucial for PooledIter; open an issue if you want it on no-std with alloc.
• anchored-pool-default: same as above, and enable the default feature flags of anchored-pool. The anchored-pool crate requires that either its kanal or crossbeam-channel feature is enabled; using the anchored-pool feature flag alone will result in a compile-time error unless you enable the kanal or crossbeam-channel flag yourself.

License

Licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE)
• MIT license (LICENSE-MIT)

at your option.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this crate by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.