//! Errors returned by functions in this crate. #[cfg(feature = "alloc")] #[allow(unused_imports)] use alloc::vec::Vec; /// An error returned to indicate a problem with nul values occurred. /// /// The error will either being a [`MissingNulTerminator`] or [`ContainsNul`]. /// The error optionally returns the ownership of the invalid vector whenever a vector was owned. #[derive(Debug, Clone)] pub enum NulError { /// A terminating nul value was missing. MissingNulTerminator(MissingNulTerminator), /// An interior nul value was found. ContainsNul(ContainsNul), } impl NulError { /// Consumes this error, returning the underlying vector of values which generated the error in /// the first place. #[inline] #[cfg(feature = "alloc")] #[cfg_attr(docsrs, doc(cfg(feature = "alloc")))] #[must_use] pub fn into_vec(self) -> Option> { match self { Self::MissingNulTerminator(_) => None, Self::ContainsNul(e) => e.into_vec(), } } } impl core::fmt::Display for NulError { #[inline] fn fmt(&self, f: &mut core::fmt::Formatter) -> core::fmt::Result { match self { Self::MissingNulTerminator(e) => e.fmt(f), Self::ContainsNul(e) => e.fmt(f), } } } #[cfg(feature = "std")] impl std::error::Error for NulError where C: core::fmt::Debug + 'static, { #[inline] fn source(&self) -> Option<&(dyn std::error::Error + 'static)> { match self { Self::MissingNulTerminator(e) => Some(e), Self::ContainsNul(e) => Some(e), } } } impl From for NulError { #[inline] fn from(value: MissingNulTerminator) -> Self { Self::MissingNulTerminator(value) } } impl From> for NulError { #[inline] fn from(value: ContainsNul) -> Self { Self::ContainsNul(value) } } /// An error returned from to indicate that a terminating nul value was missing. #[derive(Debug, Clone)] pub struct MissingNulTerminator { _unused: (), } impl MissingNulTerminator { pub(crate) fn new() -> Self { Self { _unused: () } } } impl core::fmt::Display for MissingNulTerminator { fn fmt(&self, f: &mut core::fmt::Formatter) -> core::fmt::Result { write!(f, "missing terminating nul value") } } #[cfg(feature = "std")] impl std::error::Error for MissingNulTerminator {} /// An error returned to indicate that an invalid nul value was found in a string. /// /// The error indicates the position in the vector where the nul value was found, as well as /// returning the ownership of the invalid vector. #[cfg_attr(docsrs, doc(cfg(feature = "alloc")))] #[derive(Debug, Clone)] pub struct ContainsNul { index: usize, #[cfg(feature = "alloc")] pub(crate) inner: Option>, #[cfg(not(feature = "alloc"))] _p: core::marker::PhantomData, } impl ContainsNul { #[cfg(feature = "alloc")] pub(crate) fn new(index: usize, v: Vec) -> Self { Self { index, inner: Some(v), } } #[cfg(feature = "alloc")] pub(crate) fn empty(index: usize) -> Self { Self { index, inner: None } } #[cfg(not(feature = "alloc"))] pub(crate) fn empty(index: usize) -> Self { Self { index, _p: core::marker::PhantomData, } } /// Returns the index of the invalid nul value in the slice. #[inline] #[must_use] pub fn nul_position(&self) -> usize { self.index } /// Consumes this error, returning the underlying vector of values which generated the error in /// the first place. /// /// If the sequence that generated the error was a reference to a slice instead of a [`Vec`], /// this will return [`None`]. #[inline] #[cfg(feature = "alloc")] #[cfg_attr(docsrs, doc(cfg(feature = "alloc")))] #[must_use] pub fn into_vec(self) -> Option> { self.inner } } impl core::fmt::Display for ContainsNul { fn fmt(&self, f: &mut core::fmt::Formatter) -> core::fmt::Result { write!(f, "invalid nul value found at position {}", self.index) } } #[cfg(feature = "std")] impl std::error::Error for ContainsNul where C: core::fmt::Debug {} /// An error that can be returned when decoding UTF-16 code points. /// /// This struct is created when using the [`DecodeUtf16`][crate::iter::DecodeUtf16] iterator. #[derive(Debug, Clone, PartialEq, Eq)] pub struct DecodeUtf16Error { unpaired_surrogate: u16, } impl DecodeUtf16Error { pub(crate) fn new(unpaired_surrogate: u16) -> Self { Self { unpaired_surrogate } } /// Returns the unpaired surrogate which caused this error. #[must_use] pub fn unpaired_surrogate(&self) -> u16 { self.unpaired_surrogate } } impl core::fmt::Display for DecodeUtf16Error { fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result { write!(f, "unpaired surrogate found: {:x}", self.unpaired_surrogate) } } #[cfg(feature = "std")] impl std::error::Error for DecodeUtf16Error {} /// An error that can be returned when decoding UTF-32 code points. /// /// This error occurs when a [`u32`] value is outside the 21-bit Unicode code point range /// (>`U+10FFFF`) or is a UTF-16 surrogate value. #[derive(Debug, Clone)] pub struct DecodeUtf32Error { code: u32, } impl DecodeUtf32Error { pub(crate) fn new(code: u32) -> Self { Self { code } } /// Returns the invalid code point value which caused the error. #[must_use] pub fn invalid_code_point(&self) -> u32 { self.code } } impl core::fmt::Display for DecodeUtf32Error { fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result { write!(f, "invalid UTF-32 code point: {:x}", self.code) } } #[cfg(feature = "std")] impl std::error::Error for DecodeUtf32Error {} /// Errors which can occur when attempting to interpret a sequence of `u16` as UTF-16. #[derive(Debug, Clone)] pub struct Utf16Error { index: usize, source: DecodeUtf16Error, #[cfg(feature = "alloc")] inner: Option>, } impl Utf16Error { #[cfg(feature = "alloc")] pub(crate) fn new(inner: Vec, index: usize, source: DecodeUtf16Error) -> Self { Self { inner: Some(inner), index, source, } } #[cfg(feature = "alloc")] pub(crate) fn empty(index: usize, source: DecodeUtf16Error) -> Self { Self { index, source, inner: None, } } #[cfg(not(feature = "alloc"))] pub(crate) fn empty(index: usize, source: DecodeUtf16Error) -> Self { Self { index, source } } /// Returns the index in the given string at which the invalid UTF-16 value occurred. #[must_use] pub fn index(&self) -> usize { self.index } /// Consumes this error, returning the underlying vector of values which generated the error in /// the first place. /// /// If the sequence that generated the error was a reference to a slice instead of a [`Vec`], /// this will return [`None`]. #[inline] #[cfg(feature = "alloc")] #[cfg_attr(docsrs, doc(cfg(feature = "alloc")))] #[must_use] pub fn into_vec(self) -> Option> { self.inner } } impl core::fmt::Display for Utf16Error { fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result { write!( f, "unpaired UTF-16 surrogate {:x} at index {}", self.source.unpaired_surrogate(), self.index ) } } #[cfg(feature = "std")] impl std::error::Error for Utf16Error { fn source(&self) -> Option<&(dyn std::error::Error + 'static)> { Some(&self.source) } } /// Errors which can occur when attempting to interpret a sequence of `u32` as UTF-32. #[derive(Debug, Clone)] pub struct Utf32Error { index: usize, source: DecodeUtf32Error, #[cfg(feature = "alloc")] inner: Option>, } impl Utf32Error { #[cfg(feature = "alloc")] pub(crate) fn new(inner: Vec, index: usize, source: DecodeUtf32Error) -> Self { Self { inner: Some(inner), index, source, } } #[cfg(feature = "alloc")] pub(crate) fn empty(index: usize, source: DecodeUtf32Error) -> Self { Self { index, source, inner: None, } } #[cfg(not(feature = "alloc"))] pub(crate) fn empty(index: usize, source: DecodeUtf32Error) -> Self { Self { index, source } } /// Returns the index in the given string at which the invalid UTF-32 value occurred. #[must_use] pub fn index(&self) -> usize { self.index } /// Consumes this error, returning the underlying vector of values which generated the error in /// the first place. /// /// If the sequence that generated the error was a reference to a slice instead of a [`Vec`], /// this will return [`None`]. #[inline] #[cfg(feature = "alloc")] #[cfg_attr(docsrs, doc(cfg(feature = "alloc")))] #[must_use] pub fn into_vec(self) -> Option> { self.inner } } impl core::fmt::Display for Utf32Error { fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result { write!( f, "invalid UTF-32 value {:x} at index {}", self.source.invalid_code_point(), self.index ) } } #[cfg(feature = "std")] impl std::error::Error for Utf32Error { fn source(&self) -> Option<&(dyn std::error::Error + 'static)> { Some(&self.source) } }