qubit_progress/model/
progress_stage.rs

1/*******************************************************************************
2 *
3 *    Copyright (c) 2025 - 2026 Haixing Hu.
4 *
5 *    SPDX-License-Identifier: Apache-2.0
6 *
7 *    Licensed under the Apache License, Version 2.0.
8 *
9 ******************************************************************************/
10/// Describes the current stage of a multi-stage operation.
11///
12/// # Examples
13///
14/// ```
15/// use qubit_progress::ProgressStage;
16///
17/// let stage = ProgressStage::new("verify", "Verify files")
18///     .with_index(2)
19///     .with_total_stages(4)
20///     .with_weight(0.25);
21///
22/// assert_eq!(stage.id(), "verify");
23/// assert_eq!(stage.name(), "Verify files");
24/// assert_eq!(stage.index(), Some(2));
25/// ```
26#[derive(Debug, Clone, PartialEq)]
27pub struct ProgressStage {
28    /// Stable machine-readable stage identifier.
29    id: String,
30    /// Human-readable stage name.
31    name: String,
32    /// Zero-based stage index when known.
33    index: Option<usize>,
34    /// Total number of stages when known.
35    total_stages: Option<usize>,
36    /// Relative stage weight when the caller uses weighted progress.
37    weight: Option<f64>,
38}
39
40impl ProgressStage {
41    /// Creates a stage with a stable id and display name.
42    ///
43    /// # Parameters
44    ///
45    /// * `id` - Stable machine-readable identifier.
46    /// * `name` - Human-readable stage name.
47    ///
48    /// # Returns
49    ///
50    /// A stage with no index, total stage count, or weight.
51    #[inline]
52    pub fn new(id: &str, name: &str) -> Self {
53        Self {
54            id: id.to_owned(),
55            name: name.to_owned(),
56            index: None,
57            total_stages: None,
58            weight: None,
59        }
60    }
61
62    /// Returns a copy configured with a zero-based stage index.
63    ///
64    /// # Parameters
65    ///
66    /// * `index` - Zero-based stage index.
67    ///
68    /// # Returns
69    ///
70    /// This stage with `index` recorded.
71    #[inline]
72    pub const fn with_index(mut self, index: usize) -> Self {
73        self.index = Some(index);
74        self
75    }
76
77    /// Returns a copy configured with the total stage count.
78    ///
79    /// # Parameters
80    ///
81    /// * `total_stages` - Total number of stages in the operation.
82    ///
83    /// # Returns
84    ///
85    /// This stage with `total_stages` recorded.
86    #[inline]
87    pub const fn with_total_stages(mut self, total_stages: usize) -> Self {
88        self.total_stages = Some(total_stages);
89        self
90    }
91
92    /// Returns a copy configured with a relative stage weight.
93    ///
94    /// # Parameters
95    ///
96    /// * `weight` - Relative stage weight used by callers that compute
97    ///   weighted total progress.
98    ///
99    /// # Returns
100    ///
101    /// This stage with `weight` recorded.
102    #[inline]
103    pub const fn with_weight(mut self, weight: f64) -> Self {
104        self.weight = Some(weight);
105        self
106    }
107
108    /// Returns the stable stage identifier.
109    ///
110    /// # Returns
111    ///
112    /// The machine-readable stage id.
113    #[inline]
114    pub fn id(&self) -> &str {
115        self.id.as_str()
116    }
117
118    /// Returns the human-readable stage name.
119    ///
120    /// # Returns
121    ///
122    /// The display name for this stage.
123    #[inline]
124    pub fn name(&self) -> &str {
125        self.name.as_str()
126    }
127
128    /// Returns the stage index when known.
129    ///
130    /// # Returns
131    ///
132    /// `Some(index)` when a zero-based stage index was supplied, otherwise
133    /// `None`.
134    #[inline]
135    pub const fn index(&self) -> Option<usize> {
136        self.index
137    }
138
139    /// Returns the total stage count when known.
140    ///
141    /// # Returns
142    ///
143    /// `Some(total)` when a total stage count was supplied, otherwise `None`.
144    #[inline]
145    pub const fn total_stages(&self) -> Option<usize> {
146        self.total_stages
147    }
148
149    /// Returns the relative stage weight when known.
150    ///
151    /// # Returns
152    ///
153    /// `Some(weight)` when a weight was supplied, otherwise `None`.
154    #[inline]
155    pub const fn weight(&self) -> Option<f64> {
156        self.weight
157    }
158}
qubit_progress/model/progress_stage.rs

qubit_progress/model/
progress_stage.rs
