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
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141

//! Traits involving the length of a collection.

/// A trait for describing whether a collection is empty, i.e., its length is zero.
///
/// Checking whether a collection is empty should take a constant amount of time and space.
pub trait Empty {
    /// Returns whether the collection is empty.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use len_trait::Empty;
    ///
    /// fn check_empty<C: ?Sized + Empty>(collection: &C) {
    ///     assert!(collection.is_empty());
    /// }
    ///
    /// check_empty("");
    /// check_empty(&[1, 2, 3][..0]);
    /// check_empty(&"".to_string());
    /// ```
    fn is_empty(&self) -> bool;
}


/// A trait for describing the length of a collection.
///
/// The amount of data stored in a collection, i.e. the amount of space it requires in memory, is
/// directly proportional to its length. For this reason, `str` and other types measure their
/// lengths in code values (e.g. `u8`), not code points (e.g. `char`).
///
/// Obtaining the length of the collection must take a constant amount of time and space.
#[cfg_attr(feature = "cargo-clippy", allow(len_without_is_empty))]
// TODO: https://github.com/Manishearth/rust-clippy/issues/1740
pub trait Len: Empty {
    /// Returns the length of the collection.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use len_trait::Len;
    ///
    /// fn print_len<C: ?Sized + Len>(collection: &C) {
    ///     println!("{} units long", collection.len());
    /// }
    ///
    /// print_len("中文");         // 6 units long
    /// print_len(&[1, 2, 3][..]); // 3 units long
    /// ```
    fn len(&self) -> usize;
}

/// A trait for clearing collections.
///
/// A collection is cleared by dropping all of its data. After `clear` is called, the collection is
/// guaranteed to be empty.
///
/// Clearing a collection must take at most a linear amount of time and space.
pub trait Clear: Len {
    /// Clears the collection, dropping its elements and returning its length to zero.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use len_trait::Clear;
    ///
    /// struct Value(u32);
    /// impl Drop for Value {
    ///     fn drop(&mut self) {
    ///         println!("Dropped a {}", self.0)
    ///     }
    /// }
    ///
    /// fn check_clear<C: Clear>(mut collection: C) {
    ///     collection.clear();
    ///     assert!(collection.is_empty());
    /// }
    ///
    /// check_clear(vec![Value(12)]); // Prints "Dropped a 12"
    /// check_clear("Hello, world!".to_string());
    /// ```
    fn clear(&mut self);
}

/// A trait for modifying the length of a collection.
///
/// These methods must take at most a linear amount of time and space with respect to the number of
/// elements which are moved or dropped.
pub trait LenMut: Default + Clear {
    /// Truncates the collection to be no greater than `len` long, dropping elements as needed.
    ///
    /// If the collection is less than `len` long, do nothing.
    ///
    /// # Panics
    ///
    /// Panics if `len` is not valid according to the collection. For example, the implementation
    /// for `String` will panic if `len` does not lie on a character boundary.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use len_trait::LenMut;
    ///
    /// fn check_truncate<C: LenMut>(mut collection: C) {
    ///     let old_len = collection.len();
    ///     collection.truncate(5);
    ///     if old_len >= 5 {
    ///         assert_eq!(collection.len(), 5);
    ///     } else {
    ///         assert_eq!(collection.len(), old_len);
    ///     }
    /// }
    ///
    /// check_truncate("Hello, world!".to_string());
    /// check_truncate(vec![1, 2, 3]);
    /// ```
    fn truncate(&mut self, len: usize);

    /// Splits off the collection at the given index, returning the data past the index.
    ///
    /// # Panics
    ///
    /// Panics if `index > len`.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use len_trait::LenMut;
    ///
    /// fn check_split_off<C: LenMut>(mut collection: C) {
    ///     let old_len = collection.len();
    ///     let split = collection.split_off(5);
    ///     assert_eq!(collection.len(), 5);
    ///     assert_eq!(split.len(), old_len - 5);
    /// }
    ///
    /// check_split_off("Hello, world!".to_string());
    /// check_split_off(vec![1, 2, 3, 4, 5, 6, 7, 8, 9]);
    /// ```
    fn split_off(&mut self, index: usize) -> Self;
}