Skip to main content

excel_api/
metadata.rs

1//! Explicit argument families used by worksheet-function metadata.
2//!
3//! These wrappers remove the otherwise ambiguous choice between Excel's `Q`
4//! value-only and `U` reference-preserving registration forms. They carry no
5//! independent ownership authority; M9B thunks construct them only from values
6//! tied to the generated callback scope.
7
8use crate::{ConversionError, ExcelStr, ExcelValueRef, FromExcel};
9
10/// A callback value registered with Excel's value-only `Q` type.
11#[derive(Debug)]
12pub struct ExcelValueArg<'call>(ExcelValueRef<'call>);
13
14impl<'call> ExcelValueArg<'call> {
15    /// Wraps a callback value for a `Q`-registered parameter.
16    pub const fn new(value: ExcelValueRef<'call>) -> Self {
17        Self(value)
18    }
19
20    /// Returns the callback-borrowed value, consuming this metadata wrapper.
21    pub fn into_inner(self) -> ExcelValueRef<'call> {
22        self.0
23    }
24}
25
26impl<'call> FromExcel<'call> for ExcelValueArg<'call> {
27    fn from_excel(value: ExcelValueRef<'call>) -> Result<Self, ConversionError> {
28        Ok(Self::new(value))
29    }
30}
31
32/// A callback value registered with Excel's reference-preserving `U` type.
33#[derive(Debug)]
34pub struct ExcelReferenceArg<'call>(ExcelValueRef<'call>);
35
36impl<'call> ExcelReferenceArg<'call> {
37    /// Wraps a callback value for a `U`-registered parameter.
38    pub const fn new(value: ExcelValueRef<'call>) -> Self {
39        Self(value)
40    }
41
42    /// Returns the callback-borrowed value, consuming this metadata wrapper.
43    pub fn into_inner(self) -> ExcelValueRef<'call> {
44        self.0
45    }
46}
47
48impl<'call> FromExcel<'call> for ExcelReferenceArg<'call> {
49    fn from_excel(value: ExcelValueRef<'call>) -> Result<Self, ConversionError> {
50        Ok(Self::new(value))
51    }
52}
53
54/// A direct UTF-16 argument registered with Excel's counted `D%` type.
55#[derive(Debug)]
56pub struct CountedUtf16Arg<'call>(ExcelStr<'call>);
57
58impl<'call> CountedUtf16Arg<'call> {
59    /// Wraps a validated counted direct UTF-16 callback argument.
60    pub const fn new(value: ExcelStr<'call>) -> Self {
61        Self(value)
62    }
63
64    /// Borrows the underlying UTF-16 view for no longer than this callback.
65    pub const fn as_excel_str(&self) -> &ExcelStr<'call> {
66        &self.0
67    }
68
69    /// Returns the callback-borrowed UTF-16 view, consuming this wrapper.
70    pub fn into_inner(self) -> ExcelStr<'call> {
71        self.0
72    }
73}
74
75/// A direct UTF-16 argument registered with Excel's NUL-terminated `C%` type.
76#[derive(Debug)]
77pub struct NullTerminatedUtf16Arg<'call>(ExcelStr<'call>);
78
79impl<'call> NullTerminatedUtf16Arg<'call> {
80    /// Wraps a validated NUL-terminated direct UTF-16 callback argument.
81    pub const fn new(value: ExcelStr<'call>) -> Self {
82        Self(value)
83    }
84
85    /// Borrows the underlying UTF-16 view for no longer than this callback.
86    pub const fn as_excel_str(&self) -> &ExcelStr<'call> {
87        &self.0
88    }
89
90    /// Returns the callback-borrowed UTF-16 view, consuming this wrapper.
91    pub fn into_inner(self) -> ExcelStr<'call> {
92        self.0
93    }
94}