Struct MultiValues

Source

pub struct MultiValues { /* private fields */ }

Expand description

Multiple typed runtime values with private storage representation.

Implementations§

Source §

impl MultiValues

Source

pub fn to_json_value(&self) -> ValueResult<JsonValue>

Projects this collection to its natural JSON representation.

Unset is null; every concrete collection is an array, including empty and one-item collections.

§Returns

The natural JSON representation of this collection.

§Errors

Returns a list conversion error containing the zero-based source index when an item cannot be represented as JSON.

Source

pub fn to_json_value_with( &self, options: &DataConversionOptions, ) -> ValueResult<JsonValue>

Projects this collection using explicit conversion options.

§Parameters

options - Controls duration units and precision-loss behavior.

§Returns

The natural JSON representation of this collection.

§Errors

Returns an indexed list conversion error when an item cannot be represented under the requested options.

Source §

T - Target type.

§Returns

The converted first value.

§Errors

Returns a structured missing-value conversion error when the container is unset, an empty-collection error for a concrete empty vector, or a conversion error when the first value cannot be converted to T.

Source

pub fn to_first_or<T>( &self, default: impl IntoValueDefault<T>, ) -> ValueResult<T>
where T: DataConversionTarget,

Converts the first stored value to T, or returns default when the container is unset or conversion reports a missing value.

A concrete empty collection remains an error and does not use the default.

§Type Parameters

T - Target type.

§Parameters

default - Value returned for unset storage or a conversion-missing result.

§Returns

The converted first value, or default for unset or conversion-missing storage.

§Errors

Returns an empty-collection error for a concrete empty vector, or a conversion error when the first value cannot be converted to T.

Source

pub fn to_first_or_else<T, F>(&self, default: F) -> ValueResult<T>
where T: DataConversionTarget, F: FnOnce() -> T,

Converts the first value or calls default when storage is unset or conversion reports a missing value.

§Type Parameters

T - Target conversion type.
F - Deferred fallback producing T.

§Parameters

default - Callback invoked for unset storage or a conversion-missing result.

§Returns

The converted first item or the callback result.

§Errors

Preserves empty-collection and concrete-value conversion errors without invoking the callback.

Source

pub fn to_first_with<T>( &self, options: &DataConversionOptions, ) -> ValueResult<T>
where T: DataConversionTarget,

Converts the first stored value to T using conversion options.

Stored strings are collection items and are never split again by scalar string collection options.

§Type Parameters

T - Target type.

§Parameters

options - Conversion options forwarded to qubit_datatype.

§Returns

The converted first value.

§Errors

Returns a structured missing-value conversion error when the container is unset, an empty-collection error for a concrete empty vector, or a conversion error when the first value cannot be converted to T.

Source

pub fn to_first_or_with<T>( &self, default: impl IntoValueDefault<T>, options: &DataConversionOptions, ) -> ValueResult<T>
where T: DataConversionTarget,

Converts the first stored value to T using conversion options, or returns default when storage is unset or conversion reports a missing value.

§Type Parameters

T - Target conversion type.

§Parameters

default - Lazily materialized value used for unset storage or a conversion-missing result.
options - Conversion options forwarded to qubit_datatype.

§Returns

The converted first item, or default for unset or conversion-missing storage.

§Errors

Returns an empty-collection error or a conversion error for concrete values that cannot be converted under options.

Source

pub fn to_first_or_else_with<T, F>( &self, default: F, options: &DataConversionOptions, ) -> ValueResult<T>
where T: DataConversionTarget, F: FnOnce() -> T,

Converts the first value with options, or calls default when storage is unset or conversion reports a missing value.

§Type Parameters

T - Target conversion type.
F - Deferred fallback producing T.

§Parameters

default - Callback invoked for unset storage or a conversion-missing result.
options - Conversion options forwarded to the shared converter.

§Returns

The converted first item or the callback result.

§Errors

Preserves concrete-value conversion errors without invoking the callback.

Source

pub fn to_list<T>(&self) -> ValueResult<Vec<T>>
where T: DataConversionTarget,

Converts all stored values to T.

Unlike Self::get, this method uses shared DataConverter conversion rules for every element instead of strict type matching. A concrete empty vector returns an empty vector; an unset container reports a missing-value conversion error.

§Type Parameters

T - Target element type.

§Returns

A vector containing all converted values in the original order.

§Errors

Returns the first conversion error encountered while converting an element.

Source

pub fn to_list_or<T>( &self, default: impl IntoValueDefault<Vec<T>>, ) -> ValueResult<Vec<T>>
where T: DataConversionTarget,

Converts all stored values to T, or returns default when storage is unset or conversion reports a missing value.

§Type Parameters

T - Target element type.

§Parameters

default - Lazily materialized list used for unset storage or a conversion-missing result.

§Returns

All converted items, or default for unset or conversion-missing storage.

§Errors

Returns the first item conversion error for concrete storage.

Source

pub fn to_list_or_else<T, F>(&self, default: F) -> ValueResult<Vec<T>>
where T: DataConversionTarget, F: FnOnce() -> Vec<T>,

Converts all values or calls default when storage is unset or conversion reports a missing value.

§Type Parameters

T - Target element conversion type.
F - Deferred fallback producing the complete list.

§Parameters

default - Callback invoked for unset storage or a conversion-missing result.

§Returns

The converted list or the callback result.

§Errors

Preserves concrete-value conversion errors without invoking the callback.

Source

pub fn to_list_with<T>( &self, options: &DataConversionOptions, ) -> ValueResult<Vec<T>>
where T: DataConversionTarget,

Converts all stored values to T using conversion options.

Stored strings are collection items and are never split again by scalar string collection options.

§Type Parameters

T - Target element type.

§Parameters

options - Conversion options forwarded to qubit_datatype.

§Returns

A vector containing all converted values in the original order.

§Errors

Returns the first conversion error encountered while converting an element.

Source

pub fn to_list_or_with<T>( &self, default: impl IntoValueDefault<Vec<T>>, options: &DataConversionOptions, ) -> ValueResult<Vec<T>>
where T: DataConversionTarget,

Converts all stored values to T using conversion options, or returns default when storage is unset or conversion reports a missing value.

§Type Parameters

T - Target element type.

§Parameters

default - Lazily materialized list used for unset storage or a conversion-missing result.
options - Conversion options forwarded to qubit_datatype.

§Returns

All converted items, or default for unset or conversion-missing storage.

§Errors

Returns the first item conversion error for concrete storage.

Source

pub fn to_list_or_else_with<T, F>( &self, default: F, options: &DataConversionOptions, ) -> ValueResult<Vec<T>>
where T: DataConversionTarget, F: FnOnce() -> Vec<T>,

Converts all values with options, or calls default when storage is unset or conversion reports a missing value.

§Type Parameters

T - Target element conversion type.
F - Deferred fallback producing the complete list.

§Parameters

default - Callback invoked for unset storage or a conversion-missing result.
options - Conversion options forwarded to the shared converter.

§Returns

The converted list or the callback result.

§Errors

Preserves concrete-value conversion errors without invoking the callback.

Source §

impl MultiValues

Source

pub fn new<S>(values: S) -> Self
where S: Into<Self>,

Generic constructor method

Creates MultiValues from any supported input form, avoiding direct use of enum variants at call sites.

Supported input forms include single values, vectors, slices, arrays, borrowed vectors, and borrowed string collections for supported element types.

§Type Parameters

S - Input type convertible into MultiValues.

§Parameters

values - Values to convert into a collection.

§Returns

Returns MultiValues wrapping the converted input values.

§Examples

use qubit_value::MultiValues;

// Basic types
let mv = MultiValues::new(vec![1, 2, 3]);
assert_eq!(mv.len(), 3);

// Strings
let mv = MultiValues::new(vec!["a".to_string(), "b".to_string()]);
assert_eq!(mv.len(), 2);

Source

pub fn get<T>(&self) -> ValueResult<Vec<T>>
where for<'a> Vec<T>: TryFrom<&'a Self, Error = ValueError>,

Generic getter method for multiple values.

Performs a strict typed read of all stored values as Vec<T>.

§Type Parameters

T - The target element type to retrieve.

§Returns

Returns the list of values when the stored type matches T.

§Errors

Returns ValueError::Missing when the container is unset with the requested type, or ValueError::TypeMismatch when the stored type differs from T.

§Examples

use qubit_value::MultiValues;

let multi = MultiValues::Int32(vec![1, 2, 3]);

// Through type inference
let nums: Vec<i32> = multi.get().unwrap();
assert_eq!(nums, vec![1, 2, 3]);

// Explicitly specify type parameter
let nums = multi.get::<i32>().unwrap();
assert_eq!(nums, vec![1, 2, 3]);

Source

pub fn get_or<T>( &self, default: impl IntoValueDefault<Vec<T>>, ) -> ValueResult<Vec<T>>
where for<'a> Vec<T>: TryFrom<&'a Self, Error = ValueError>,

Generic getter method with a default value list.

Returns the supplied default only when this container is unset. A concrete empty vector remains an empty result.

§Type Parameters

T - Target element type for the strict read.

§Parameters

default - Lazily materialized list used only for unset storage.

§Returns

The concrete stored list, or default for unset storage.

§Errors

Returns ValueError::TypeMismatch when the stored type differs from T.

Source

pub fn get_or_else<T, F>(&self, default: F) -> ValueResult<Vec<T>>
where for<'a> Vec<T>: TryFrom<&'a Self, Error = ValueError>, F: FnOnce() -> Vec<T>,

Strictly reads all values or calls default only when storage is unset.

A concrete empty collection is returned unchanged and type mismatches are preserved without invoking the callback.

§Type Parameters

T - Target element type.
F - Deferred fallback producing the complete list.

§Parameters

default - Callback invoked only for unset storage.

§Returns

The stored list or the callback result.

§Errors

Returns ValueError::TypeMismatch for an incompatible concrete collection without invoking the callback.

Source

pub fn get_first<T>(&self) -> ValueResult<T>
where for<'a> T: TryFrom<&'a Self, Error = ValueError>,

Generic getter method for the first value

Reads the first stored value as T, performing strict type checking.

get_first<T>() does not do cross-type conversion. When the converter feature is enabled, use to<T>() for compatible cross-type conversion.

§Type Parameters

T - The target element type to retrieve.

§Returns

Returns the first value when the stored type matches T and at least one value exists.

§Errors

Returns ValueError::Missing when the requested type matches but no value is stored, or ValueError::TypeMismatch when the stored type differs from T.

§Examples

use qubit_value::MultiValues;

let multi = MultiValues::Int32(vec![42, 100, 200]);

// Through type inference
let first: i32 = multi.get_first().unwrap();
assert_eq!(first, 42);

// Explicitly specify type parameter
let first = multi.get_first::<i32>().unwrap();
assert_eq!(first, 42);

// String type
let multi = MultiValues::String(vec!["hello".to_string(), "world".to_string()]);
let first: String = multi.get_first().unwrap();
assert_eq!(first, "hello");

Source

pub fn get_first_or<T>( &self, default: impl IntoValueDefault<T>, ) -> ValueResult<T>
where for<'a> T: TryFrom<&'a Self, Error = ValueError>,

Generic first-value getter with a default value.

Returns the supplied default only when the container is unset. A concrete empty vector returns ValueError::Missing; type mismatches are also preserved.

§Type Parameters

T - Target type for the strict first-item read.

§Parameters

default - Lazily materialized value used only for unset storage.

§Returns

The first concrete item, or default for unset storage.

§Errors

Returns ValueError::Missing for a concrete empty collection or ValueError::TypeMismatch when the stored type differs from T.

Source

pub fn get_first_or_else<T, F>(&self, default: F) -> ValueResult<T>
where for<'a> T: TryFrom<&'a Self, Error = ValueError>, F: FnOnce() -> T,

Strictly reads the first value or calls default only when unset.

§Type Parameters

T - Target element type.
F - Deferred fallback producing one element.

§Parameters

default - Callback invoked only for unset storage.

§Returns

The first stored item or the callback result.

§Errors

Preserves empty-collection and type-mismatch errors without invoking the callback.

Source

pub fn set<S>(&mut self, values: S)
where S: Into<Self>,

Generic setter method

Replaces the entire list with the converted input values.

This operation updates the stored type to the input element type and does not validate runtime compatibility with the previous variant.

Supports any input that can be converted into MultiValues, including single values, vectors, slices, arrays, and borrowed vectors for supported element types.

Existing values are replaced, and the stored type becomes the converted input type.

§Type Parameters

S - Input type convertible into MultiValues.

§Parameters

values - The values to set.

§Compile-time restriction

Unsupported input types fail to compile because they do not implement Into<MultiValues>.

§Examples

use qubit_datatype::DataType;
use qubit_value::MultiValues;

// 1) Vec<T>
let mut mv = MultiValues::Unset(DataType::Int32);
mv.set(vec![42, 100, 200]);
assert_eq!(mv.get_int32s().unwrap(), &[42, 100, 200]);

// 2) &[T]
let mut mv = MultiValues::Unset(DataType::Int32);
let slice = &[7, 8, 9][..];
mv.set(slice);
assert_eq!(mv.get_int32s().unwrap(), &[7, 8, 9]);

// 3) Single T
let mut mv = MultiValues::Unset(DataType::Int32);
mv.set(42);
assert_eq!(mv.get_int32s().unwrap(), &[42]);

// String example
let mut mv = MultiValues::Unset(DataType::String);
mv.set(vec!["hello".to_string(), "world".to_string()]);
assert_eq!(mv.get_strings().unwrap(), &["hello", "world"]);

Source

pub fn add<S>(&mut self, values: S) -> ValueResult<()>
where S: Into<Self>,

Generic add method

Appends converted input values to the existing list with strict type checking.

Supports any input that can be converted into MultiValues, including single values, vectors, slices, arrays, and borrowed vectors for supported element types.

The converted input must have the same data type as the current container. An empty container keeps its declared type until non-empty values of the same type are appended.

§Type Parameters

S - Input type convertible into MultiValues.

§Parameters

values - Values to append.

§Returns

Ok(()) after appending, including when the input is empty.

§Errors

Returns ValueError::TypeMismatch when the converted input data type differs from the current container data type.

§Examples

use qubit_datatype::DataType;
use qubit_value::MultiValues;

// 1) Single T
let mut mv = MultiValues::Int32(vec![42]);
mv.add(100).unwrap();
assert_eq!(mv.get_int32s().unwrap(), &[42, 100]);

// 2) Vec<T>
mv.add(vec![200, 300]).unwrap();
assert_eq!(mv.get_int32s().unwrap(), &[42, 100, 200, 300]);

// 3) &[T]
let slice = &[400, 500][..];
mv.add(slice).unwrap();
assert_eq!(mv.get_int32s().unwrap(), &[42, 100, 200, 300, 400, 500]);

Source

pub fn data_type(&self) -> DataType

Get the data type of the values

§Returns

Returns the data type corresponding to these multiple values

§Examples

use qubit_datatype::DataType;
use qubit_value::MultiValues;

let values = MultiValues::Int32(vec![1, 2, 3]);
assert_eq!(values.data_type(), DataType::Int32);

Source

pub fn len(&self) -> usize

Returns the number of values.

§Returns

The number of values contained in these multiple values. An unset collection has length zero.

§Examples

use qubit_datatype::DataType;
use qubit_value::MultiValues;

let values = MultiValues::Int32(vec![1, 2, 3]);
assert_eq!(values.len(), 3);

let empty = MultiValues::Unset(DataType::String);
assert_eq!(empty.len(), 0);

Source

pub fn is_empty(&self) -> bool

Tests whether this collection contains no values.

An unset collection and a concrete empty vector both have length zero. Use MultiValues::is_unset when the distinction between no collection and a concrete empty collection matters.

§Returns

true when Self::len is zero; otherwise, false.

Source

pub fn is_unset(&self) -> bool

Tests whether this container has no concrete vector.

§Returns

Returns true only for MultiValues::Unset. A concrete empty vector returns false.

§Examples

use qubit_datatype::DataType;
use qubit_value::MultiValues;

let values = MultiValues::Int32(vec![]);
assert!(!values.is_unset());

let empty = MultiValues::Unset(DataType::String);
assert!(empty.is_unset());

Source

pub fn is_numeric(&self) -> bool

Tests whether a concrete collection belongs to the numeric type family.

A concrete empty numeric vector returns true; an unset collection returns false, even when its declared type is numeric.

§Returns

true for concrete collections with a numeric element type.

Source

pub fn unset(&mut self)

Removes the concrete vector while preserving its declared data type.

Source

pub fn clear(&mut self)

Clears all values while preserving a concrete collection and its type. An unset collection remains unset because it has no concrete vector to clear.

§Examples

use qubit_datatype::DataType;
use qubit_value::MultiValues;

let mut values = MultiValues::Int32(vec![1, 2, 3]);
values.clear();
assert_eq!(values.len(), 0);
assert_eq!(values.data_type(), DataType::Int32);

Source

pub fn set_type(&mut self, data_type: DataType)

Set the data type

If the new type differs from the current type, clears all values and sets the new type.

§Parameters

data_type - The data type to set

§Examples

use qubit_datatype::DataType;
use qubit_value::MultiValues;

let mut values = MultiValues::Int32(vec![1, 2, 3]);
values.set_type(DataType::String);
assert!(values.is_unset());
assert_eq!(values.data_type(), DataType::String);

Source

pub fn first_value(&self) -> Value

Converts the first element to a single Value.

Returns Value::Unset with the same declared type when no element is stored.

§Returns

A cloned first item, or a typed unset value when no item exists.

Source

pub fn into_first_value(self) -> Value

Consumes this collection and returns its first item as a Value.

Empty and unset collections become Value::Unset with the same data type. Owned element storage is moved instead of cloned.

§Returns

The owned first item, or a typed unset value when no item exists.

Source

pub fn merge(&mut self, other: &MultiValues) -> ValueResult<()>

Appends all values from another container with the same data type.

§Parameters

other - Collection whose values are cloned and appended.

§Returns

Ok(()) after appending, including when other is empty.

§Errors

Returns ValueError::TypeMismatch when other has a different data type.

Source §

impl MultiValues

Source

pub fn get_first_bool(&self) -> ValueResult<bool>

Get the first boolean value.

§Returns

If types match and a value exists, returns the first boolean value; see # Errors.

§Examples

use qubit_value::MultiValues;

let values = MultiValues::Bool(vec![true, false]);
assert_eq!(values.get_first_bool().unwrap(), true);

§Examples

use qubit_value::MultiValues;

let values = MultiValues::Bool(vec![true, false, true]);
assert_eq!(values.get_bools().unwrap(), &[true, false, true]);

§Errors

Returns ValueError::Missing when the container is unset with the requested type, or ValueError::TypeMismatch when the stored data type differs. A concrete empty vector returns an empty slice.