Debian Codegraph @

.cargo/vendor/zerocopy/src/error.rs

raw
1 // Copyright 2024 The Fuchsia Authors
2 //
3 // Licensed under the 2-Clause BSD License <LICENSE-BSD or
4 // https://opensource.org/license/bsd-2-clause>, Apache License, Version 2.0
5 // <LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0>, or the MIT
6 // license <LICENSE-MIT or https://opensource.org/licenses/MIT>, at your option.
7 // This file may not be copied, modified, or distributed except according to
8 // those terms.
9
10 //! Types related to error reporting.
11 //!
12 //! ## Single failure mode errors
13 //!
14 //! Generally speaking, zerocopy's conversions may fail for one of up to three
15 //! reasons:
16 //! - [`AlignmentError`]: the conversion source was improperly aligned
17 //! - [`SizeError`]: the conversion source was of incorrect size
18 //! - [`ValidityError`]: the conversion source contained invalid data
19 //!
20 //! Methods that only have one failure mode, like
21 //! [`FromBytes::read_from_bytes`], return that mode's corresponding error type
22 //! directly.
23 //!
24 //! ## Compound errors
25 //!
26 //! Conversion methods that have either two or three possible failure modes
27 //! return one of these error types:
28 //! - [`CastError`]: the error type of reference conversions
29 //! - [`TryCastError`]: the error type of fallible reference conversions
30 //! - [`TryReadError`]: the error type of fallible read conversions
31 //!
32 //! ## [`Unaligned`] destination types
33 //!
34 //! For [`Unaligned`] destination types, alignment errors are impossible. All
35 //! compound error types support infallibly discarding the alignment error via
36 //! [`From`] so long as `Dst: Unaligned`. For example, see [`<SizeError as
37 //! From<ConvertError>>::from`][size-error-from].
38 //!
39 //! [size-error-from]: struct.SizeError.html#method.from-1
40 //!
41 //! ## Accessing the conversion source
42 //!
43 //! All error types provide an `into_src` method that converts the error into
44 //! the source value underlying the failed conversion.
45 //!
46 //! ## Display formatting
47 //!
48 //! All error types provide a `Display` implementation that produces a
49 //! human-readable error message. When `debug_assertions` are enabled, these
50 //! error messages are verbose and may include potentially sensitive
51 //! information, including:
52 //!
53 //! - the names of the involved types
54 //! - the sizes of the involved types
55 //! - the addresses of the involved types
56 //! - the contents of the involved types
57 //!
58 //! When `debug_assertions` are disabled (as is default for `release` builds),
59 //! such potentially sensitive information is excluded.
60 //!
61 //! In the future, we may support manually configuring this behavior. If you are
62 //! interested in this feature, [let us know on GitHub][issue-1457] so we know
63 //! to prioritize it.
64 //!
65 //! [issue-1457]: https://github.com/google/zerocopy/issues/1457
66 //!
67 //! ## Validation order
68 //!
69 //! Our conversion methods typically check alignment, then size, then bit
70 //! validity. However, we do not guarantee that this is always the case, and
71 //! this behavior may change between releases.
72 //!
73 //! ## `Send`, `Sync`, and `'static`
74 //!
75 //! Our error types are `Send`, `Sync`, and `'static` when their `Src` parameter
76 //! is `Send`, `Sync`, or `'static`, respectively. This can cause issues when an
77 //! error is sent or synchronized across threads; e.g.:
78 //!
79 //! ```compile_fail,E0515
80 //! use zerocopy::*;
81 //!
82 //! let result: SizeError<&[u8], u32> = std::thread::spawn(|| {
83 //! let source = &mut [0u8, 1, 2][..];
84 //! // Try (and fail) to read a `u32` from `source`.
85 //! u32::read_from_bytes(source).unwrap_err()
86 //! }).join().unwrap();
87 //! ```
88 //!
89 //! To work around this, use [`map_src`][CastError::map_src] to convert the
90 //! source parameter to an unproblematic type; e.g.:
91 //!
92 //! ```
93 //! use zerocopy::*;
94 //!
95 //! let result: SizeError<(), u32> = std::thread::spawn(|| {
96 //! let source = &mut [0u8, 1, 2][..];
97 //! // Try (and fail) to read a `u32` from `source`.
98 //! u32::read_from_bytes(source).unwrap_err()
99 //! // Erase the error source.
100 //! .map_src(drop)
101 //! }).join().unwrap();
102 //! ```
103 //!
104 //! Alternatively, use `.to_string()` to eagerly convert the error into a
105 //! human-readable message; e.g.:
106 //!
107 //! ```
108 //! use zerocopy::*;
109 //!
110 //! let result: Result<u32, String> = std::thread::spawn(|| {
111 //! let source = &mut [0u8, 1, 2][..];
112 //! // Try (and fail) to read a `u32` from `source`.
113 //! u32::read_from_bytes(source)
114 //! // Eagerly render the error message.
115 //! .map_err(|err| err.to_string())
116 //! }).join().unwrap();
117 //! ```
118 #[cfg(zerocopy_core_error_1_81_0)]
119 use core::error::Error;
120 use core::{
121 convert::Infallible,
122 fmt::{self, Debug, Write},
123 ops::Deref,
124 };
125 #[cfg(all(not(zerocopy_core_error_1_81_0), any(feature = "std", test)))]
126 use std::error::Error;
127
128 use crate::{util::SendSyncPhantomData, KnownLayout, TryFromBytes, Unaligned};
129 #[cfg(doc)]
130 use crate::{FromBytes, Ref};
131
132 /// Zerocopy's generic error type.
133 ///
134 /// Generally speaking, zerocopy's conversions may fail for one of up to three
135 /// reasons:
136 /// - [`AlignmentError`]: the conversion source was improperly aligned
137 /// - [`SizeError`]: the conversion source was of incorrect size
138 /// - [`ValidityError`]: the conversion source contained invalid data
139 ///
140 /// However, not all conversions produce all errors. For instance,
141 /// [`FromBytes::ref_from_bytes`] may fail due to alignment or size issues, but
142 /// not validity issues. This generic error type captures these
143 /// (im)possibilities via parameterization: `A` is parameterized with
144 /// [`AlignmentError`], `S` is parameterized with [`SizeError`], and `V` is
145 /// parameterized with [`Infallible`].
146 ///
147 /// Zerocopy never uses this type directly in its API. Rather, we provide three
148 /// pre-parameterized aliases:
149 /// - [`CastError`]: the error type of reference conversions
150 /// - [`TryCastError`]: the error type of fallible reference conversions
151 /// - [`TryReadError`]: the error type of fallible read conversions
152 #[derive(PartialEq, Eq)]
153 pub enum ConvertError<A, S, V> {
154 /// The conversion source was improperly aligned.
155 Alignment(A),
156 /// The conversion source was of incorrect size.
157 Size(S),
158 /// The conversion source contained invalid data.
159 Validity(V),
160 }
161
162 impl<Src, Dst: ?Sized + Unaligned, S, V> From<ConvertError<AlignmentError<Src, Dst>, S, V>>
163 for ConvertError<Infallible, S, V>
164 {
165 /// Infallibly discards the alignment error from this `ConvertError` since
166 /// `Dst` is unaligned.
167 ///
168 /// Since [`Dst: Unaligned`], it is impossible to encounter an alignment
169 /// error. This method permits discarding that alignment error infallibly
170 /// and replacing it with [`Infallible`].
171 ///
172 /// [`Dst: Unaligned`]: crate::Unaligned
173 ///
174 /// # Examples
175 ///
176 /// ```
177 /// use core::convert::Infallible;
178 /// use zerocopy::*;
179 /// # use zerocopy_derive::*;
180 ///
181 /// #[derive(TryFromBytes, KnownLayout, Unaligned, Immutable)]
182 /// #[repr(C, packed)]
183 /// struct Bools {
184 /// one: bool,
185 /// two: bool,
186 /// many: [bool],
187 /// }
188 ///
189 /// impl Bools {
190 /// fn parse(bytes: &[u8]) -> Result<&Bools, AlignedTryCastError<&[u8], Bools>> {
191 /// // Since `Bools: Unaligned`, we can infallibly discard
192 /// // the alignment error.
193 /// Bools::try_ref_from_bytes(bytes).map_err(Into::into)
194 /// }
195 /// }
196 /// ```
197 #[inline]
198 fn from(err: ConvertError<AlignmentError<Src, Dst>, S, V>) -> ConvertError<Infallible, S, V> {
199 match err {
200 ConvertError::Alignment(e) => ConvertError::Alignment(Infallible::from(e)),
201 ConvertError::Size(e) => ConvertError::Size(e),
202 ConvertError::Validity(e) => ConvertError::Validity(e),
203 }
204 }
205 }
206
207 impl<A: fmt::Debug, S: fmt::Debug, V: fmt::Debug> fmt::Debug for ConvertError<A, S, V> {
208 #[inline]
209 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
210 match self {
211 Self::Alignment(e) => f.debug_tuple("Alignment").field(e).finish(),
212 Self::Size(e) => f.debug_tuple("Size").field(e).finish(),
213 Self::Validity(e) => f.debug_tuple("Validity").field(e).finish(),
214 }
215 }
216 }
217
218 /// Produces a human-readable error message.
219 ///
220 /// The message differs between debug and release builds. When
221 /// `debug_assertions` are enabled, this message is verbose and includes
222 /// potentially sensitive information.
223 impl<A: fmt::Display, S: fmt::Display, V: fmt::Display> fmt::Display for ConvertError<A, S, V> {
224 #[inline]
225 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
226 match self {
227 Self::Alignment(e) => e.fmt(f),
228 Self::Size(e) => e.fmt(f),
229 Self::Validity(e) => e.fmt(f),
230 }
231 }
232 }
233
234 #[cfg(any(zerocopy_core_error_1_81_0, feature = "std", test))]
235 #[cfg_attr(doc_cfg, doc(cfg(all(rust = "1.81.0", feature = "std"))))]
236 impl<A, S, V> Error for ConvertError<A, S, V>
237 where
238 A: fmt::Display + fmt::Debug,
239 S: fmt::Display + fmt::Debug,
240 V: fmt::Display + fmt::Debug,
241 {
242 }
243
244 /// The error emitted if the conversion source is improperly aligned.
245 #[derive(PartialEq, Eq)]
246 pub struct AlignmentError<Src, Dst: ?Sized> {
247 /// The source value involved in the conversion.
248 src: Src,
249 /// The inner destination type inolved in the conversion.
250 ///
251 /// INVARIANT: An `AlignmentError` may only be constructed if `Dst`'s
252 /// alignment requirement is greater than one.
253 dst: SendSyncPhantomData<Dst>,
254 }
255
256 impl<Src, Dst: ?Sized> AlignmentError<Src, Dst> {
257 /// # Safety
258 ///
259 /// The caller must ensure that `Dst`'s alignment requirement is greater
260 /// than one.
261 pub(crate) unsafe fn new_unchecked(src: Src) -> Self {
262 // INVARIANT: The caller guarantees that `Dst`'s alignment requirement
263 // is greater than one.
264 Self { src, dst: SendSyncPhantomData::default() }
265 }
266
267 /// Produces the source underlying the failed conversion.
268 #[inline]
269 pub fn into_src(self) -> Src {
270 self.src
271 }
272
273 pub(crate) fn with_src<NewSrc>(self, new_src: NewSrc) -> AlignmentError<NewSrc, Dst> {
274 // INVARIANT: `with_src` doesn't change the type of `Dst`, so the
275 // invariant that `Dst`'s alignment requirement is greater than one is
276 // preserved.
277 AlignmentError { src: new_src, dst: SendSyncPhantomData::default() }
278 }
279
280 /// Maps the source value associated with the conversion error.
281 ///
282 /// This can help mitigate [issues with `Send`, `Sync` and `'static`
283 /// bounds][self#send-sync-and-static].
284 ///
285 /// # Examples
286 ///
287 /// ```
288 /// use zerocopy::*;
289 ///
290 /// let unaligned = Unalign::new(0u16);
291 ///
292 /// // Attempt to deref `unaligned`. This might fail with an alignment error.
293 /// let maybe_n: Result<&u16, AlignmentError<&Unalign<u16>, u16>> = unaligned.try_deref();
294 ///
295 /// // Map the error's source to its address as a usize.
296 /// let maybe_n: Result<&u16, AlignmentError<usize, u16>> = maybe_n.map_err(|err| {
297 /// err.map_src(|src| src as *const _ as usize)
298 /// });
299 /// ```
300 #[inline]
301 pub fn map_src<NewSrc>(self, f: impl FnOnce(Src) -> NewSrc) -> AlignmentError<NewSrc, Dst> {
302 AlignmentError { src: f(self.src), dst: SendSyncPhantomData::default() }
303 }
304
305 pub(crate) fn into<S, V>(self) -> ConvertError<Self, S, V> {
306 ConvertError::Alignment(self)
307 }
308
309 /// Format extra details for a verbose, human-readable error message.
310 ///
311 /// This formatting may include potentially sensitive information.
312 fn display_verbose_extras(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result
313 where
314 Src: Deref,
315 Dst: KnownLayout,
316 {
317 #[allow(clippy::as_conversions)]
318 let addr = self.src.deref() as *const _ as *const ();
319 let addr_align = 2usize.pow((crate::util::AsAddress::addr(addr)).trailing_zeros());
320
321 f.write_str("\n\nSource type: ")?;
322 f.write_str(core::any::type_name::<Src>())?;
323
324 f.write_str("\nSource address: ")?;
325 addr.fmt(f)?;
326 f.write_str(" (a multiple of ")?;
327 addr_align.fmt(f)?;
328 f.write_str(")")?;
329
330 f.write_str("\nDestination type: ")?;
331 f.write_str(core::any::type_name::<Dst>())?;
332
333 f.write_str("\nDestination alignment: ")?;
334 <Dst as KnownLayout>::LAYOUT.align.get().fmt(f)?;
335
336 Ok(())
337 }
338 }
339
340 impl<Src, Dst: ?Sized + Unaligned> From<AlignmentError<Src, Dst>> for Infallible {
341 #[inline(always)]
342 fn from(_: AlignmentError<Src, Dst>) -> Infallible {
343 // SAFETY: `AlignmentError`s can only be constructed when `Dst`'s
344 // alignment requirement is greater than one. In this block, `Dst:
345 // Unaligned`, which means that its alignment requirement is equal to
346 // one. Thus, it's not possible to reach here at runtime.
347 unsafe { core::hint::unreachable_unchecked() }
348 }
349 }
350
351 #[cfg(test)]
352 impl<Src, Dst> AlignmentError<Src, Dst> {
353 // A convenience constructor so that test code doesn't need to write
354 // `unsafe`.
355 fn new_checked(src: Src) -> AlignmentError<Src, Dst> {
356 assert_ne!(core::mem::align_of::<Dst>(), 1);
357 // SAFETY: The preceding assertion guarantees that `Dst`'s alignment
358 // requirement is greater than one.
359 unsafe { AlignmentError::new_unchecked(src) }
360 }
361 }
362
363 impl<Src, Dst: ?Sized> fmt::Debug for AlignmentError<Src, Dst> {
364 #[inline]
365 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
366 f.debug_struct("AlignmentError").finish()
367 }
368 }
369
370 /// Produces a human-readable error message.
371 ///
372 /// The message differs between debug and release builds. When
373 /// `debug_assertions` are enabled, this message is verbose and includes
374 /// potentially sensitive information.
375 impl<Src, Dst: ?Sized> fmt::Display for AlignmentError<Src, Dst>
376 where
377 Src: Deref,
378 Dst: KnownLayout,
379 {
380 #[inline]
381 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
382 f.write_str("The conversion failed because the address of the source is not a multiple of the alignment of the destination type.")?;
383
384 if cfg!(debug_assertions) {
385 self.display_verbose_extras(f)
386 } else {
387 Ok(())
388 }
389 }
390 }
391
392 #[cfg(any(zerocopy_core_error_1_81_0, feature = "std", test))]
393 #[cfg_attr(doc_cfg, doc(cfg(all(rust = "1.81.0", feature = "std"))))]
394 impl<Src, Dst: ?Sized> Error for AlignmentError<Src, Dst>
395 where
396 Src: Deref,
397 Dst: KnownLayout,
398 {
399 }
400
401 impl<Src, Dst: ?Sized, S, V> From<AlignmentError<Src, Dst>>
402 for ConvertError<AlignmentError<Src, Dst>, S, V>
403 {
404 #[inline(always)]
405 fn from(err: AlignmentError<Src, Dst>) -> Self {
406 Self::Alignment(err)
407 }
408 }
409
410 /// The error emitted if the conversion source is of incorrect size.
411 #[derive(PartialEq, Eq)]
412 pub struct SizeError<Src, Dst: ?Sized> {
413 /// The source value involved in the conversion.
414 src: Src,
415 /// The inner destination type inolved in the conversion.
416 dst: SendSyncPhantomData<Dst>,
417 }
418
419 impl<Src, Dst: ?Sized> SizeError<Src, Dst> {
420 pub(crate) fn new(src: Src) -> Self {
421 Self { src, dst: SendSyncPhantomData::default() }
422 }
423
424 /// Produces the source underlying the failed conversion.
425 #[inline]
426 pub fn into_src(self) -> Src {
427 self.src
428 }
429
430 /// Sets the source value associated with the conversion error.
431 pub(crate) fn with_src<NewSrc>(self, new_src: NewSrc) -> SizeError<NewSrc, Dst> {
432 SizeError { src: new_src, dst: SendSyncPhantomData::default() }
433 }
434
435 /// Maps the source value associated with the conversion error.
436 ///
437 /// This can help mitigate [issues with `Send`, `Sync` and `'static`
438 /// bounds][self#send-sync-and-static].
439 ///
440 /// # Examples
441 ///
442 /// ```
443 /// use zerocopy::*;
444 ///
445 /// let source: [u8; 3] = [0, 1, 2];
446 ///
447 /// // Try to read a `u32` from `source`. This will fail because there are insufficient
448 /// // bytes in `source`.
449 /// let maybe_u32: Result<u32, SizeError<&[u8], u32>> = u32::read_from_bytes(&source[..]);
450 ///
451 /// // Map the error's source to its size.
452 /// let maybe_u32: Result<u32, SizeError<usize, u32>> = maybe_u32.map_err(|err| {
453 /// err.map_src(|src| src.len())
454 /// });
455 /// ```
456 #[inline]
457 pub fn map_src<NewSrc>(self, f: impl FnOnce(Src) -> NewSrc) -> SizeError<NewSrc, Dst> {
458 SizeError { src: f(self.src), dst: SendSyncPhantomData::default() }
459 }
460
461 /// Sets the destination type associated with the conversion error.
462 pub(crate) fn with_dst<NewDst: ?Sized>(self) -> SizeError<Src, NewDst> {
463 SizeError { src: self.src, dst: SendSyncPhantomData::default() }
464 }
465
466 /// Converts the error into a general [`ConvertError`].
467 pub(crate) fn into<A, V>(self) -> ConvertError<A, Self, V> {
468 ConvertError::Size(self)
469 }
470
471 /// Format extra details for a verbose, human-readable error message.
472 ///
473 /// This formatting may include potentially sensitive information.
474 fn display_verbose_extras(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result
475 where
476 Src: Deref,
477 Dst: KnownLayout,
478 {
479 // include the source type
480 f.write_str("\nSource type: ")?;
481 f.write_str(core::any::type_name::<Src>())?;
482
483 // include the source.deref() size
484 let src_size = core::mem::size_of_val(&*self.src);
485 f.write_str("\nSource size: ")?;
486 src_size.fmt(f)?;
487 f.write_str(" byte")?;
488 if src_size != 1 {
489 f.write_char('s')?;
490 }
491
492 // if `Dst` is `Sized`, include the `Dst` size
493 if let crate::SizeInfo::Sized { size } = Dst::LAYOUT.size_info {
494 f.write_str("\nDestination size: ")?;
495 size.fmt(f)?;
496 f.write_str(" byte")?;
497 if size != 1 {
498 f.write_char('s')?;
499 }
500 }
501
502 // include the destination type
503 f.write_str("\nDestination type: ")?;
504 f.write_str(core::any::type_name::<Dst>())?;
505
506 Ok(())
507 }
508 }
509
510 impl<Src, Dst: ?Sized> fmt::Debug for SizeError<Src, Dst> {
511 #[inline]
512 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
513 f.debug_struct("SizeError").finish()
514 }
515 }
516
517 /// Produces a human-readable error message.
518 ///
519 /// The message differs between debug and release builds. When
520 /// `debug_assertions` are enabled, this message is verbose and includes
521 /// potentially sensitive information.
522 impl<Src, Dst: ?Sized> fmt::Display for SizeError<Src, Dst>
523 where
524 Src: Deref,
525 Dst: KnownLayout,
526 {
527 #[inline]
528 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
529 f.write_str("The conversion failed because the source was incorrectly sized to complete the conversion into the destination type.")?;
530 if cfg!(debug_assertions) {
531 f.write_str("\n")?;
532 self.display_verbose_extras(f)?;
533 }
534 Ok(())
535 }
536 }
537
538 #[cfg(any(zerocopy_core_error_1_81_0, feature = "std", test))]
539 #[cfg_attr(doc_cfg, doc(cfg(all(rust = "1.81.0", feature = "std"))))]
540 impl<Src, Dst: ?Sized> Error for SizeError<Src, Dst>
541 where
542 Src: Deref,
543 Dst: KnownLayout,
544 {
545 }
546
547 impl<Src, Dst: ?Sized, A, V> From<SizeError<Src, Dst>> for ConvertError<A, SizeError<Src, Dst>, V> {
548 #[inline(always)]
549 fn from(err: SizeError<Src, Dst>) -> Self {
550 Self::Size(err)
551 }
552 }
553
554 /// The error emitted if the conversion source contains invalid data.
555 #[derive(PartialEq, Eq)]
556 pub struct ValidityError<Src, Dst: ?Sized + TryFromBytes> {
557 /// The source value involved in the conversion.
558 pub(crate) src: Src,
559 /// The inner destination type inolved in the conversion.
560 dst: SendSyncPhantomData<Dst>,
561 }
562
563 impl<Src, Dst: ?Sized + TryFromBytes> ValidityError<Src, Dst> {
564 pub(crate) fn new(src: Src) -> Self {
565 Self { src, dst: SendSyncPhantomData::default() }
566 }
567
568 /// Produces the source underlying the failed conversion.
569 #[inline]
570 pub fn into_src(self) -> Src {
571 self.src
572 }
573
574 /// Maps the source value associated with the conversion error.
575 ///
576 /// This can help mitigate [issues with `Send`, `Sync` and `'static`
577 /// bounds][self#send-sync-and-static].
578 ///
579 /// # Examples
580 ///
581 /// ```
582 /// use zerocopy::*;
583 ///
584 /// let source: u8 = 42;
585 ///
586 /// // Try to transmute the `source` to a `bool`. This will fail.
587 /// let maybe_bool: Result<bool, ValidityError<u8, bool>> = try_transmute!(source);
588 ///
589 /// // Drop the error's source.
590 /// let maybe_bool: Result<bool, ValidityError<(), bool>> = maybe_bool.map_err(|err| {
591 /// err.map_src(drop)
592 /// });
593 /// ```
594 #[inline]
595 pub fn map_src<NewSrc>(self, f: impl FnOnce(Src) -> NewSrc) -> ValidityError<NewSrc, Dst> {
596 ValidityError { src: f(self.src), dst: SendSyncPhantomData::default() }
597 }
598
599 /// Converts the error into a general [`ConvertError`].
600 pub(crate) fn into<A, S>(self) -> ConvertError<A, S, Self> {
601 ConvertError::Validity(self)
602 }
603
604 /// Format extra details for a verbose, human-readable error message.
605 ///
606 /// This formatting may include potentially sensitive information.
607 fn display_verbose_extras(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result
608 where
609 Dst: KnownLayout,
610 {
611 f.write_str("Destination type: ")?;
612 f.write_str(core::any::type_name::<Dst>())?;
613 Ok(())
614 }
615 }
616
617 impl<Src, Dst: ?Sized + TryFromBytes> fmt::Debug for ValidityError<Src, Dst> {
618 #[inline]
619 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
620 f.debug_struct("ValidityError").finish()
621 }
622 }
623
624 /// Produces a human-readable error message.
625 ///
626 /// The message differs between debug and release builds. When
627 /// `debug_assertions` are enabled, this message is verbose and includes
628 /// potentially sensitive information.
629 impl<Src, Dst: ?Sized> fmt::Display for ValidityError<Src, Dst>
630 where
631 Dst: KnownLayout + TryFromBytes,
632 {
633 #[inline]
634 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
635 f.write_str("The conversion failed because the source bytes are not a valid value of the destination type.")?;
636 if cfg!(debug_assertions) {
637 f.write_str("\n\n")?;
638 self.display_verbose_extras(f)?;
639 }
640 Ok(())
641 }
642 }
643
644 #[cfg(any(zerocopy_core_error_1_81_0, feature = "std", test))]
645 #[cfg_attr(doc_cfg, doc(cfg(all(rust = "1.81.0", feature = "std"))))]
646 impl<Src, Dst: ?Sized> Error for ValidityError<Src, Dst> where Dst: KnownLayout + TryFromBytes {}
647
648 impl<Src, Dst: ?Sized + TryFromBytes, A, S> From<ValidityError<Src, Dst>>
649 for ConvertError<A, S, ValidityError<Src, Dst>>
650 {
651 #[inline(always)]
652 fn from(err: ValidityError<Src, Dst>) -> Self {
653 Self::Validity(err)
654 }
655 }
656
657 /// The error type of reference conversions.
658 ///
659 /// Reference conversions, like [`FromBytes::ref_from_bytes`] may emit
660 /// [alignment](AlignmentError) and [size](SizeError) errors.
661 // Bounds on generic parameters are not enforced in type aliases, but they do
662 // appear in rustdoc.
663 #[allow(type_alias_bounds)]
664 pub type CastError<Src, Dst: ?Sized> =
665 ConvertError<AlignmentError<Src, Dst>, SizeError<Src, Dst>, Infallible>;
666
667 impl<Src, Dst: ?Sized> CastError<Src, Dst> {
668 /// Produces the source underlying the failed conversion.
669 #[inline]
670 pub fn into_src(self) -> Src {
671 match self {
672 Self::Alignment(e) => e.src,
673 Self::Size(e) => e.src,
674 Self::Validity(i) => match i {},
675 }
676 }
677
678 /// Sets the source value associated with the conversion error.
679 pub(crate) fn with_src<NewSrc>(self, new_src: NewSrc) -> CastError<NewSrc, Dst> {
680 match self {
681 Self::Alignment(e) => CastError::Alignment(e.with_src(new_src)),
682 Self::Size(e) => CastError::Size(e.with_src(new_src)),
683 Self::Validity(i) => match i {},
684 }
685 }
686
687 /// Maps the source value associated with the conversion error.
688 ///
689 /// This can help mitigate [issues with `Send`, `Sync` and `'static`
690 /// bounds][self#send-sync-and-static].
691 ///
692 /// # Examples
693 ///
694 /// ```
695 /// use zerocopy::*;
696 ///
697 /// let source: [u8; 3] = [0, 1, 2];
698 ///
699 /// // Try to read a `u32` from `source`. This will fail because there are insufficient
700 /// // bytes in `source`.
701 /// let maybe_u32: Result<&u32, CastError<&[u8], u32>> = u32::ref_from_bytes(&source[..]);
702 ///
703 /// // Map the error's source to its size and address.
704 /// let maybe_u32: Result<&u32, CastError<(usize, usize), u32>> = maybe_u32.map_err(|err| {
705 /// err.map_src(|src| (src.len(), src.as_ptr() as usize))
706 /// });
707 /// ```
708 #[inline]
709 pub fn map_src<NewSrc>(self, f: impl FnOnce(Src) -> NewSrc) -> CastError<NewSrc, Dst> {
710 match self {
711 Self::Alignment(e) => CastError::Alignment(e.map_src(f)),
712 Self::Size(e) => CastError::Size(e.map_src(f)),
713 Self::Validity(i) => match i {},
714 }
715 }
716
717 /// Converts the error into a general [`ConvertError`].
718 pub(crate) fn into(self) -> TryCastError<Src, Dst>
719 where
720 Dst: TryFromBytes,
721 {
722 match self {
723 Self::Alignment(e) => TryCastError::Alignment(e),
724 Self::Size(e) => TryCastError::Size(e),
725 Self::Validity(i) => match i {},
726 }
727 }
728 }
729
730 impl<Src, Dst: ?Sized + Unaligned> From<CastError<Src, Dst>> for SizeError<Src, Dst> {
731 /// Infallibly extracts the [`SizeError`] from this `CastError` since `Dst`
732 /// is unaligned.
733 ///
734 /// Since [`Dst: Unaligned`], it is impossible to encounter an alignment
735 /// error, and so the only error that can be encountered at runtime is a
736 /// [`SizeError`]. This method permits extracting that `SizeError`
737 /// infallibly.
738 ///
739 /// [`Dst: Unaligned`]: crate::Unaligned
740 ///
741 /// # Examples
742 ///
743 /// ```rust
744 /// use zerocopy::*;
745 /// # use zerocopy_derive::*;
746 ///
747 /// #[derive(FromBytes, IntoBytes, KnownLayout, Immutable, Unaligned)]
748 /// #[repr(C)]
749 /// struct UdpHeader {
750 /// src_port: [u8; 2],
751 /// dst_port: [u8; 2],
752 /// length: [u8; 2],
753 /// checksum: [u8; 2],
754 /// }
755 ///
756 /// #[derive(FromBytes, IntoBytes, KnownLayout, Immutable, Unaligned)]
757 /// #[repr(C, packed)]
758 /// struct UdpPacket {
759 /// header: UdpHeader,
760 /// body: [u8],
761 /// }
762 ///
763 /// impl UdpPacket {
764 /// pub fn parse(bytes: &[u8]) -> Result<&UdpPacket, SizeError<&[u8], UdpPacket>> {
765 /// // Since `UdpPacket: Unaligned`, we can map the `CastError` to a `SizeError`.
766 /// UdpPacket::ref_from_bytes(bytes).map_err(Into::into)
767 /// }
768 /// }
769 /// ```
770 #[inline(always)]
771 fn from(err: CastError<Src, Dst>) -> SizeError<Src, Dst> {
772 match err {
773 #[allow(unreachable_code)]
774 CastError::Alignment(e) => match Infallible::from(e) {},
775 CastError::Size(e) => e,
776 CastError::Validity(i) => match i {},
777 }
778 }
779 }
780
781 /// The error type of fallible reference conversions.
782 ///
783 /// Fallible reference conversions, like [`TryFromBytes::try_ref_from_bytes`]
784 /// may emit [alignment](AlignmentError), [size](SizeError), and
785 /// [validity](ValidityError) errors.
786 // Bounds on generic parameters are not enforced in type aliases, but they do
787 // appear in rustdoc.
788 #[allow(type_alias_bounds)]
789 pub type TryCastError<Src, Dst: ?Sized + TryFromBytes> =
790 ConvertError<AlignmentError<Src, Dst>, SizeError<Src, Dst>, ValidityError<Src, Dst>>;
791
792 // FIXME(#1139): Remove the `TryFromBytes` here and in other downstream
793 // locations (all the way to `ValidityError`) if we determine it's not necessary
794 // for rich validity errors.
795 impl<Src, Dst: ?Sized + TryFromBytes> TryCastError<Src, Dst> {
796 /// Produces the source underlying the failed conversion.
797 #[inline]
798 pub fn into_src(self) -> Src {
799 match self {
800 Self::Alignment(e) => e.src,
801 Self::Size(e) => e.src,
802 Self::Validity(e) => e.src,
803 }
804 }
805
806 /// Maps the source value associated with the conversion error.
807 ///
808 /// This can help mitigate [issues with `Send`, `Sync` and `'static`
809 /// bounds][self#send-sync-and-static].
810 ///
811 /// # Examples
812 ///
813 /// ```
814 /// use core::num::NonZeroU32;
815 /// use zerocopy::*;
816 ///
817 /// let source: [u8; 3] = [0, 0, 0];
818 ///
819 /// // Try to read a `NonZeroU32` from `source`.
820 /// let maybe_u32: Result<&NonZeroU32, TryCastError<&[u8], NonZeroU32>>
821 /// = NonZeroU32::try_ref_from_bytes(&source[..]);
822 ///
823 /// // Map the error's source to its size and address.
824 /// let maybe_u32: Result<&NonZeroU32, TryCastError<(usize, usize), NonZeroU32>> =
825 /// maybe_u32.map_err(|err| {
826 /// err.map_src(|src| (src.len(), src.as_ptr() as usize))
827 /// });
828 /// ```
829 #[inline]
830 pub fn map_src<NewSrc>(self, f: impl FnOnce(Src) -> NewSrc) -> TryCastError<NewSrc, Dst> {
831 match self {
832 Self::Alignment(e) => TryCastError::Alignment(e.map_src(f)),
833 Self::Size(e) => TryCastError::Size(e.map_src(f)),
834 Self::Validity(e) => TryCastError::Validity(e.map_src(f)),
835 }
836 }
837 }
838
839 impl<Src, Dst: ?Sized + TryFromBytes> From<CastError<Src, Dst>> for TryCastError<Src, Dst> {
840 #[inline]
841 fn from(value: CastError<Src, Dst>) -> Self {
842 match value {
843 CastError::Alignment(e) => Self::Alignment(e),
844 CastError::Size(e) => Self::Size(e),
845 CastError::Validity(i) => match i {},
846 }
847 }
848 }
849
850 /// The error type of fallible read-conversions.
851 ///
852 /// Fallible read-conversions, like [`TryFromBytes::try_read_from_bytes`] may emit
853 /// [size](SizeError) and [validity](ValidityError) errors, but not alignment errors.
854 // Bounds on generic parameters are not enforced in type aliases, but they do
855 // appear in rustdoc.
856 #[allow(type_alias_bounds)]
857 pub type TryReadError<Src, Dst: ?Sized + TryFromBytes> =
858 ConvertError<Infallible, SizeError<Src, Dst>, ValidityError<Src, Dst>>;
859
860 impl<Src, Dst: ?Sized + TryFromBytes> TryReadError<Src, Dst> {
861 /// Produces the source underlying the failed conversion.
862 #[inline]
863 pub fn into_src(self) -> Src {
864 match self {
865 Self::Alignment(i) => match i {},
866 Self::Size(e) => e.src,
867 Self::Validity(e) => e.src,
868 }
869 }
870
871 /// Maps the source value associated with the conversion error.
872 ///
873 /// This can help mitigate [issues with `Send`, `Sync` and `'static`
874 /// bounds][self#send-sync-and-static].
875 ///
876 /// # Examples
877 ///
878 /// ```
879 /// use core::num::NonZeroU32;
880 /// use zerocopy::*;
881 ///
882 /// let source: [u8; 3] = [0, 0, 0];
883 ///
884 /// // Try to read a `NonZeroU32` from `source`.
885 /// let maybe_u32: Result<NonZeroU32, TryReadError<&[u8], NonZeroU32>>
886 /// = NonZeroU32::try_read_from_bytes(&source[..]);
887 ///
888 /// // Map the error's source to its size.
889 /// let maybe_u32: Result<NonZeroU32, TryReadError<usize, NonZeroU32>> =
890 /// maybe_u32.map_err(|err| {
891 /// err.map_src(|src| src.len())
892 /// });
893 /// ```
894 #[inline]
895 pub fn map_src<NewSrc>(self, f: impl FnOnce(Src) -> NewSrc) -> TryReadError<NewSrc, Dst> {
896 match self {
897 Self::Alignment(i) => match i {},
898 Self::Size(e) => TryReadError::Size(e.map_src(f)),
899 Self::Validity(e) => TryReadError::Validity(e.map_src(f)),
900 }
901 }
902 }
903
904 /// The error type of well-aligned, fallible casts.
905 ///
906 /// This is like [`TryCastError`], but for casts that are always well-aligned.
907 /// It is identical to `TryCastError`, except that its alignment error is
908 /// [`Infallible`].
909 ///
910 /// As of this writing, none of zerocopy's API produces this error directly.
911 /// However, it is useful since it permits users to infallibly discard alignment
912 /// errors when they can prove statically that alignment errors are impossible.
913 ///
914 /// # Examples
915 ///
916 /// ```
917 /// use core::convert::Infallible;
918 /// use zerocopy::*;
919 /// # use zerocopy_derive::*;
920 ///
921 /// #[derive(TryFromBytes, KnownLayout, Unaligned, Immutable)]
922 /// #[repr(C, packed)]
923 /// struct Bools {
924 /// one: bool,
925 /// two: bool,
926 /// many: [bool],
927 /// }
928 ///
929 /// impl Bools {
930 /// fn parse(bytes: &[u8]) -> Result<&Bools, AlignedTryCastError<&[u8], Bools>> {
931 /// // Since `Bools: Unaligned`, we can infallibly discard
932 /// // the alignment error.
933 /// Bools::try_ref_from_bytes(bytes).map_err(Into::into)
934 /// }
935 /// }
936 /// ```
937 #[allow(type_alias_bounds)]
938 pub type AlignedTryCastError<Src, Dst: ?Sized + TryFromBytes> =
939 ConvertError<Infallible, SizeError<Src, Dst>, ValidityError<Src, Dst>>;
940
941 /// The error type of a failed allocation.
942 ///
943 /// This type is intended to be deprecated in favor of the standard library's
944 /// [`AllocError`] type once it is stabilized. When that happens, this type will
945 /// be replaced by a type alias to the standard library type. We do not intend
946 /// to treat this as a breaking change; users who wish to avoid breakage should
947 /// avoid writing code which assumes that this is *not* such an alias. For
948 /// example, implementing the same trait for both types will result in an impl
949 /// conflict once this type is an alias.
950 ///
951 /// [`AllocError`]: https://doc.rust-lang.org/alloc/alloc/struct.AllocError.html
952 #[derive(Copy, Clone, PartialEq, Eq, Debug)]
953 pub struct AllocError;
954
955 #[cfg(test)]
956 mod tests {
957 use super::*;
958
959 #[test]
960 fn test_send_sync() {
961 // Test that all error types are `Send + Sync` even if `Dst: !Send +
962 // !Sync`.
963
964 #[allow(dead_code)]
965 fn is_send_sync<T: Send + Sync>(_t: T) {}
966
967 #[allow(dead_code)]
968 fn alignment_err_is_send_sync<Src: Send + Sync, Dst>(err: AlignmentError<Src, Dst>) {
969 is_send_sync(err)
970 }
971
972 #[allow(dead_code)]
973 fn size_err_is_send_sync<Src: Send + Sync, Dst>(err: SizeError<Src, Dst>) {
974 is_send_sync(err)
975 }
976
977 #[allow(dead_code)]
978 fn validity_err_is_send_sync<Src: Send + Sync, Dst: TryFromBytes>(
979 err: ValidityError<Src, Dst>,
980 ) {
981 is_send_sync(err)
982 }
983
984 #[allow(dead_code)]
985 fn convert_error_is_send_sync<Src: Send + Sync, Dst: TryFromBytes>(
986 err: ConvertError<
987 AlignmentError<Src, Dst>,
988 SizeError<Src, Dst>,
989 ValidityError<Src, Dst>,
990 >,
991 ) {
992 is_send_sync(err)
993 }
994 }
995
996 #[test]
997 fn alignment_display() {
998 #[repr(C, align(128))]
999 struct Aligned {
1000 bytes: [u8; 128],
1001 }
1002
1003 impl_known_layout!(elain::Align::<8>);
1004
1005 let aligned = Aligned { bytes: [0; 128] };
1006
1007 let bytes = &aligned.bytes[1..];
1008 let addr = crate::util::AsAddress::addr(bytes);
1009 assert_eq!(
1010 AlignmentError::<_, elain::Align::<8>>::new_checked(bytes).to_string(),
1011 format!("The conversion failed because the address of the source is not a multiple of the alignment of the destination type.\n\
1012 \nSource type: &[u8]\
1013 \nSource address: 0x{:x} (a multiple of 1)\
1014 \nDestination type: elain::Align<8>\
1015 \nDestination alignment: 8", addr)
1016 );
1017
1018 let bytes = &aligned.bytes[2..];
1019 let addr = crate::util::AsAddress::addr(bytes);
1020 assert_eq!(
1021 AlignmentError::<_, elain::Align::<8>>::new_checked(bytes).to_string(),
1022 format!("The conversion failed because the address of the source is not a multiple of the alignment of the destination type.\n\
1023 \nSource type: &[u8]\
1024 \nSource address: 0x{:x} (a multiple of 2)\
1025 \nDestination type: elain::Align<8>\
1026 \nDestination alignment: 8", addr)
1027 );
1028
1029 let bytes = &aligned.bytes[3..];
1030 let addr = crate::util::AsAddress::addr(bytes);
1031 assert_eq!(
1032 AlignmentError::<_, elain::Align::<8>>::new_checked(bytes).to_string(),
1033 format!("The conversion failed because the address of the source is not a multiple of the alignment of the destination type.\n\
1034 \nSource type: &[u8]\
1035 \nSource address: 0x{:x} (a multiple of 1)\
1036 \nDestination type: elain::Align<8>\
1037 \nDestination alignment: 8", addr)
1038 );
1039
1040 let bytes = &aligned.bytes[4..];
1041 let addr = crate::util::AsAddress::addr(bytes);
1042 assert_eq!(
1043 AlignmentError::<_, elain::Align::<8>>::new_checked(bytes).to_string(),
1044 format!("The conversion failed because the address of the source is not a multiple of the alignment of the destination type.\n\
1045 \nSource type: &[u8]\
1046 \nSource address: 0x{:x} (a multiple of 4)\
1047 \nDestination type: elain::Align<8>\
1048 \nDestination alignment: 8", addr)
1049 );
1050 }
1051
1052 #[test]
1053 fn size_display() {
1054 assert_eq!(
1055 SizeError::<_, [u8]>::new(&[0u8; 2][..]).to_string(),
1056 "The conversion failed because the source was incorrectly sized to complete the conversion into the destination type.\n\
1057 \nSource type: &[u8]\
1058 \nSource size: 2 bytes\
1059 \nDestination type: [u8]"
1060 );
1061
1062 assert_eq!(
1063 SizeError::<_, [u8; 2]>::new(&[0u8; 1][..]).to_string(),
1064 "The conversion failed because the source was incorrectly sized to complete the conversion into the destination type.\n\
1065 \nSource type: &[u8]\
1066 \nSource size: 1 byte\
1067 \nDestination size: 2 bytes\
1068 \nDestination type: [u8; 2]"
1069 );
1070 }
1071
1072 #[test]
1073 fn validity_display() {
1074 assert_eq!(
1075 ValidityError::<_, bool>::new(&[2u8; 1][..]).to_string(),
1076 "The conversion failed because the source bytes are not a valid value of the destination type.\n\
1077 \n\
1078 Destination type: bool"
1079 );
1080 }
1081 }