simdutf8/compat.rs
1//! The `compat` API flavor provides full compatibility with [`std::str::from_utf8()`] and detailed validation errors.
2//!
3//! In particular, [`from_utf8()`]
4//! returns an [`Utf8Error`], which has the [`valid_up_to()`](Utf8Error#method.valid_up_to) and
5//! [`error_len()`](Utf8Error#method.error_len) methods. The first is useful for verification of streamed data. The
6//! second is useful e.g. for replacing invalid byte sequences with a replacement character.
7//!
8//! The functions in this module also fail early: errors are checked on-the-fly as the string is processed and once
9//! an invalid UTF-8 sequence is encountered, it returns without processing the rest of the data.
10//! This comes at a slight performance penalty compared to the [`crate::basic`] module if the input is valid UTF-8.
11
12use core::fmt::Display;
13use core::fmt::Formatter;
14
15use core::str::{from_utf8_unchecked, from_utf8_unchecked_mut};
16
17use crate::implementation::validate_utf8_compat;
18
19/// UTF-8 error information compatible with [`std::str::Utf8Error`].
20///
21/// Contains information on the location of the encountered validation error and the length of the
22/// invalid UTF-8 sequence.
23#[derive(Copy, Eq, PartialEq, Clone, Debug)]
24pub struct Utf8Error {
25 pub(crate) valid_up_to: usize,
26 pub(crate) error_len: Option<u8>,
27}
28
29impl Utf8Error {
30 /// Analogue to [`std::str::Utf8Error::valid_up_to()`](std::str::Utf8Error#method.valid_up_to).
31 ///
32 /// ...
33 #[inline]
34 #[must_use]
35 pub fn valid_up_to(&self) -> usize {
36 self.valid_up_to
37 }
38
39 /// Analogue to [`std::str::Utf8Error::error_len()`](std::str::Utf8Error#method.error_len).
40 ///
41 /// ...
42 #[inline]
43 #[must_use]
44 pub fn error_len(&self) -> Option<usize> {
45 self.error_len.map(|len| len as usize)
46 }
47}
48
49impl Display for Utf8Error {
50 fn fmt(&self, f: &mut Formatter<'_>) -> core::fmt::Result {
51 if let Some(error_len) = self.error_len {
52 write!(
53 f,
54 "invalid utf-8 sequence of {} bytes from index {}",
55 error_len, self.valid_up_to
56 )
57 } else {
58 write!(
59 f,
60 "incomplete utf-8 byte sequence from index {}",
61 self.valid_up_to
62 )
63 }
64 }
65}
66
67#[cfg(feature = "std")]
68impl std::error::Error for Utf8Error {}
69
70/// Analogue to [`std::str::from_utf8()`].
71///
72/// Checks if the passed byte sequence is valid UTF-8 and returns an
73/// [`std::str`] reference to the passed byte slice wrapped in `Ok()` if it is.
74///
75/// # Errors
76/// Will return Err([`Utf8Error`]) on if the input contains invalid UTF-8 with
77/// detailed error information.
78#[inline]
79pub fn from_utf8(input: &[u8]) -> Result<&str, Utf8Error> {
80 unsafe {
81 validate_utf8_compat(input)?;
82 Ok(from_utf8_unchecked(input))
83 }
84}
85
86/// Analogue to [`std::str::from_utf8_mut()`].
87///
88/// Checks if the passed mutable byte sequence is valid UTF-8 and returns a mutable
89/// [`std::str`] reference to the passed byte slice wrapped in `Ok()` if it is.
90///
91/// # Errors
92/// Will return Err([`Utf8Error`]) on if the input contains invalid UTF-8 with
93/// detailed error information.
94#[inline]
95pub fn from_utf8_mut(input: &mut [u8]) -> Result<&mut str, Utf8Error> {
96 unsafe {
97 validate_utf8_compat(input)?;
98 Ok(from_utf8_unchecked_mut(input))
99 }
100}
101
102/// Allows direct access to the platform-specific unsafe validation implementations.
103#[cfg(feature = "public_imp")]
104pub mod imp {
105 /// Includes the x86/x86-64 SIMD implementations.
106 #[cfg(any(target_arch = "x86", target_arch = "x86_64"))]
107 pub mod x86 {
108 /// Includes the validation implementation for AVX 512-compatible CPUs.
109 #[cfg(avx512_stable)]
110 pub mod avx512 {
111 pub use crate::implementation::x86::avx512::validate_utf8_compat as validate_utf8;
112 }
113 /// Includes the validation implementation for AVX 2-compatible CPUs.
114 pub mod avx2 {
115 pub use crate::implementation::x86::avx2::validate_utf8_compat as validate_utf8;
116 }
117 /// Includes the validation implementation for SSE 4.2-compatible CPUs.
118 pub mod sse42 {
119 pub use crate::implementation::x86::sse42::validate_utf8_compat as validate_utf8;
120 }
121 }
122
123 /// Includes the aarch64 SIMD implementations.
124 #[cfg(all(target_arch = "aarch64", target_feature = "neon"))]
125 pub mod aarch64 {
126 /// Includes the validation implementation for Neon SIMD.
127 pub mod neon {
128 pub use crate::implementation::aarch64::neon::validate_utf8_compat as validate_utf8;
129 }
130 }
131
132 /// Includes the armv7 NEON SIMD implementations.
133 #[cfg(all(
134 target_arch = "arm",
135 target_feature = "v7",
136 target_endian = "little",
137 feature = "armv7_neon",
138 ))]
139 pub mod armv7 {
140 /// Includes the Neon-based validation implementation for armv7 neon-compatible CPUs.
141 ///
142 /// Using the provided functionality on CPUs which do not support neon is undefined
143 /// behavior and will very likely cause a crash.
144 pub mod neon {
145 pub use crate::implementation::armv7::neon::validate_utf8_compat as validate_utf8;
146 }
147 }
148
149 /// Includes the wasm32 SIMD implementations.
150 #[cfg(all(target_arch = "wasm32", target_feature = "simd128"))]
151 pub mod wasm32 {
152 /// Includes the validation implementation for WASM simd128.
153 pub mod simd128 {
154 pub use crate::implementation::wasm32::simd128::validate_utf8_compat as validate_utf8;
155 }
156 }
157
158 /// Includes the portable SIMD implementations.
159 #[cfg(feature = "portable_public_imp")]
160 pub mod portable {
161 /// Includes the validation implementation for 128-bit portable SIMD.
162 pub mod simd128 {
163 pub use crate::implementation::portable::simd128::validate_utf8_compat as validate_utf8;
164 }
165
166 /// Includes the validation implementation for 256-bit portable SIMD.
167 pub mod simd256 {
168 pub use crate::implementation::portable::simd256::validate_utf8_compat as validate_utf8;
169 }
170 }
171}