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

qubit_value/
named_value.rs
