1use core::fmt;
2
3use crate::DecodeError;
4
5#[derive(Clone, Copy, Debug, Eq, PartialEq)]
7pub enum ExcelError {
8 Null,
10 Div0,
12 Value,
14 Ref,
16 Name,
18 Num,
20 Na,
22 GettingData,
24}
25
26impl From<excel_api_sys::XlError> for ExcelError {
27 fn from(value: excel_api_sys::XlError) -> Self {
28 match value {
29 excel_api_sys::XlError::Null => Self::Null,
30 excel_api_sys::XlError::Div0 => Self::Div0,
31 excel_api_sys::XlError::Value => Self::Value,
32 excel_api_sys::XlError::Ref => Self::Ref,
33 excel_api_sys::XlError::Name => Self::Name,
34 excel_api_sys::XlError::Num => Self::Num,
35 excel_api_sys::XlError::Na => Self::Na,
36 excel_api_sys::XlError::GettingData => Self::GettingData,
37 }
38 }
39}
40
41#[derive(Clone, Copy, Debug, Eq, PartialEq)]
44pub struct Utf16ConversionError;
45
46impl fmt::Display for Utf16ConversionError {
47 fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
48 formatter.write_str("UTF-16 payload contains an unpaired surrogate")
49 }
50}
51
52impl std::error::Error for Utf16ConversionError {}
53
54#[derive(Clone, Debug, Eq, PartialEq)]
56pub enum OwnedValueError {
57 ArrayShapeOverflow {
59 rows: usize,
61 columns: usize,
63 },
64 InvalidArrayShape {
66 rows: usize,
68 columns: usize,
70 elements: usize,
72 },
73 NestedArrayUnsupported,
75}
76
77impl fmt::Display for OwnedValueError {
78 fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
79 match self {
80 Self::ArrayShapeOverflow { rows, columns } => {
81 write!(formatter, "array shape {rows} x {columns} overflows usize")
82 }
83 Self::InvalidArrayShape {
84 rows,
85 columns,
86 elements,
87 } => write!(
88 formatter,
89 "array shape {rows} x {columns} does not match {elements} elements"
90 ),
91 Self::NestedArrayUnsupported => {
92 formatter.write_str("nested Excel arrays are unsupported")
93 }
94 }
95 }
96}
97
98impl std::error::Error for OwnedValueError {}
99
100#[derive(Clone, Debug, Eq, PartialEq)]
103pub enum ConversionError {
104 UnexpectedType {
106 expected: &'static str,
108 actual: &'static str,
110 },
111 UnsupportedReference,
113 InvalidUtf16,
115 NonFiniteNumber,
117 NonIntegralNumber,
119 IntegerOutOfRange,
121 InvalidArrayShape,
123 StringLimitExceeded {
125 actual: usize,
127 maximum: usize,
129 },
130 ArrayElementLimitExceeded {
132 actual: usize,
134 maximum: usize,
136 },
137 AggregateByteLimitExceeded {
139 required: usize,
141 maximum: usize,
143 },
144 NestedArrayUnsupported,
146 ConversionDepthExceeded {
148 depth: usize,
150 maximum: usize,
152 },
153 BorrowedValueDecode(DecodeError),
155}
156
157impl fmt::Display for ConversionError {
158 fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
159 match self {
160 Self::UnexpectedType { expected, actual } => {
161 write!(formatter, "expected {expected}, received {actual}")
162 }
163 Self::UnsupportedReference => {
164 formatter.write_str("Excel references require explicit coercion")
165 }
166 Self::InvalidUtf16 => formatter.write_str("Excel text is not valid UTF-16"),
167 Self::NonFiniteNumber => formatter.write_str("number is not finite"),
168 Self::NonIntegralNumber => formatter.write_str("number is not an integer"),
169 Self::IntegerOutOfRange => formatter.write_str("integer is out of range"),
170 Self::InvalidArrayShape => formatter.write_str("array shape is invalid"),
171 Self::StringLimitExceeded { actual, maximum } => write!(
172 formatter,
173 "string has {actual} UTF-16 code units; conversion limit is {maximum}"
174 ),
175 Self::ArrayElementLimitExceeded { actual, maximum } => write!(
176 formatter,
177 "array has {actual} elements; conversion limit is {maximum}"
178 ),
179 Self::AggregateByteLimitExceeded { required, maximum } => write!(
180 formatter,
181 "conversion requires at least {required} bytes; limit is {maximum}"
182 ),
183 Self::NestedArrayUnsupported => {
184 formatter.write_str("nested Excel arrays are unsupported")
185 }
186 Self::ConversionDepthExceeded { depth, maximum } => write!(
187 formatter,
188 "conversion depth {depth} exceeds limit {maximum}"
189 ),
190 Self::BorrowedValueDecode(error) => {
191 write!(formatter, "borrowed Excel value became invalid: {error}")
192 }
193 }
194 }
195}
196
197impl std::error::Error for ConversionError {
198 fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
199 match self {
200 Self::BorrowedValueDecode(error) => Some(error),
201 _ => None,
202 }
203 }
204}
205
206impl From<Utf16ConversionError> for ConversionError {
207 fn from(_: Utf16ConversionError) -> Self {
208 Self::InvalidUtf16
209 }
210}
211
212impl From<DecodeError> for ConversionError {
213 fn from(error: DecodeError) -> Self {
214 Self::BorrowedValueDecode(error)
215 }
216}
217
218impl From<OwnedValueError> for ConversionError {
219 fn from(error: OwnedValueError) -> Self {
220 match error {
221 OwnedValueError::NestedArrayUnsupported => Self::NestedArrayUnsupported,
222 OwnedValueError::ArrayShapeOverflow { .. }
223 | OwnedValueError::InvalidArrayShape { .. } => Self::InvalidArrayShape,
224 }
225 }
226}
227
228#[derive(Clone, Debug, Eq, PartialEq)]
233pub enum ReturnError {
234 StringTooLongForExcel {
236 actual: usize,
238 maximum: usize,
240 },
241 StringLimitExceeded {
243 actual: usize,
245 maximum: usize,
247 },
248 InvalidArrayShape {
250 rows: usize,
252 columns: usize,
254 elements: usize,
256 },
257 EmptyArrayUnsupported,
259 ArrayDimensionExceedsAbi {
261 rows: usize,
263 columns: usize,
265 },
266 ArrayElementCountOverflow {
268 rows: usize,
270 columns: usize,
272 },
273 ArrayElementLimitExceeded {
275 actual: usize,
277 maximum: usize,
279 },
280 NestedArrayUnsupported,
282 ReferenceUnsupported,
284 UnsupportedSemanticVariant {
286 variant: &'static str,
288 },
289 TotalByteOverflow,
291 TotalByteLimitExceeded {
293 required: usize,
295 maximum: usize,
297 },
298 AllocationCountOverflow,
300 AllocationCountLimitExceeded {
302 required: usize,
304 maximum: usize,
306 },
307 PlanningDepthExceeded {
309 depth: usize,
311 maximum: usize,
313 },
314}
315
316impl fmt::Display for ReturnError {
317 fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
318 match self {
319 Self::StringTooLongForExcel { actual, maximum } => write!(
320 formatter,
321 "return string has {actual} UTF-16 code units; Excel supports at most {maximum}"
322 ),
323 Self::StringLimitExceeded { actual, maximum } => write!(
324 formatter,
325 "return string has {actual} UTF-16 code units; project limit is {maximum}"
326 ),
327 Self::InvalidArrayShape {
328 rows,
329 columns,
330 elements,
331 } => write!(
332 formatter,
333 "return array shape {rows} x {columns} does not match {elements} elements"
334 ),
335 Self::EmptyArrayUnsupported => formatter.write_str(
336 "zero-dimensional xltypeMulti returns are unsupported; return Empty instead",
337 ),
338 Self::ArrayDimensionExceedsAbi { rows, columns } => write!(
339 formatter,
340 "return array dimensions {rows} x {columns} exceed the Excel 12 ABI limits"
341 ),
342 Self::ArrayElementCountOverflow { rows, columns } => write!(
343 formatter,
344 "return array element count {rows} x {columns} overflows usize"
345 ),
346 Self::ArrayElementLimitExceeded { actual, maximum } => write!(
347 formatter,
348 "return array has {actual} elements; project limit is {maximum}"
349 ),
350 Self::NestedArrayUnsupported => {
351 formatter.write_str("nested Excel return arrays are unsupported")
352 }
353 Self::ReferenceUnsupported => {
354 formatter.write_str("Excel references are unsupported return values")
355 }
356 Self::UnsupportedSemanticVariant { variant } => {
357 write!(
358 formatter,
359 "semantic variant {variant} is unsupported for returns"
360 )
361 }
362 Self::TotalByteOverflow => {
363 formatter.write_str("return storage byte accounting overflowed usize")
364 }
365 Self::TotalByteLimitExceeded { required, maximum } => write!(
366 formatter,
367 "return requires {required} ABI storage bytes; project limit is {maximum}"
368 ),
369 Self::AllocationCountOverflow => {
370 formatter.write_str("return allocation-count accounting overflowed usize")
371 }
372 Self::AllocationCountLimitExceeded { required, maximum } => write!(
373 formatter,
374 "return requires {required} allocations; project limit is {maximum}"
375 ),
376 Self::PlanningDepthExceeded { depth, maximum } => write!(
377 formatter,
378 "return planning depth {depth} exceeds project limit {maximum}"
379 ),
380 }
381 }
382}
383
384impl std::error::Error for ReturnError {}
385
386#[derive(Clone, Debug, Eq, PartialEq)]
388pub enum ReturnMaterializationError {
389 PlanStorageInvariantMismatch {
391 field: &'static str,
393 planned: usize,
395 actual: usize,
397 },
398 Utf8EncodedLengthMismatch {
400 planned: usize,
402 actual: usize,
404 },
405 StringBufferLengthMismatch {
407 planned: usize,
409 actual: usize,
411 },
412 ArrayShapeMismatch {
414 rows: usize,
416 columns: usize,
418 elements: usize,
420 },
421 UnsupportedPlannedValue {
423 variant: &'static str,
425 },
426 AllocationFailure {
428 storage: &'static str,
430 },
431 InjectedTestFailure {
433 stage: &'static str,
435 },
436}
437
438impl fmt::Display for ReturnMaterializationError {
439 fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
440 match self {
441 Self::PlanStorageInvariantMismatch {
442 field,
443 planned,
444 actual,
445 } => write!(
446 formatter,
447 "return plan {field} is {planned}, but materialized storage requires {actual}"
448 ),
449 Self::Utf8EncodedLengthMismatch { planned, actual } => write!(
450 formatter,
451 "planned UTF-8 text requires {planned} UTF-16 units, but encoding produced {actual}"
452 ),
453 Self::StringBufferLengthMismatch { planned, actual } => write!(
454 formatter,
455 "planned counted string requires {planned} units, but materialization produced {actual}"
456 ),
457 Self::ArrayShapeMismatch {
458 rows,
459 columns,
460 elements,
461 } => write!(
462 formatter,
463 "planned return array shape {rows} x {columns} does not match {elements} elements"
464 ),
465 Self::UnsupportedPlannedValue { variant } => {
466 write!(formatter, "planned value {variant} cannot be materialized")
467 }
468 Self::AllocationFailure { storage } => {
469 write!(formatter, "could not allocate {storage} return storage")
470 }
471 Self::InjectedTestFailure { stage } => {
472 write!(formatter, "test injected a failure at {stage}")
473 }
474 }
475 }
476}
477
478impl std::error::Error for ReturnMaterializationError {}
479
480#[derive(Debug)]
481pub enum ThunkError {
483 NullArgument,
485 Decode(DecodeError),
487 Conversion(ConversionError),
489 Function(ExcelError),
491 ReturnPlanning(ReturnError),
493 Materialization(ReturnMaterializationError),
495}
496
497impl fmt::Display for ThunkError {
498 fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
499 match self {
500 Self::NullArgument => formatter.write_str("Excel supplied a null argument pointer"),
501 Self::Decode(error) => write!(formatter, "Excel argument decoding failed: {error}"),
502 Self::Conversion(error) => {
503 write!(formatter, "Excel argument conversion failed: {error}")
504 }
505 Self::Function(error) => write!(formatter, "worksheet function returned {error:?}"),
506 Self::ReturnPlanning(error) => write!(formatter, "return planning failed: {error}"),
507 Self::Materialization(error) => {
508 write!(formatter, "return materialization failed: {error}")
509 }
510 }
511 }
512}
513
514impl std::error::Error for ThunkError {}
515
516impl fmt::Display for DecodeError {
517 fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
518 write!(formatter, "{self:?}")
519 }
520}
521
522impl std::error::Error for DecodeError {}