prism3_value/
named_value.rs

1/*******************************************************************************
2 *
3 *    Copyright (c) 2025.
4 *    3-Prism 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 common_rs::util::value::{NamedValue, Value};
47///
48/// let named = NamedValue::new("flag", Value::Bool(true));
49/// // Call Value methods through Deref
50/// assert_eq!(named.as_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 common_rs::util::value::{NamedValue, Value};
78    ///
79    /// let named = NamedValue::new("timeout", Value::Int32(30));
80    /// assert_eq!(named.name(), "timeout");
81    /// ```
82    pub fn new(name: impl Into<String>, value: Value) -> Self {
83        Self {
84            name: name.into(),
85            value,
86        }
87    }
88
89    /// Get a reference to the name
90    ///
91    /// Returns a read-only name slice bound to this value.
92    ///
93    /// # Returns
94    ///
95    /// Returns a string slice `&str` of the name
96    ///
97    /// # Example
98    ///
99    /// ```rust
100    /// use common_rs::util::value::{NamedValue, Value};
101    ///
102    /// let named = NamedValue::new("host", Value::String("localhost".to_string()));
103    /// assert_eq!(named.name(), "host");
104    /// ```
105    pub fn name(&self) -> &str {
106        &self.name
107    }
108
109    /// Set a new name
110    ///
111    /// Updates the name bound to the current instance.
112    ///
113    /// # Parameters
114    ///
115    /// * `name` - The new name
116    ///
117    /// # Example
118    ///
119    /// ```rust
120    /// use common_rs::util::value::{NamedValue, Value};
121    ///
122    /// let mut named = NamedValue::new("old_name", Value::Bool(true));
123    /// named.set_name("new_name");
124    /// assert_eq!(named.name(), "new_name");
125    /// ```
126    pub fn set_name(&mut self, name: impl Into<String>) {
127        self.name = name.into();
128    }
129}
130
131impl Deref for NamedValue {
132    type Target = Value;
133
134    /// Dereference to the inner [`Value`]
135    ///
136    /// Allows direct invocation of methods on [`Value`], for example: `named.as_i32()`.
137    ///
138    /// # Returns
139    ///
140    /// Returns an immutable reference `&Value` to the inner value.
141    ///
142    /// # Example
143    ///
144    /// ```rust
145    /// use common_rs::util::value::{NamedValue, Value};
146    ///
147    /// let named = NamedValue::new("flag", Value::Bool(true));
148    /// // Call Value methods through Deref
149    /// assert_eq!(named.as_bool().unwrap(), true);
150    /// ```
151    fn deref(&self) -> &Self::Target {
152        &self.value
153    }
154}
155
156impl DerefMut for NamedValue {
157    /// Mutable dereference to the inner [`Value`]
158    ///
159    /// Allows in-place modification of the inner value (provided [`Value`] itself offers corresponding mutable methods).
160    ///
161    /// # Returns
162    ///
163    /// Returns a mutable reference `&mut Value` to the inner value.
164    fn deref_mut(&mut self) -> &mut Self::Target {
165        &mut self.value
166    }
167}
prism3_value/named_value.rs

prism3_value/
named_value.rs
