runmat_core/
value_metadata.rs

1use runmat_builtins::{LogicalArray, SparseTensor, Value};
2
3/// MATLAB-style class name for a runtime value.
4pub fn matlab_class_name(value: &Value) -> String {
5    match value {
6        Value::Num(_) | Value::ComplexTensor(_) | Value::Complex(_, _) => "double".to_string(),
7        Value::Tensor(tensor) => tensor.dtype.class_name().to_string(),
8        Value::SparseTensor(_) => "double".to_string(),
9        Value::Int(iv) => iv.class_name().to_string(),
10        Value::Bool(_) | Value::LogicalArray(_) => "logical".to_string(),
11        Value::String(_) | Value::StringArray(_) => "string".to_string(),
12        Value::CharArray(_) => "char".to_string(),
13        Value::Cell(_) => "cell".to_string(),
14        Value::Struct(_) => "struct".to_string(),
15        Value::GpuTensor(_) => "gpuArray".to_string(),
16        Value::FunctionHandle(_)
17        | Value::ExternalFunctionHandle(_)
18        | Value::MethodFunctionHandle(_)
19        | Value::BoundFunctionHandle { .. }
20        | Value::Closure(_) => "function_handle".to_string(),
21        Value::HandleObject(handle) => {
22            if handle.class_name.is_empty() {
23                "handle".to_string()
24            } else {
25                handle.class_name.clone()
26            }
27        }
28        Value::Listener(_) => "event.listener".to_string(),
29        // Internal destructuring helper; shouldn't surface in user-facing values,
30        // but handle it defensively for completeness.
31        Value::OutputList(_) => "OutputList".to_string(),
32        Value::Object(obj) => obj.class_name.clone(),
33        Value::ClassRef(_) => "meta.class".to_string(),
34        Value::MException(_) => "MException".to_string(),
35    }
36}
37
38/// Returns the MATLAB-style shape for the provided value when applicable.
39pub fn value_shape(value: &Value) -> Option<Vec<usize>> {
40    match value {
41        Value::Num(_) | Value::Int(_) | Value::Bool(_) | Value::Complex(_, _) => Some(vec![1, 1]),
42        Value::LogicalArray(arr) => Some(arr.shape.clone()),
43        Value::StringArray(sa) => Some(sa.shape.clone()),
44        Value::String(s) => Some(vec![1, s.chars().count()]),
45        Value::CharArray(ca) => Some(vec![ca.rows, ca.cols]),
46        Value::Tensor(t) => Some(t.shape.clone()),
47        Value::SparseTensor(s) => Some(vec![s.rows, s.cols]),
48        Value::ComplexTensor(t) => Some(t.shape.clone()),
49        Value::Cell(ca) => Some(ca.shape.clone()),
50        Value::GpuTensor(handle) => Some(handle.shape.clone()),
51        Value::Object(obj) if obj.is_class("datetime") => match obj.properties.get("__serial") {
52            Some(Value::Tensor(tensor)) => Some(tensor.shape.clone()),
53            Some(Value::Num(_)) => Some(vec![1, 1]),
54            _ => None,
55        },
56        _ => None,
57    }
58}
59
60/// Returns a MATLAB dtype label for numeric values when available.
61pub fn numeric_dtype_label(value: &Value) -> Option<&'static str> {
62    match value {
63        Value::Num(_) | Value::Complex(_, _) => Some("double"),
64        Value::Tensor(t) => Some(t.dtype.class_name()),
65        Value::LogicalArray(_) => Some("logical"),
66        Value::Int(iv) => Some(iv.class_name()),
67        _ => None,
68    }
69}
70
71/// Rough estimate of the in-memory footprint for the provided value, in bytes.
72pub fn approximate_size_bytes(value: &Value) -> Option<u64> {
73    Some(match value {
74        Value::Num(_) | Value::Int(_) | Value::Complex(_, _) => 8,
75        Value::Bool(_) => 1,
76        Value::LogicalArray(arr) => arr.data.len() as u64,
77        Value::Tensor(t) => (t.data.len() * 8) as u64,
78        Value::SparseTensor(s) => sparse_tensor_memory_bytes(s),
79        Value::ComplexTensor(t) => (t.data.len() * 16) as u64,
80        Value::String(s) => s.len() as u64,
81        Value::StringArray(sa) => sa.data.iter().map(|s| s.len() as u64).sum(),
82        Value::CharArray(ca) => (ca.rows * ca.cols) as u64,
83        _ => return None,
84    })
85}
86
87/// Rough estimate of the sparse tensor storage footprint, in bytes.
88pub fn sparse_tensor_memory_bytes(sparse: &SparseTensor) -> u64 {
89    sparse_tensor_memory_bytes_from_lengths(
90        sparse.values.len(),
91        sparse.row_indices.len(),
92        sparse.col_ptrs.len(),
93    )
94}
95
96fn sparse_tensor_memory_bytes_from_lengths(
97    values_len: usize,
98    row_indices_len: usize,
99    col_ptrs_len: usize,
100) -> u64 {
101    (values_len as u64)
102        .saturating_mul(std::mem::size_of::<f64>() as u64)
103        .saturating_add(
104            (row_indices_len as u64).saturating_mul(std::mem::size_of::<usize>() as u64),
105        )
106        .saturating_add((col_ptrs_len as u64).saturating_mul(std::mem::size_of::<usize>() as u64))
107}
108
109/// Produce a numeric preview (up to `limit` elements) for scalars and dense arrays.
110pub fn preview_numeric_values(value: &Value, limit: usize) -> Option<(Vec<f64>, bool)> {
111    match value {
112        Value::Num(n) => Some((vec![*n], false)),
113        Value::Int(iv) => Some((vec![iv.to_f64()], false)),
114        Value::Bool(flag) => Some((vec![if *flag { 1.0 } else { 0.0 }], false)),
115        Value::Tensor(t) => Some(preview_f64_slice(&t.data, limit)),
116        Value::SparseTensor(s) => Some(preview_sparse_tensor(s, limit)),
117        Value::LogicalArray(arr) => Some(preview_logical_slice(arr, limit)),
118        Value::StringArray(_) | Value::String(_) | Value::CharArray(_) => None,
119        Value::ComplexTensor(_) | Value::Complex(_, _) => None,
120        Value::Cell(_)
121        | Value::Struct(_)
122        | Value::Object(_)
123        | Value::HandleObject(_)
124        | Value::Listener(_)
125        | Value::OutputList(_)
126        | Value::FunctionHandle(_)
127        | Value::ExternalFunctionHandle(_)
128        | Value::MethodFunctionHandle(_)
129        | Value::BoundFunctionHandle { .. }
130        | Value::Closure(_)
131        | Value::ClassRef(_)
132        | Value::MException(_)
133        | Value::GpuTensor(_) => None,
134    }
135}
136
137fn preview_f64_slice(data: &[f64], limit: usize) -> (Vec<f64>, bool) {
138    if data.len() > limit {
139        (data[..limit].to_vec(), true)
140    } else {
141        (data.to_vec(), false)
142    }
143}
144
145fn preview_sparse_tensor(sparse: &SparseTensor, limit: usize) -> (Vec<f64>, bool) {
146    let total_len = sparse.rows.saturating_mul(sparse.cols);
147    let preview_len = total_len.min(limit);
148    let mut preview = Vec::with_capacity(preview_len);
149    if sparse.rows == 0 {
150        return (preview, false);
151    }
152    for linear_index in 0..preview_len {
153        let row = linear_index % sparse.rows;
154        let col = linear_index / sparse.rows;
155        preview.push(sparse.get(row, col).unwrap_or(0.0));
156    }
157    (preview, total_len > limit)
158}
159
160fn preview_logical_slice(arr: &LogicalArray, limit: usize) -> (Vec<f64>, bool) {
161    let truncated = arr.data.len() > limit;
162    let mut preview = Vec::with_capacity(arr.data.len().min(limit));
163    for value in arr.data.iter().take(limit) {
164        preview.push(if *value == 0 { 0.0 } else { 1.0 });
165    }
166    (preview, truncated)
167}
168
169#[cfg(test)]
170mod tests {
171    use super::*;
172    use runmat_builtins::{NumericDType, ObjectInstance, Tensor};
173
174    #[test]
175    fn approximate_size_bytes_uses_f64_width_for_integer_dtypes() {
176        // Tensor.data is always Vec<f64> (8 bytes/element) regardless of dtype.
177        let u8_tensor = Tensor::new_with_dtype(vec![1.0, 2.0, 3.0], vec![3, 1], NumericDType::U8)
178            .expect("tensor");
179        let u16_tensor = Tensor::new_with_dtype(vec![1.0, 2.0, 3.0], vec![3, 1], NumericDType::U16)
180            .expect("tensor");
181        let f32_tensor = Tensor::new_with_dtype(vec![1.0, 2.0, 3.0], vec![3, 1], NumericDType::F32)
182            .expect("tensor");
183
184        assert_eq!(approximate_size_bytes(&Value::Tensor(u8_tensor)), Some(24));
185        assert_eq!(approximate_size_bytes(&Value::Tensor(u16_tensor)), Some(24));
186        assert_eq!(approximate_size_bytes(&Value::Tensor(f32_tensor)), Some(24));
187    }
188
189    #[test]
190    fn sparse_tensor_memory_bytes_uses_saturating_arithmetic() {
191        let sparse =
192            SparseTensor::new(3, 2, vec![0, 1, 2], vec![0, 2], vec![4.0, 5.0]).expect("sparse");
193        let expected = (2 * std::mem::size_of::<f64>())
194            + (2 * std::mem::size_of::<usize>())
195            + (3 * std::mem::size_of::<usize>());
196
197        assert_eq!(sparse_tensor_memory_bytes(&sparse), expected as u64);
198        assert_eq!(
199            sparse_tensor_memory_bytes_from_lengths(usize::MAX, usize::MAX, usize::MAX),
200            u64::MAX
201        );
202    }
203
204    #[test]
205    fn datetime_object_shape_comes_from_internal_serial_tensor() {
206        let mut object = ObjectInstance::new("datetime".to_string());
207        object.properties.insert(
208            "__serial".to_string(),
209            Value::Tensor(Tensor::new(vec![739351.0, 739352.0], vec![2, 1]).expect("tensor")),
210        );
211
212        assert_eq!(value_shape(&Value::Object(object)), Some(vec![2, 1]));
213    }
214
215    #[test]
216    fn sparse_preview_uses_logical_column_major_values() {
217        let sparse = SparseTensor::new(3, 3, vec![0, 1, 1, 3], vec![1, 0, 2], vec![4.0, 5.0, 6.0])
218            .expect("sparse");
219
220        assert_eq!(
221            preview_numeric_values(&Value::SparseTensor(sparse), 9),
222            Some((vec![0.0, 4.0, 0.0, 0.0, 0.0, 0.0, 5.0, 0.0, 6.0], false))
223        );
224    }
225
226    #[test]
227    fn sparse_preview_truncates_by_logical_element_count() {
228        let sparse = SparseTensor::zeros(1000, 1000);
229
230        assert_eq!(
231            preview_numeric_values(&Value::SparseTensor(sparse), 3),
232            Some((vec![0.0, 0.0, 0.0], true))
233        );
234    }
235}
runmat_core/value_metadata.rs

runmat_core/
value_metadata.rs
