qubit_value/
named_value.rs

1/*******************************************************************************
2 *
3 *    Copyright (c) 2025 - 2026.
4 *    Haixing Hu, Qubit Co. Ltd.
5 *
6 *    All rights reserved.
7 *
8 ******************************************************************************/
9//! # Named Single Value
10//!
11//! Provides a named container for single values, allowing readable identifiers
12//! to be added to individual values in complex configurations or structures.
13//!
14//! Suitable for scenarios such as log annotation, configuration item encapsulation,
15//! and preserving strongly typed values in key-value pairs.
16//!
17//! # Author
18//!
19//! Haixing Hu
20
21use serde::{Deserialize, Serialize};
22use std::ops::{Deref, DerefMut};
23
24use super::value::Value;
25
26/// Named single value
27///
28/// Associates a human-readable name with a single [`Value`], facilitating identification,
29/// retrieval, and display in configurations, parameter passing, and complex data structures.
30///
31/// # Features
32///
33/// - Provides stable name identification for values
34/// - Automatically dereferences to the inner [`Value`] via `Deref`, allowing direct access to [`Value`] methods
35/// - Supports `serde` serialization and deserialization
36///
37/// # Use Cases
38///
39/// - Configuration item encapsulation (e.g., `"port"`, `"timeout"`, etc.)
40/// - Named output of key values in logs/monitoring
41/// - Quick location by name in collections
42///
43/// # Example
44///
45/// ```rust
46/// use qubit_value::{NamedValue, Value};
47///
48/// let named = NamedValue::new("flag", Value::Bool(true));
49/// // Call Value methods through Deref
50/// assert_eq!(named.to::<bool>().unwrap(), true);
51/// ```
52#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
53pub struct NamedValue {
54    /// Name of the value
55    name: String,
56    /// Content of the value
57    value: Value,
58}
59
60impl NamedValue {
61    /// Create a new named value
62    ///
63    /// Creates a binding instance between a name and a value.
64    ///
65    /// # Parameters
66    ///
67    /// * `name` - Name of the value
68    /// * `value` - Content of the value
69    ///
70    /// # Returns
71    ///
72    /// Returns a newly created [`NamedValue`] instance
73    ///
74    /// # Example
75    ///
76    /// ```rust
77    /// use qubit_value::{NamedValue, Value};
78    ///
79    /// let named = NamedValue::new("timeout", Value::Int32(30));
80    /// assert_eq!(named.name(), "timeout");
81    /// ```
82    #[inline]
83    pub fn new(name: impl Into<String>, value: Value) -> Self {
84        Self {
85            name: name.into(),
86            value,
87        }
88    }
89
90    /// Get a reference to the name
91    ///
92    /// Returns a read-only name slice bound to this value.
93    ///
94    /// # Returns
95    ///
96    /// Returns a string slice `&str` of the name
97    ///
98    /// # Example
99    ///
100    /// ```rust
101    /// use qubit_value::{NamedValue, Value};
102    ///
103    /// let named = NamedValue::new("host", Value::String("localhost".to_string()));
104    /// assert_eq!(named.name(), "host");
105    /// ```
106    #[inline]
107    pub fn name(&self) -> &str {
108        &self.name
109    }
110
111    /// Set a new name
112    ///
113    /// Updates the name bound to the current instance.
114    ///
115    /// # Parameters
116    ///
117    /// * `name` - The new name
118    ///
119    /// # Example
120    ///
121    /// ```rust
122    /// use qubit_value::{NamedValue, Value};
123    ///
124    /// let mut named = NamedValue::new("old_name", Value::Bool(true));
125    /// named.set_name("new_name");
126    /// assert_eq!(named.name(), "new_name");
127    /// ```
128    #[inline]
129    pub fn set_name(&mut self, name: impl Into<String>) {
130        self.name = name.into();
131    }
132
133    /// Consume the instance and return `(name, value)`.
134    #[inline]
135    pub fn into_parts(self) -> (String, Value) {
136        (self.name, self.value)
137    }
138}
139
140impl Deref for NamedValue {
141    type Target = Value;
142
143    /// Dereference to the inner [`Value`]
144    ///
145    /// Allows direct invocation of methods on [`Value`], for example: `named.to::<i32>()`.
146    ///
147    /// # Returns
148    ///
149    /// Returns an immutable reference `&Value` to the inner value.
150    ///
151    /// # Example
152    ///
153    /// ```rust
154    /// use qubit_value::{NamedValue, Value};
155    ///
156    /// let named = NamedValue::new("flag", Value::Bool(true));
157    /// // Call Value methods through Deref
158    /// assert_eq!(named.to::<bool>().unwrap(), true);
159    /// ```
160    #[inline]
161    fn deref(&self) -> &Self::Target {
162        &self.value
163    }
164}
165
166impl DerefMut for NamedValue {
167    /// Mutable dereference to the inner [`Value`]
168    ///
169    /// Allows in-place modification of the inner value (provided [`Value`] itself offers corresponding mutable methods).
170    ///
171    /// # Returns
172    ///
173    /// Returns a mutable reference `&mut Value` to the inner value.
174    #[inline]
175    fn deref_mut(&mut self) -> &mut Self::Target {
176        &mut self.value
177    }
178}
qubit_value/named_value.rs

qubit_value/
named_value.rs
