Skip to main content

excel_api/
convert.rs

1use core::mem::size_of;
2
3use crate::{
4    ConversionError, ExcelArray, ExcelArrayView, ExcelError, ExcelString, ExcelValue,
5    ExcelValueRef, OptionalValue,
6};
7
8/// Resource limits applied before callback-owned data is copied.
9///
10/// Defaults deliberately allow far less than Excel's maximum worksheet grid:
11/// 65,536 elements and 16 MiB of conservatively counted destination storage.
12#[derive(Clone, Copy, Debug, Eq, PartialEq)]
13pub struct ConversionLimits {
14    /// Maximum UTF-16 code units copied for one string.
15    pub max_string_code_units: usize,
16    /// Maximum elements copied from one rectangular array.
17    pub max_array_elements: usize,
18    /// Maximum conservatively counted destination bytes.
19    pub max_aggregate_bytes: usize,
20    /// Maximum supported conversion nesting depth.
21    pub max_depth: usize,
22}
23
24impl ConversionLimits {
25    /// Conservative conversion bounds used by [`Default`].
26    pub const DEFAULT: Self = Self {
27        max_string_code_units: excel_api_sys::EXCEL12_MAX_STRING_CODE_UNITS,
28        max_array_elements: 65_536,
29        max_aggregate_bytes: 16 * 1024 * 1024,
30        max_depth: 8,
31    };
32}
33
34impl Default for ConversionLimits {
35    fn default() -> Self {
36        Self::DEFAULT
37    }
38}
39
40/// Convert one borrowed Excel input into a Rust value without invoking Excel
41/// coercion rules.
42pub trait FromExcel<'call>: Sized {
43    /// Converts a callback-borrowed value without invoking Excel coercion.
44    ///
45    /// Implementations must not retain callback-scoped pointers in `Self`.
46    fn from_excel(value: ExcelValueRef<'call>) -> Result<Self, ConversionError>;
47}
48
49/// Convert a Rust value into an owned semantic Excel value.
50///
51/// A later memory layer will transform this value into an ABI-compatible
52/// return allocation.
53pub trait IntoExcel {
54    /// Produces an owned semantic Excel value suitable for later return planning.
55    fn into_excel(self) -> Result<ExcelValue, ConversionError>;
56}
57
58impl ExcelValue {
59    /// Deep-copies a callback value using [`ConversionLimits::default`].
60    pub fn from_borrowed(value: ExcelValueRef<'_>) -> Result<Self, ConversionError> {
61        Self::from_borrowed_with_limits(value, &ConversionLimits::default())
62    }
63
64    /// Deep-copies a callback value after a non-allocating preflight pass.
65    pub fn from_borrowed_with_limits(
66        value: ExcelValueRef<'_>,
67        limits: &ConversionLimits,
68    ) -> Result<Self, ConversionError> {
69        let required = preflight_value(&value, limits, 0)?;
70        enforce_aggregate_limit(required, limits)?;
71        materialize_value(value, 0)
72    }
73}
74
75impl ExcelString {
76    /// Copies callback UTF-16 using [`ConversionLimits::default`].
77    pub fn from_borrowed(value: ExcelValueRef<'_>) -> Result<Self, ConversionError> {
78        Self::from_borrowed_with_limits(value, &ConversionLimits::default())
79    }
80
81    /// Copies callback UTF-16 directly, without an intermediate UTF-8 string.
82    pub fn from_borrowed_with_limits(
83        value: ExcelValueRef<'_>,
84        limits: &ConversionLimits,
85    ) -> Result<Self, ConversionError> {
86        let ExcelValueRef::Text(value) = value else {
87            return Err(unexpected("text", &value));
88        };
89        let required = preflight_string(value.len(), size_of::<u16>(), limits)?;
90        enforce_aggregate_limit(required, limits)?;
91        Ok(value.into())
92    }
93}
94
95impl ExcelArray {
96    /// Deep-copies a callback multi using [`ConversionLimits::default`].
97    pub fn from_borrowed(value: ExcelValueRef<'_>) -> Result<Self, ConversionError> {
98        Self::from_borrowed_with_limits(value, &ConversionLimits::default())
99    }
100
101    /// Deep-copies a callback multi after checking shape and all configured
102    /// limits before allocating destination storage.
103    pub fn from_borrowed_with_limits(
104        value: ExcelValueRef<'_>,
105        limits: &ConversionLimits,
106    ) -> Result<Self, ConversionError> {
107        let ExcelValueRef::Array(value) = value else {
108            return Err(unexpected("array", &value));
109        };
110        let required = preflight_array(&value, limits, 0)?;
111        enforce_aggregate_limit(required, limits)?;
112        materialize_array(value, 0)
113    }
114}
115
116impl<'call> FromExcel<'call> for ExcelValue {
117    fn from_excel(value: ExcelValueRef<'call>) -> Result<Self, ConversionError> {
118        Self::from_borrowed(value)
119    }
120}
121
122impl<'call> FromExcel<'call> for ExcelString {
123    fn from_excel(value: ExcelValueRef<'call>) -> Result<Self, ConversionError> {
124        Self::from_borrowed(value)
125    }
126}
127
128impl<'call> FromExcel<'call> for String {
129    fn from_excel(value: ExcelValueRef<'call>) -> Result<Self, ConversionError> {
130        let ExcelValueRef::Text(value) = value else {
131            return Err(unexpected("text", &value));
132        };
133        let limits = ConversionLimits::default();
134        let required = preflight_string(value.len(), 3, &limits)?;
135        enforce_aggregate_limit(required, &limits)?;
136        String::from_utf16(value.as_utf16()).map_err(|_| ConversionError::InvalidUtf16)
137    }
138}
139
140impl<'call> FromExcel<'call> for ExcelArray {
141    fn from_excel(value: ExcelValueRef<'call>) -> Result<Self, ConversionError> {
142        Self::from_borrowed(value)
143    }
144}
145
146impl<'call> FromExcel<'call> for f64 {
147    fn from_excel(value: ExcelValueRef<'call>) -> Result<Self, ConversionError> {
148        match value {
149            ExcelValueRef::Number(value) => Ok(value),
150            ExcelValueRef::Integer(value) => Ok(f64::from(value)),
151            other => Err(unexpected("number", &other)),
152        }
153    }
154}
155
156impl<'call> FromExcel<'call> for bool {
157    fn from_excel(value: ExcelValueRef<'call>) -> Result<Self, ConversionError> {
158        match value {
159            ExcelValueRef::Boolean(value) => Ok(value),
160            other => Err(unexpected("boolean", &other)),
161        }
162    }
163}
164
165impl<'call> FromExcel<'call> for ExcelError {
166    fn from_excel(value: ExcelValueRef<'call>) -> Result<Self, ConversionError> {
167        match value {
168            ExcelValueRef::Error(value) => Ok(value),
169            other => Err(unexpected("error", &other)),
170        }
171    }
172}
173
174impl<'call, T: FromExcel<'call>> FromExcel<'call> for Option<T> {
175    /// Missing and empty values both map to `None`. Use `OptionalValue<T>` when
176    /// that distinction must be retained.
177    fn from_excel(value: ExcelValueRef<'call>) -> Result<Self, ConversionError> {
178        match value {
179            ExcelValueRef::Missing(_) | ExcelValueRef::Nil(_) => Ok(None),
180            value => T::from_excel(value).map(Some),
181        }
182    }
183}
184
185impl<'call, T: FromExcel<'call>> FromExcel<'call> for OptionalValue<T> {
186    fn from_excel(value: ExcelValueRef<'call>) -> Result<Self, ConversionError> {
187        match value {
188            ExcelValueRef::Missing(_) => Ok(Self::Missing),
189            ExcelValueRef::Nil(_) => Ok(Self::Empty),
190            value => T::from_excel(value).map(Self::Value),
191        }
192    }
193}
194
195macro_rules! impl_integer_from_excel {
196    ($($integer:ty),* $(,)?) => {
197        $(
198            impl<'call> FromExcel<'call> for $integer {
199                fn from_excel(value: ExcelValueRef<'call>) -> Result<Self, ConversionError> {
200                    match value {
201                        ExcelValueRef::Integer(value) => {
202                            Self::try_from(value).map_err(|_| ConversionError::IntegerOutOfRange)
203                        }
204                        ExcelValueRef::Number(value) => checked_float_to_integer(
205                            value,
206                            <$integer>::MIN as f64,
207                            <$integer>::MAX as f64,
208                        ),
209                        other => Err(unexpected("integer", &other)),
210                    }
211                }
212            }
213        )*
214    };
215}
216
217impl_integer_from_excel!(i16, i32, u16, u32);
218
219fn checked_float_to_integer<T>(value: f64, minimum: f64, maximum: f64) -> Result<T, ConversionError>
220where
221    T: TryFrom<i64>,
222{
223    if !value.is_finite() {
224        return Err(ConversionError::NonFiniteNumber);
225    }
226    if value.fract() != 0.0 {
227        return Err(ConversionError::NonIntegralNumber);
228    }
229
230    // Every currently supported target is at most 32 bits, so all target
231    // bounds and integral inputs are represented exactly by f64 and i64.
232    if value < minimum || value > maximum {
233        return Err(ConversionError::IntegerOutOfRange);
234    }
235    let integer = value as i64;
236    T::try_from(integer).map_err(|_| ConversionError::IntegerOutOfRange)
237}
238
239impl IntoExcel for ExcelValue {
240    fn into_excel(self) -> Result<ExcelValue, ConversionError> {
241        Ok(self)
242    }
243}
244
245impl IntoExcel for ExcelArray {
246    fn into_excel(self) -> Result<ExcelValue, ConversionError> {
247        Ok(ExcelValue::Array(self))
248    }
249}
250
251impl IntoExcel for ExcelString {
252    fn into_excel(self) -> Result<ExcelValue, ConversionError> {
253        Ok(ExcelValue::Text(self))
254    }
255}
256
257impl IntoExcel for f64 {
258    fn into_excel(self) -> Result<ExcelValue, ConversionError> {
259        Ok(ExcelValue::Number(self))
260    }
261}
262
263impl IntoExcel for bool {
264    fn into_excel(self) -> Result<ExcelValue, ConversionError> {
265        Ok(ExcelValue::Boolean(self))
266    }
267}
268
269impl IntoExcel for String {
270    fn into_excel(self) -> Result<ExcelValue, ConversionError> {
271        Ok(ExcelValue::Text(self.into()))
272    }
273}
274
275impl IntoExcel for &str {
276    fn into_excel(self) -> Result<ExcelValue, ConversionError> {
277        Ok(ExcelValue::Text(self.into()))
278    }
279}
280
281impl IntoExcel for ExcelError {
282    fn into_excel(self) -> Result<ExcelValue, ConversionError> {
283        Ok(ExcelValue::Error(self))
284    }
285}
286
287macro_rules! impl_i32_backed_into_excel {
288    ($($integer:ty),* $(,)?) => {
289        $(
290            impl IntoExcel for $integer {
291                fn into_excel(self) -> Result<ExcelValue, ConversionError> {
292                    Ok(ExcelValue::Integer(i32::from(self)))
293                }
294            }
295        )*
296    };
297}
298
299impl_i32_backed_into_excel!(i16, i32, u16);
300
301impl IntoExcel for u32 {
302    fn into_excel(self) -> Result<ExcelValue, ConversionError> {
303        match i32::try_from(self) {
304            Ok(value) => Ok(ExcelValue::Integer(value)),
305            Err(_) => Ok(ExcelValue::Number(f64::from(self))),
306        }
307    }
308}
309
310fn preflight_value(
311    value: &ExcelValueRef<'_>,
312    limits: &ConversionLimits,
313    depth: usize,
314) -> Result<usize, ConversionError> {
315    enforce_depth(depth, limits)?;
316    match value {
317        ExcelValueRef::Text(value) => preflight_string(value.len(), size_of::<u16>(), limits),
318        ExcelValueRef::Reference(_) => Err(ConversionError::UnsupportedReference),
319        ExcelValueRef::Array(value) => {
320            if depth != 0 {
321                return Err(ConversionError::NestedArrayUnsupported);
322            }
323            preflight_array(value, limits, depth)
324        }
325        ExcelValueRef::Number(_)
326        | ExcelValueRef::Boolean(_)
327        | ExcelValueRef::Error(_)
328        | ExcelValueRef::Missing(_)
329        | ExcelValueRef::Nil(_)
330        | ExcelValueRef::Integer(_) => Ok(0),
331    }
332}
333
334fn preflight_array(
335    array: &ExcelArrayView<'_>,
336    limits: &ConversionLimits,
337    depth: usize,
338) -> Result<usize, ConversionError> {
339    let element_depth = depth
340        .checked_add(1)
341        .ok_or(ConversionError::ConversionDepthExceeded {
342            depth: usize::MAX,
343            maximum: limits.max_depth,
344        })?;
345    enforce_depth(element_depth, limits)?;
346
347    let (rows, columns) = array.dimensions();
348    let count = rows
349        .checked_mul(columns)
350        .ok_or(ConversionError::InvalidArrayShape)?;
351    if count > limits.max_array_elements {
352        return Err(ConversionError::ArrayElementLimitExceeded {
353            actual: count,
354            maximum: limits.max_array_elements,
355        });
356    }
357
358    let mut required = checked_storage_bytes(count, size_of::<ExcelValue>(), limits)?;
359    enforce_aggregate_limit(required, limits)?;
360    for row in 0..rows {
361        for column in 0..columns {
362            let value = array
363                .get(row, column)?
364                .ok_or(ConversionError::InvalidArrayShape)?;
365            let element_bytes = preflight_value(&value, limits, element_depth)?;
366            required = required.checked_add(element_bytes).ok_or(
367                ConversionError::AggregateByteLimitExceeded {
368                    required: usize::MAX,
369                    maximum: limits.max_aggregate_bytes,
370                },
371            )?;
372            enforce_aggregate_limit(required, limits)?;
373        }
374    }
375    Ok(required)
376}
377
378fn preflight_string(
379    code_units: usize,
380    bytes_per_unit: usize,
381    limits: &ConversionLimits,
382) -> Result<usize, ConversionError> {
383    if code_units > limits.max_string_code_units {
384        return Err(ConversionError::StringLimitExceeded {
385            actual: code_units,
386            maximum: limits.max_string_code_units,
387        });
388    }
389    checked_storage_bytes(code_units, bytes_per_unit, limits)
390}
391
392fn checked_storage_bytes(
393    count: usize,
394    element_size: usize,
395    limits: &ConversionLimits,
396) -> Result<usize, ConversionError> {
397    count
398        .checked_mul(element_size)
399        .ok_or(ConversionError::AggregateByteLimitExceeded {
400            required: usize::MAX,
401            maximum: limits.max_aggregate_bytes,
402        })
403}
404
405fn enforce_aggregate_limit(
406    required: usize,
407    limits: &ConversionLimits,
408) -> Result<(), ConversionError> {
409    if required > limits.max_aggregate_bytes {
410        Err(ConversionError::AggregateByteLimitExceeded {
411            required,
412            maximum: limits.max_aggregate_bytes,
413        })
414    } else {
415        Ok(())
416    }
417}
418
419fn enforce_depth(depth: usize, limits: &ConversionLimits) -> Result<(), ConversionError> {
420    if depth > limits.max_depth {
421        Err(ConversionError::ConversionDepthExceeded {
422            depth,
423            maximum: limits.max_depth,
424        })
425    } else {
426        Ok(())
427    }
428}
429
430fn materialize_value(
431    value: ExcelValueRef<'_>,
432    depth: usize,
433) -> Result<ExcelValue, ConversionError> {
434    match value {
435        ExcelValueRef::Number(value) => Ok(ExcelValue::Number(value)),
436        ExcelValueRef::Text(value) => Ok(ExcelValue::Text(value.into())),
437        ExcelValueRef::Boolean(value) => Ok(ExcelValue::Boolean(value)),
438        ExcelValueRef::Reference(_) => Err(ConversionError::UnsupportedReference),
439        ExcelValueRef::Error(value) => Ok(ExcelValue::Error(value)),
440        ExcelValueRef::Array(value) => {
441            if depth != 0 {
442                return Err(ConversionError::NestedArrayUnsupported);
443            }
444            materialize_array(value, depth).map(ExcelValue::Array)
445        }
446        ExcelValueRef::Missing(_) => Ok(ExcelValue::Missing),
447        ExcelValueRef::Nil(_) => Ok(ExcelValue::Empty),
448        ExcelValueRef::Integer(value) => Ok(ExcelValue::Integer(value)),
449    }
450}
451
452fn materialize_array(
453    array: ExcelArrayView<'_>,
454    depth: usize,
455) -> Result<ExcelArray, ConversionError> {
456    let (rows, columns) = array.dimensions();
457    let count = rows
458        .checked_mul(columns)
459        .ok_or(ConversionError::InvalidArrayShape)?;
460    let mut values = Vec::with_capacity(count);
461    for row in 0..rows {
462        for column in 0..columns {
463            let value = array
464                .get(row, column)?
465                .ok_or(ConversionError::InvalidArrayShape)?;
466            values.push(materialize_value(value, depth + 1)?);
467        }
468    }
469    ExcelArray::new(rows, columns, values).map_err(Into::into)
470}
471
472fn unexpected(expected: &'static str, actual: &ExcelValueRef<'_>) -> ConversionError {
473    ConversionError::UnexpectedType {
474        expected,
475        actual: actual.kind_name(),
476    }
477}
478
479#[cfg(test)]
480mod tests {
481    use excel_api_sys::{
482        XLOPER12, XLOPER12Array, XLOPER12SRef, XLOPER12Value, XLREF12, xltypeBool, xltypeErr,
483        xltypeInt, xltypeMissing, xltypeMulti, xltypeNil, xltypeNum, xltypeSRef, xltypeStr,
484    };
485
486    use crate::{RawExcelValue, Utf16ConversionError};
487
488    use super::*;
489
490    fn raw(value: XLOPER12Value, xltype: u32) -> XLOPER12 {
491        XLOPER12 { val: value, xltype }
492    }
493
494    fn decode(value: &XLOPER12) -> ExcelValueRef<'_> {
495        // SAFETY: each fixture keeps all reachable SDK storage initialized,
496        // immutable, and alive while the returned callback view is used.
497        unsafe { RawExcelValue::from_callback(value) }
498            .decode()
499            .unwrap()
500    }
501
502    #[test]
503    fn deep_copy_preserves_scalars_missing_empty_and_integer() {
504        let fixtures = [
505            (
506                raw(XLOPER12Value { num: 1.25 }, xltypeNum),
507                ExcelValue::Number(1.25),
508            ),
509            (
510                raw(XLOPER12Value { w: -7 }, xltypeInt),
511                ExcelValue::Integer(-7),
512            ),
513            (
514                raw(XLOPER12Value { xbool: 1 }, xltypeBool),
515                ExcelValue::Boolean(true),
516            ),
517            (
518                raw(
519                    XLOPER12Value {
520                        err: excel_api_sys::xlerrRef,
521                    },
522                    xltypeErr,
523                ),
524                ExcelValue::Error(ExcelError::Ref),
525            ),
526            (
527                raw(XLOPER12Value { w: 0 }, xltypeMissing),
528                ExcelValue::Missing,
529            ),
530            (raw(XLOPER12Value { w: 0 }, xltypeNil), ExcelValue::Empty),
531        ];
532
533        for (fixture, expected) in &fixtures {
534            assert_eq!(
535                ExcelValue::from_excel(decode(fixture)),
536                Ok(expected.clone())
537            );
538        }
539    }
540
541    #[test]
542    fn borrowed_text_copy_is_independent_and_preserves_code_units() {
543        let mut storage = [4_u16, b'A' as u16, 0, 0xD800, 0xDC00];
544        let raw = raw(
545            XLOPER12Value {
546                str: storage.as_mut_ptr(),
547            },
548            xltypeStr,
549        );
550        let owned = ExcelString::from_excel(decode(&raw)).unwrap();
551        storage[1..].fill(b'Z' as u16);
552
553        assert_eq!(owned.as_utf16(), &[b'A' as u16, 0, 0xD800, 0xDC00]);
554    }
555
556    #[test]
557    fn strict_string_conversion_rejects_unpaired_surrogates() {
558        let mut storage = [1_u16, 0xD800];
559        let raw = raw(
560            XLOPER12Value {
561                str: storage.as_mut_ptr(),
562            },
563            xltypeStr,
564        );
565        assert_eq!(
566            String::from_excel(decode(&raw)),
567            Err(ConversionError::InvalidUtf16)
568        );
569
570        let owned = ExcelString::from_utf16_units([0xD800].to_vec());
571        assert_eq!(String::try_from(&owned), Err(Utf16ConversionError));
572    }
573
574    #[test]
575    fn deep_copied_mixed_array_is_independent_and_row_major() {
576        let mut text = [3_u16, b'X' as u16, 0, 0xD800];
577        let mut elements = [
578            raw(XLOPER12Value { num: 1.5 }, xltypeNum),
579            raw(XLOPER12Value { w: 2 }, xltypeInt),
580            raw(
581                XLOPER12Value {
582                    str: text.as_mut_ptr(),
583                },
584                xltypeStr,
585            ),
586            raw(
587                XLOPER12Value {
588                    err: excel_api_sys::xlerrNA,
589                },
590                xltypeErr,
591            ),
592        ];
593        let root = raw(
594            XLOPER12Value {
595                array: XLOPER12Array {
596                    lparray: elements.as_mut_ptr(),
597                    rows: 2,
598                    columns: 2,
599                },
600            },
601            xltypeMulti,
602        );
603
604        let owned = ExcelArray::from_excel(decode(&root)).unwrap();
605        text[1..].fill(b'Z' as u16);
606        elements[0] = raw(XLOPER12Value { num: 99.0 }, xltypeNum);
607        assert_eq!(elements[0].xltype, xltypeNum);
608        let ExcelValueRef::Array(overwritten_source) = decode(&root) else {
609            panic!("expected source array");
610        };
611        assert!(matches!(
612            overwritten_source.get(0, 0),
613            Ok(Some(ExcelValueRef::Number(99.0)))
614        ));
615
616        assert_eq!(owned.get(0, 0), Some(&ExcelValue::Number(1.5)));
617        assert_eq!(owned.get(0, 1), Some(&ExcelValue::Integer(2)));
618        assert_eq!(
619            owned.get(1, 0),
620            Some(&ExcelValue::Text(ExcelString::from_utf16_units(
621                [b'X' as u16, 0, 0xD800].to_vec()
622            )))
623        );
624        assert_eq!(owned.get(1, 1), Some(&ExcelValue::Error(ExcelError::Na)));
625    }
626
627    #[test]
628    fn references_are_rejected_without_coercion() {
629        let reference = raw(
630            XLOPER12Value {
631                sref: XLOPER12SRef {
632                    count: 1,
633                    reference: XLREF12::default(),
634                },
635            },
636            xltypeSRef,
637        );
638        assert_eq!(
639            ExcelValue::from_excel(decode(&reference)),
640            Err(ConversionError::UnsupportedReference)
641        );
642    }
643
644    #[test]
645    fn conversion_limits_are_enforced_before_copying() {
646        let mut text = [3_u16, b'A' as u16, b'B' as u16, b'C' as u16];
647        let raw_text = raw(
648            XLOPER12Value {
649                str: text.as_mut_ptr(),
650            },
651            xltypeStr,
652        );
653        let limits = ConversionLimits {
654            max_string_code_units: 2,
655            ..ConversionLimits::default()
656        };
657        assert_eq!(
658            ExcelValue::from_borrowed_with_limits(decode(&raw_text), &limits),
659            Err(ConversionError::StringLimitExceeded {
660                actual: 3,
661                maximum: 2,
662            })
663        );
664
665        let mut elements = [
666            raw(XLOPER12Value { num: 1.0 }, xltypeNum),
667            raw(XLOPER12Value { num: 2.0 }, xltypeNum),
668        ];
669        let root = raw(
670            XLOPER12Value {
671                array: XLOPER12Array {
672                    lparray: elements.as_mut_ptr(),
673                    rows: 1,
674                    columns: 2,
675                },
676            },
677            xltypeMulti,
678        );
679        let limits = ConversionLimits {
680            max_array_elements: 1,
681            ..ConversionLimits::default()
682        };
683        assert_eq!(
684            ExcelArray::from_borrowed_with_limits(decode(&root), &limits),
685            Err(ConversionError::ArrayElementLimitExceeded {
686                actual: 2,
687                maximum: 1,
688            })
689        );
690
691        let limits = ConversionLimits {
692            max_aggregate_bytes: size_of::<ExcelValue>() * 2 - 1,
693            ..ConversionLimits::default()
694        };
695        assert!(matches!(
696            ExcelArray::from_borrowed_with_limits(decode(&root), &limits),
697            Err(ConversionError::AggregateByteLimitExceeded { .. })
698        ));
699
700        let mut text_element = raw(
701            XLOPER12Value {
702                str: text.as_mut_ptr(),
703            },
704            xltypeStr,
705        );
706        let text_array = raw(
707            XLOPER12Value {
708                array: XLOPER12Array {
709                    lparray: &mut text_element,
710                    rows: 1,
711                    columns: 1,
712                },
713            },
714            xltypeMulti,
715        );
716        let required = size_of::<ExcelValue>() + 3 * size_of::<u16>();
717        let limits = ConversionLimits {
718            max_aggregate_bytes: required - 1,
719            ..ConversionLimits::default()
720        };
721        assert_eq!(
722            ExcelArray::from_borrowed_with_limits(decode(&text_array), &limits),
723            Err(ConversionError::AggregateByteLimitExceeded {
724                required,
725                maximum: required - 1,
726            })
727        );
728
729        let limits = ConversionLimits {
730            max_depth: 0,
731            ..ConversionLimits::default()
732        };
733        assert_eq!(
734            ExcelArray::from_borrowed_with_limits(decode(&root), &limits),
735            Err(ConversionError::ConversionDepthExceeded {
736                depth: 1,
737                maximum: 0,
738            })
739        );
740    }
741
742    #[test]
743    fn numeric_conversions_follow_checked_policy() {
744        assert_eq!(f64::from_excel(ExcelValueRef::Integer(-7)), Ok(-7.0));
745        assert_eq!(i32::from_excel(ExcelValueRef::Integer(-7)), Ok(-7));
746        assert_eq!(
747            u32::from_excel(ExcelValueRef::Integer(-1)),
748            Err(ConversionError::IntegerOutOfRange)
749        );
750        assert_eq!(i32::from_excel(ExcelValueRef::Number(42.0)), Ok(42));
751        assert_eq!(
752            i32::from_excel(ExcelValueRef::Number(1.5)),
753            Err(ConversionError::NonIntegralNumber)
754        );
755        assert_eq!(
756            i32::from_excel(ExcelValueRef::Number(f64::NAN)),
757            Err(ConversionError::NonFiniteNumber)
758        );
759        assert_eq!(
760            i32::from_excel(ExcelValueRef::Number(f64::INFINITY)),
761            Err(ConversionError::NonFiniteNumber)
762        );
763        assert_eq!(
764            i16::from_excel(ExcelValueRef::Number(f64::from(i16::MIN))),
765            Ok(i16::MIN)
766        );
767        assert_eq!(
768            i16::from_excel(ExcelValueRef::Number(f64::from(i16::MAX))),
769            Ok(i16::MAX)
770        );
771        assert_eq!(
772            i32::from_excel(ExcelValueRef::Number(f64::from(i32::MIN))),
773            Ok(i32::MIN)
774        );
775        assert_eq!(
776            i32::from_excel(ExcelValueRef::Number(f64::from(i32::MAX))),
777            Ok(i32::MAX)
778        );
779        assert_eq!(u16::from_excel(ExcelValueRef::Number(0.0)), Ok(u16::MIN));
780        assert_eq!(
781            u16::from_excel(ExcelValueRef::Number(f64::from(u16::MAX))),
782            Ok(u16::MAX)
783        );
784        assert_eq!(u32::from_excel(ExcelValueRef::Number(0.0)), Ok(u32::MIN));
785        assert_eq!(
786            u32::from_excel(ExcelValueRef::Number(f64::from(u32::MAX))),
787            Ok(u32::MAX)
788        );
789        assert_eq!(
790            i16::from_excel(ExcelValueRef::Number(f64::from(i16::MAX) + 1.0)),
791            Err(ConversionError::IntegerOutOfRange)
792        );
793        assert_eq!(
794            u32::from_excel(ExcelValueRef::Number(-1.0)),
795            Err(ConversionError::IntegerOutOfRange)
796        );
797    }
798
799    #[test]
800    fn boolean_and_error_conversions_require_exact_types() {
801        assert_eq!(bool::from_excel(ExcelValueRef::Boolean(true)), Ok(true));
802        assert_eq!(
803            ExcelError::from_excel(ExcelValueRef::Error(ExcelError::Div0)),
804            Ok(ExcelError::Div0)
805        );
806        assert!(matches!(
807            bool::from_excel(ExcelValueRef::Number(1.0)),
808            Err(ConversionError::UnexpectedType {
809                expected: "boolean",
810                actual: "number",
811            })
812        ));
813    }
814
815    #[test]
816    fn into_excel_preserves_i32_backed_integer_semantics() {
817        assert_eq!(7_i16.into_excel(), Ok(ExcelValue::Integer(7)));
818        assert_eq!(7_u16.into_excel(), Ok(ExcelValue::Integer(7)));
819        assert_eq!(7_i32.into_excel(), Ok(ExcelValue::Integer(7)));
820        assert_eq!(
821            u32::MAX.into_excel(),
822            Ok(ExcelValue::Number(f64::from(u32::MAX)))
823        );
824    }
825
826    #[test]
827    fn option_and_optional_value_have_documented_empty_policy() {
828        let missing = raw(XLOPER12Value { w: 0 }, xltypeMissing);
829        let empty = raw(XLOPER12Value { w: 0 }, xltypeNil);
830        let integer = raw(XLOPER12Value { w: 3 }, xltypeInt);
831
832        assert_eq!(Option::<i32>::from_excel(decode(&missing)), Ok(None));
833        assert_eq!(Option::<i32>::from_excel(decode(&empty)), Ok(None));
834        assert_eq!(
835            OptionalValue::<i32>::from_excel(decode(&missing)),
836            Ok(OptionalValue::Missing)
837        );
838        assert_eq!(
839            OptionalValue::<i32>::from_excel(decode(&empty)),
840            Ok(OptionalValue::Empty)
841        );
842        assert_eq!(
843            OptionalValue::<i32>::from_excel(decode(&integer)),
844            Ok(OptionalValue::Value(3))
845        );
846    }
847}