zrx_graph/graph/traversal/
iter.rs

1// Copyright (c) 2025 Zensical and contributors
2
3// SPDX-License-Identifier: MIT
4// Third-party contributions licensed under DCO
5
6// Permission is hereby granted, free of charge, to any person obtaining a copy
7// of this software and associated documentation files (the "Software"), to
8// deal in the Software without restriction, including without limitation the
9// rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
10// sell copies of the Software, and to permit persons to whom the Software is
11// furnished to do so, subject to the following conditions:
12
13// The above copyright notice and this permission notice shall be included in
14// all copies or substantial portions of the Software.
15
16// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18// FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE
19// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
21// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
22// IN THE SOFTWARE.
23
24// ----------------------------------------------------------------------------
25
26//! Iterator over a topological traversal.
27
28use super::Traversal;
29
30// ----------------------------------------------------------------------------
31// Structs
32// ----------------------------------------------------------------------------
33
34/// Iterator over a topological traversal.
35///
36/// This iterator consumes a [`Traversal`], emitting nodes in topological order.
37/// It offers a simplified API for synchronous iteration if nodes don't need to
38/// be deliberately completed, but can be considered done once the iterator
39/// has emitted them.
40#[derive(Debug)]
41pub struct IntoIter {
42    /// Traversal.
43    traversal: Traversal,
44}
45
46// ----------------------------------------------------------------------------
47// Trait implementations
48// ----------------------------------------------------------------------------
49
50impl Iterator for IntoIter {
51    type Item = usize;
52
53    /// Returns the next node.
54    #[inline]
55    fn next(&mut self) -> Option<Self::Item> {
56        let node = self.traversal.take()?;
57        self.traversal.complete(node).expect("invariant");
58        Some(node)
59    }
60
61    /// Returns the bounds of the traversal.
62    #[inline]
63    fn size_hint(&self) -> (usize, Option<usize>) {
64        (self.traversal.len(), None)
65    }
66}
67
68// ----------------------------------------------------------------------------
69
70impl IntoIterator for Traversal {
71    type Item = usize;
72    type IntoIter = IntoIter;
73
74    /// Creates an iterator over a topological traversal.
75    ///
76    /// This consumes the traversal and produces an iterator that automatically
77    /// completes each node after emitting it, allowing for convenient use in
78    /// for loops and iterator chains.
79    ///
80    /// # Examples
81    ///
82    /// ```
83    /// # use std::error::Error;
84    /// # fn main() -> Result<(), Box<dyn Error>> {
85    /// use zrx_graph::Graph;
86    ///
87    /// // Create graph builder and add nodes
88    /// let mut builder = Graph::builder();
89    /// let a = builder.add_node("a");
90    /// let b = builder.add_node("b");
91    /// let c = builder.add_node("c");
92    ///
93    /// // Create edges between nodes
94    /// builder.add_edge(a, b, 0)?;
95    /// builder.add_edge(b, c, 0)?;
96    ///
97    /// // Create graph from builder
98    /// let graph = builder.build();
99    ///
100    /// // Create iterator over topological traversal
101    /// for node in graph.traverse([a]) {
102    ///     println!("{node:?}");
103    /// }
104    /// # Ok(())
105    /// # }
106    /// ```
107    #[inline]
108    fn into_iter(self) -> Self::IntoIter {
109        IntoIter { traversal: self }
110    }
111}
zrx_graph/graph/traversal/iter.rs

zrx_graph/graph/traversal/
iter.rs
