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

qubit_progress/model/
progress_stage.rs
