zrx_stream/stream/value/
position.rs

1// Copyright (c) 2025-2026 Zensical and contributors
2
3// SPDX-License-Identifier: MIT
4// All contributions are certified under the 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//! Position.
27
28use zrx_scheduler::Value;
29
30// ----------------------------------------------------------------------------
31// Structs
32// ----------------------------------------------------------------------------
33
34/// Position.
35///
36/// This data type attaches an index to a value, indicating its position within
37/// a sorted stream. It is primarily used in the context of [`Stream::sort`][],
38/// which keeps an internal store of items and updates their positions as the
39/// items entering the stream change.
40///
41/// Note that ordering of positions is determined by their index, and in case
42/// a tie-breaker is necessary, by the value itself.
43///
44/// [`Stream::sort`]: crate::stream::Stream::sort
45#[derive(Clone, Debug, PartialEq, Eq, PartialOrd, Ord)]
46pub struct Position<T> {
47    /// Index in sort order.
48    pub index: usize,
49    /// Associated value.
50    pub value: T,
51}
52
53// ----------------------------------------------------------------------------
54// Implementations
55// ----------------------------------------------------------------------------
56
57impl<T> Position<T> {
58    /// Creates a position.
59    ///
60    /// # Examples
61    ///
62    /// ```
63    /// use zrx_stream::value::Position;
64    ///
65    /// // Create position
66    /// let position = Position::new(0, "a");
67    /// ```
68    pub fn new(index: usize, value: T) -> Self {
69        Self { index, value }
70    }
71
72    /// Returns the index and associated value, consuming the position.
73    ///
74    /// # Examples
75    ///
76    /// ```
77    /// use zrx_stream::value::Position;
78    ///
79    /// // Create position
80    /// let position = Position::new(0, "a");
81    /// assert_eq!(
82    ///     position.into_parts(),
83    ///     (0, "a"),
84    /// );
85    /// ```
86    #[inline]
87    pub fn into_parts(self) -> (usize, T) {
88        (self.index, self.value)
89    }
90
91    /// Returns the associated value, consuming the position.
92    ///
93    /// ```
94    /// use zrx_stream::value::Position;
95    ///
96    /// // Create position
97    /// let position = Position::new(0, "a");
98    /// assert_eq!(position.into_value(), "a");
99    /// ```
100    #[inline]
101    pub fn into_value(self) -> T {
102        self.value
103    }
104}
105
106// ----------------------------------------------------------------------------
107// Trait implementations
108// ----------------------------------------------------------------------------
109
110impl<T> Value for Position<T> where T: Value {}
zrx_stream/stream/value/position.rs

zrx_stream/stream/value/
position.rs
