seekable-iterator 0.4.0

Traits for iterators and lending iterators with seeking capabilities
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92

use core::cmp::Ordering;

#[cfg(feature = "clone-behavior")]
use clone_behavior::{DeepClone, MirroredClone, Speed};
#[cfg(feature = "generic-container")]
use generic_container::{FragileContainer, GenericContainer};


/// Interface for comparing keys (or entries) of a sorted collection.
///
/// The comparison function should provide a total order, just as [`Ord`] would. Additionally,
/// any clones of a comparator value should behave identically to the source comparator.
///
/// Note that none of the axioms that define a total order require that two elements which compare
/// as equal are "*truly*" equal in some more fundamental sense; that is, keys which are distinct
/// (perhaps according to an [`Eq`] implementation) may compare as equal in the provided total
/// order and corresponding equivalence relation.
///
/// Unsafe code is *not* allowed to rely on the correctness of implementations; that is, an
/// incorrect `Comparator` implementation may cause severe logic errors, but must not cause
/// memory unsafety.
pub trait Comparator<Key: ?Sized> {
    /// Compare two keys (or entries) in a sorted collection.
    ///
    /// This method is analogous to [`Ord::cmp`], and should provide a total order.
    ///
    /// Note that none of the axioms that define a total order require that two elements which
    /// compare as equal are "*truly*" equal in some more fundamental sense; that is, keys which
    /// are distinct (perhaps according to an [`Eq`] implementation) may compare as equal in
    /// the provided total order and corresponding equivalence relation.
    ///
    /// Unsafe code is *not* allowed to rely on the correctness of implementations; that is, an
    /// incorrect implementation may cause severe logic errors, but must not cause
    /// memory unsafety.
    #[must_use]
    fn cmp(&self, lhs: &Key, rhs: &Key) -> Ordering;
}

#[cfg(feature = "generic-container")]
impl<Key: ?Sized, C: FragileContainer<dyn Comparator<Key>>> Comparator<Key> for C {
    #[inline]
    fn cmp(&self, lhs: &Key, rhs: &Key) -> Ordering {
        // I'm slightly paranoid about the type coercion coercing to the wrong thing,
        // but doing this line-by-line is probably unnecessary.
        let inner = self.get_ref();
        let inner: &dyn Comparator<Key> = &*inner;
        inner.cmp(lhs, rhs)
    }
}

#[cfg(feature = "generic-container")]
impl<T, C, Key> Comparator<Key> for GenericContainer<T, C>
where
    T:   ?Sized + Comparator<Key>,
    C:   ?Sized + FragileContainer<T>,
    Key: ?Sized,
{
    #[inline]
    fn cmp(&self, lhs: &Key, rhs: &Key) -> Ordering {
        let inner = self.container.get_ref();
        let inner: &T = &inner;
        inner.cmp(lhs, rhs)
    }
}

/// A [`Comparator`] which uses keys' [`Ord`] implementations.
#[derive(Default, Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub struct OrdComparator;

impl<Key: ?Sized + Ord> Comparator<Key> for OrdComparator {
    /// Equivalent to `Ord::cmp(lhs, rhs)`.
    #[inline]
    fn cmp(&self, lhs: &Key, rhs: &Key) -> Ordering {
        Ord::cmp(lhs, rhs)
    }
}

#[cfg(feature = "clone-behavior")]
impl<S: Speed> DeepClone<S> for OrdComparator {
    #[inline]
    fn deep_clone(&self) -> Self {
        Self
    }
}

#[cfg(feature = "clone-behavior")]
impl<S: Speed> MirroredClone<S> for OrdComparator {
    #[inline]
    fn mirrored_clone(&self) -> Self {
        Self
    }
}