qubit_value/multi_values/multi_values_constructor.rs
1// =============================================================================
2// Copyright (c) 2025 - 2026 Haixing Hu.
3//
4// SPDX-License-Identifier: Apache-2.0
5//
6// Licensed under the Apache License, Version 2.0.
7// =============================================================================
8
9//! `From<T>` implementations for supported `MultiValues` input forms.
10
11use super::multi_values::MultiValues;
12
13/// Collects borrowed string values into owned strings.
14///
15/// # Type Parameters
16///
17/// * `I` - Iterator source yielding borrowed UTF-8 strings.
18///
19/// # Parameters
20///
21/// * `values` - Borrowed strings to copy into the returned collection.
22///
23/// # Returns
24///
25/// Owned strings in the source iteration order.
26#[must_use]
27#[inline]
28fn collect_strings<'a, I>(values: I) -> Vec<String>
29where
30 I: IntoIterator<Item = &'a str>,
31{
32 values.into_iter().map(str::to_owned).collect()
33}
34
35/// Implements owned collection conversions from the shared value table.
36macro_rules! impl_multi_values_from_table {
37 (
38 ;
39 $(
40 (
41 [$($cfg:meta),*],
42 $variant:ident,
43 $type:ty,
44 $data_type:expr,
45 $materialization:ident,
46 $json_class:ident,
47 $number_projection:ident,
48 $value_doc:literal,
49 $multi_doc:literal
50 $(, $_wire:tt)*
51 )
52 ),+ $(,)?
53 ) => {
54 $(
55 $(#[$cfg])*
56 $(#[cfg_attr(docsrs, doc($cfg))])*
57 impl From<$type> for MultiValues {
58 /// Creates a one-item collection by taking ownership of `value`.
59 ///
60 /// # Parameters
61 ///
62 /// * `value` - Element moved into the collection.
63 ///
64 /// # Returns
65 ///
66 /// A one-item collection of the corresponding element type.
67 #[inline]
68 fn from(value: $type) -> Self {
69 MultiValues::$variant(vec![value])
70 }
71 }
72
73 $(#[$cfg])*
74 $(#[cfg_attr(docsrs, doc($cfg))])*
75 impl From<Vec<$type>> for MultiValues {
76 /// Takes ownership of the vector and its element storage without cloning elements.
77 /// An empty vector creates a concrete empty collection.
78 ///
79 /// # Parameters
80 ///
81 /// * `values` - Vector whose storage is moved into the collection.
82 ///
83 /// # Returns
84 ///
85 /// A typed collection retaining the input vector and element order.
86 #[inline]
87 fn from(values: Vec<$type>) -> Self {
88 MultiValues::$variant(values)
89 }
90 }
91
92 $(#[$cfg])*
93 $(#[cfg_attr(docsrs, doc($cfg))])*
94 impl From<&[$type]> for MultiValues {
95 /// Clones the elements into an owned collection, preserving order.
96 /// An empty slice creates a concrete empty collection.
97 ///
98 /// # Parameters
99 ///
100 /// * `values` - Elements to collect in their original order.
101 ///
102 /// # Returns
103 ///
104 /// A typed collection containing the input elements in order, including when empty.
105 #[inline]
106 fn from(values: &[$type]) -> Self {
107 MultiValues::$variant(values.to_vec())
108 }
109 }
110
111 $(#[$cfg])*
112 $(#[cfg_attr(docsrs, doc($cfg))])*
113 impl From<&Vec<$type>> for MultiValues {
114 /// Clones the elements into an owned collection, preserving order.
115 /// An empty vector creates a concrete empty collection.
116 ///
117 /// # Parameters
118 ///
119 /// * `values` - Elements to collect in their original order.
120 ///
121 /// # Returns
122 ///
123 /// A typed collection containing the input elements in order, including when empty.
124 #[inline]
125 fn from(values: &Vec<$type>) -> Self {
126 MultiValues::$variant(values.clone())
127 }
128 }
129
130 $(#[$cfg])*
131 $(#[cfg_attr(docsrs, doc($cfg))])*
132 impl<const N: usize> From<[$type; N]> for MultiValues {
133 /// Moves the array elements into a newly allocated vector, preserving order.
134 /// An empty array creates a concrete empty collection.
135 ///
136 /// # Parameters
137 ///
138 /// * `values` - Elements to collect in their original order.
139 ///
140 /// # Returns
141 ///
142 /// A typed collection containing the input elements in order, including when empty.
143 #[inline]
144 fn from(values: [$type; N]) -> Self {
145 MultiValues::$variant(Vec::from(values))
146 }
147 }
148
149 $(#[$cfg])*
150 $(#[cfg_attr(docsrs, doc($cfg))])*
151 impl<const N: usize> From<&[$type; N]> for MultiValues {
152 /// Clones the elements into an owned collection, preserving order.
153 /// An empty array creates a concrete empty collection.
154 ///
155 /// # Parameters
156 ///
157 /// * `values` - Elements to collect in their original order.
158 ///
159 /// # Returns
160 ///
161 /// A typed collection containing the input elements in order, including when empty.
162 #[inline]
163 fn from(values: &[$type; N]) -> Self {
164 MultiValues::$variant(values.to_vec())
165 }
166 }
167 )+
168 };
169}
170
171for_each_value_type!(impl_multi_values_from_table);
172
173impl From<&str> for MultiValues {
174 /// Copies the text into a one-item owned string collection.
175 ///
176 /// # Parameters
177 ///
178 /// * `value` - Borrowed text to copy into owned storage.
179 ///
180 /// # Returns
181 ///
182 /// A one-item string collection owning a copy of the text.
183 #[inline]
184 fn from(value: &str) -> Self {
185 MultiValues::String(vec![value.to_string()])
186 }
187}
188
189impl<'a> From<Vec<&'a str>> for MultiValues {
190 /// Copies each string into an owned collection, preserving order.
191 /// An empty vector creates a concrete empty collection.
192 ///
193 /// # Parameters
194 ///
195 /// * `values` - Borrowed strings to copy in their original order.
196 ///
197 /// # Returns
198 ///
199 /// An owned string collection in input order, including when empty.
200 #[inline]
201 fn from(values: Vec<&'a str>) -> Self {
202 MultiValues::String(collect_strings(values))
203 }
204}
205
206impl<'a, 'b> From<&'a [&'b str]> for MultiValues {
207 /// Copies each string into an owned collection, preserving order.
208 /// An empty slice creates a concrete empty collection.
209 ///
210 /// # Parameters
211 ///
212 /// * `values` - Borrowed strings to copy in their original order.
213 ///
214 /// # Returns
215 ///
216 /// An owned string collection in input order, including when empty.
217 #[inline]
218 fn from(values: &'a [&'b str]) -> Self {
219 MultiValues::String(collect_strings(values.iter().copied()))
220 }
221}
222
223impl<'a, 'b> From<&'a Vec<&'b str>> for MultiValues {
224 /// Copies each string into an owned collection, preserving order.
225 /// An empty vector creates a concrete empty collection.
226 ///
227 /// # Parameters
228 ///
229 /// * `values` - Borrowed strings to copy in their original order.
230 ///
231 /// # Returns
232 ///
233 /// An owned string collection in input order, including when empty.
234 #[inline]
235 fn from(values: &'a Vec<&'b str>) -> Self {
236 MultiValues::String(collect_strings(values.iter().copied()))
237 }
238}
239
240impl<'a, const N: usize> From<[&'a str; N]> for MultiValues {
241 /// Copies each string into an owned collection, preserving order.
242 /// An empty array creates a concrete empty collection.
243 ///
244 /// # Parameters
245 ///
246 /// * `values` - Borrowed strings to copy in their original order.
247 ///
248 /// # Returns
249 ///
250 /// An owned string collection in input order, including when empty.
251 #[inline]
252 fn from(values: [&'a str; N]) -> Self {
253 MultiValues::String(collect_strings(values))
254 }
255}
256
257impl<'a, 'b, const N: usize> From<&'a [&'b str; N]> for MultiValues {
258 /// Copies each string into an owned collection, preserving order.
259 /// An empty array creates a concrete empty collection.
260 ///
261 /// # Parameters
262 ///
263 /// * `values` - Borrowed strings to copy in their original order.
264 ///
265 /// # Returns
266 ///
267 /// An owned string collection in input order, including when empty.
268 #[inline]
269 fn from(values: &'a [&'b str; N]) -> Self {
270 MultiValues::String(collect_strings(values.iter().copied()))
271 }
272}