value_traits/traits/
iter.rs

1/*
2 * SPDX-FileCopyrightText: 2025 Tommaso Fontana
3 * SPDX-FileCopyrightText: 2025 Sebastiano Vigna
4 * SPDX-FileCopyrightText: 2025 Inria
5 *
6 * SPDX-License-Identifier: Apache-2.0 OR LGPL-2.1-or-later
7 */
8
9//! Traits for value-based iterators.
10
11/// A trait for obtaining a value-based iterator.
12///
13/// This trait necessary as all standard Rust containers already have
14/// [`IntoIterator`]-based methods for obtaining reference-based iterators.
15///
16/// Note that [`iter_value`](IterableByValue::iter_value) returns a standard
17/// iterator. However, the intended semantics is that the iterator will return
18/// values.
19///
20/// If you need to iterate from a given position, and you can implement such
21/// an iterator more efficiently, please consider [`IterableByValueFrom`].
22pub trait IterableByValue {
23    type Item;
24    type Iter<'a>: Iterator<Item = Self::Item>
25    where
26        Self: 'a;
27    /// Returns an iterator on values.
28    fn iter_value(&self) -> Self::Iter<'_>;
29}
30
31/// A trait for obtaining a value-based iterator starting from a given position.
32///
33/// This is an version of [`IterableByValue::iter_value`] that is useful for
34/// types in which obtaining a global iterator and skipping is expensive. Note
35/// that we cannot provide a skip-based default implementation because the
36/// returned type is not necessarily the same type as that returned by
37/// [`IterableByValue::iter_value`], but you are free to implement
38/// [`iter_value_from`](IterableByValueFrom::iter_value_from) that way.
39pub trait IterableByValueFrom: IterableByValue {
40    type IterFrom<'a>: Iterator<Item = <Self as IterableByValue>::Item>
41    where
42        Self: 'a;
43    /// Returns an iterator on values starting at the given position.
44    fn iter_value_from(&self, from: usize) -> Self::IterFrom<'_>;
45}
value_traits/traits/iter.rs

value_traits/traits/
iter.rs
