core/slice/ascii.rs
1//! Operations on ASCII `[u8]`.
2
3/// Ferrocene addition: Hidden module to test crate-internal functionality
4#[doc(hidden)]
5#[unstable(feature = "ferrocene_test", issue = "none")]
6pub(crate) mod ferrocene_test;
7
8use core::ascii::EscapeDefault;
9
10use crate::fmt::{self, Write};
11#[cfg(not(all(target_arch = "loongarch64", target_feature = "lsx")))]
12use crate::intrinsics::const_eval_select;
13use crate::{ascii, iter, ops};
14#[unstable(feature = "u8_split_ascii_whitespace", issue = "147878")]
15use crate::{
16 iter::{Filter, FusedIterator},
17 slice::Split,
18 str::{BytesIsNotEmpty, IsAsciiWhitespace},
19};
20
21impl [u8] {
22 /// Checks if all bytes in this slice are within the ASCII range.
23 ///
24 /// An empty slice returns `true`.
25 #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")]
26 #[rustc_const_stable(feature = "const_slice_is_ascii", since = "1.74.0")]
27 #[must_use]
28 #[inline]
29 #[ferrocene::prevalidated]
30 pub const fn is_ascii(&self) -> bool {
31 is_ascii(self)
32 }
33
34 /// If this slice [`is_ascii`](Self::is_ascii), returns it as a slice of
35 /// [ASCII characters](`ascii::Char`), otherwise returns `None`.
36 #[unstable(feature = "ascii_char", issue = "110998")]
37 #[must_use]
38 #[inline]
39 pub const fn as_ascii(&self) -> Option<&[ascii::Char]> {
40 if self.is_ascii() {
41 // SAFETY: Just checked that it's ASCII
42 Some(unsafe { self.as_ascii_unchecked() })
43 } else {
44 None
45 }
46 }
47
48 /// Converts this slice of bytes into a slice of ASCII characters,
49 /// without checking whether they're valid.
50 ///
51 /// # Safety
52 ///
53 /// Every byte in the slice must be in `0..=127`, or else this is UB.
54 #[unstable(feature = "ascii_char", issue = "110998")]
55 #[must_use]
56 #[inline]
57 pub const unsafe fn as_ascii_unchecked(&self) -> &[ascii::Char] {
58 let byte_ptr: *const [u8] = self;
59 let ascii_ptr = byte_ptr as *const [ascii::Char];
60 // SAFETY: The caller promised all the bytes are ASCII
61 unsafe { &*ascii_ptr }
62 }
63
64 /// Checks that two slices are an ASCII case-insensitive match.
65 ///
66 /// Same as `to_ascii_lowercase(a) == to_ascii_lowercase(b)`,
67 /// but without allocating and copying temporaries.
68 #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")]
69 #[rustc_const_stable(feature = "const_eq_ignore_ascii_case", since = "1.89.0")]
70 #[must_use]
71 #[inline]
72 #[ferrocene::prevalidated]
73 pub const fn eq_ignore_ascii_case(&self, other: &[u8]) -> bool {
74 if self.len() != other.len() {
75 return false;
76 }
77
78 #[cfg(any(
79 all(target_arch = "x86_64", target_feature = "sse2"),
80 all(target_arch = "aarch64", target_feature = "neon")
81 ))]
82 {
83 const CHUNK_SIZE: usize = 16;
84 // The following function has two invariants:
85 // 1. The slice lengths must be equal, which we checked above.
86 // 2. The slice lengths must greater than or equal to N, which this
87 // if-statement is checking.
88 if self.len() >= CHUNK_SIZE {
89 return self.eq_ignore_ascii_case_chunks::<CHUNK_SIZE>(other);
90 }
91 }
92
93 self.eq_ignore_ascii_case_simple(other)
94 }
95
96 /// ASCII case-insensitive equality check without chunk-at-a-time
97 /// optimization.
98 #[inline]
99 #[ferrocene::prevalidated]
100 const fn eq_ignore_ascii_case_simple(&self, other: &[u8]) -> bool {
101 // FIXME(const-hack): This implementation can be reverted when
102 // `core::iter::zip` is allowed in const. The original implementation:
103 // self.len() == other.len() && iter::zip(self, other).all(|(a, b)| a.eq_ignore_ascii_case(b))
104 let mut a = self;
105 let mut b = other;
106
107 while let ([first_a, rest_a @ ..], [first_b, rest_b @ ..]) = (a, b) {
108 if first_a.eq_ignore_ascii_case(first_b) {
109 a = rest_a;
110 b = rest_b;
111 } else {
112 return false;
113 }
114 }
115
116 true
117 }
118
119 /// Optimized version of `eq_ignore_ascii_case` to process chunks at a time.
120 ///
121 /// Platforms that have SIMD instructions may benefit from this
122 /// implementation over `eq_ignore_ascii_case_simple`.
123 ///
124 /// # Invariants
125 ///
126 /// The caller must guarantee that the slices are equal in length, and the
127 /// slice lengths are greater than or equal to `N` bytes.
128 #[cfg(any(
129 all(target_arch = "x86_64", target_feature = "sse2"),
130 all(target_arch = "aarch64", target_feature = "neon")
131 ))]
132 #[ferrocene::prevalidated]
133 #[inline]
134 const fn eq_ignore_ascii_case_chunks<const N: usize>(&self, other: &[u8]) -> bool {
135 // FIXME(const-hack): The while-loops that follow should be replaced by
136 // for-loops when available in const.
137
138 let (self_chunks, self_rem) = self.as_chunks::<N>();
139 let (other_chunks, _) = other.as_chunks::<N>();
140
141 // Branchless check to encourage auto-vectorization
142 #[ferrocene::prevalidated]
143 #[inline(always)]
144 const fn eq_ignore_ascii_inner<const L: usize>(lhs: &[u8; L], rhs: &[u8; L]) -> bool {
145 let mut equal_ascii = true;
146 let mut j = 0;
147 while j < L {
148 equal_ascii &= lhs[j].eq_ignore_ascii_case(&rhs[j]);
149 j += 1;
150 }
151
152 equal_ascii
153 }
154
155 // Process the chunks, returning early if an inequality is found
156 let mut i = 0;
157 while i < self_chunks.len() && i < other_chunks.len() {
158 if !eq_ignore_ascii_inner(&self_chunks[i], &other_chunks[i]) {
159 return false;
160 }
161 i += 1;
162 }
163
164 // Check the length invariant which is necessary for the tail-handling
165 // logic to be correct. This should have been upheld by the caller,
166 // otherwise lengths less than N will compare as true without any
167 // checking.
168 debug_assert!(self.len() >= N);
169
170 // If there are remaining tails, load the last N bytes in the slices to
171 // avoid falling back to per-byte checking.
172 if !self_rem.is_empty() {
173 if let (Some(a_rem), Some(b_rem)) = (self.last_chunk::<N>(), other.last_chunk::<N>()) {
174 if !eq_ignore_ascii_inner(a_rem, b_rem) {
175 return false;
176 }
177 } else {
178 #[ferrocene::annotation("
179 This branch is not coverable from public API. \
180 The only caller (`eq_ignore_ascii_case`) only calls this function if both values \
181 are the same length, and that shared length is greater than the `N` chunk size.
182 The `if` statement above is currently acting to destructure the returned values.
183 ")]
184 {}
185 }
186 }
187
188 true
189 }
190
191 /// Converts this slice to its ASCII upper case equivalent in-place.
192 ///
193 /// ASCII letters 'a' to 'z' are mapped to 'A' to 'Z',
194 /// but non-ASCII letters are unchanged.
195 ///
196 /// To return a new uppercased value without modifying the existing one, use
197 /// [`to_ascii_uppercase`].
198 ///
199 /// [`to_ascii_uppercase`]: #method.to_ascii_uppercase
200 #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")]
201 #[rustc_const_stable(feature = "const_make_ascii", since = "1.84.0")]
202 #[inline]
203 pub const fn make_ascii_uppercase(&mut self) {
204 // FIXME(const-hack): We would like to simply iterate using `for` loops but this isn't currently allowed in constant expressions.
205 let mut i = 0;
206 while i < self.len() {
207 let byte = &mut self[i];
208 byte.make_ascii_uppercase();
209 i += 1;
210 }
211 }
212
213 /// Converts this slice to its ASCII lower case equivalent in-place.
214 ///
215 /// ASCII letters 'A' to 'Z' are mapped to 'a' to 'z',
216 /// but non-ASCII letters are unchanged.
217 ///
218 /// To return a new lowercased value without modifying the existing one, use
219 /// [`to_ascii_lowercase`].
220 ///
221 /// [`to_ascii_lowercase`]: #method.to_ascii_lowercase
222 #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")]
223 #[rustc_const_stable(feature = "const_make_ascii", since = "1.84.0")]
224 #[inline]
225 pub const fn make_ascii_lowercase(&mut self) {
226 // FIXME(const-hack): We would like to simply iterate using `for` loops but this isn't currently allowed in constant expressions.
227 let mut i = 0;
228 while i < self.len() {
229 let byte = &mut self[i];
230 byte.make_ascii_lowercase();
231 i += 1;
232 }
233 }
234
235 /// Returns an iterator that produces an escaped version of this slice,
236 /// treating it as an ASCII string.
237 ///
238 /// # Examples
239 ///
240 /// ```
241 /// let s = b"0\t\r\n'\"\\\x9d";
242 /// let escaped = s.escape_ascii().to_string();
243 /// assert_eq!(escaped, "0\\t\\r\\n\\'\\\"\\\\\\x9d");
244 /// ```
245 #[must_use = "this returns the escaped bytes as an iterator, \
246 without modifying the original"]
247 #[stable(feature = "inherent_ascii_escape", since = "1.60.0")]
248 #[ferrocene::prevalidated]
249 pub fn escape_ascii(&self) -> EscapeAscii<'_> {
250 EscapeAscii { inner: self.iter().flat_map(EscapeByte) }
251 }
252
253 /// Returns a byte slice with leading ASCII whitespace bytes removed.
254 ///
255 /// 'Whitespace' refers to the definition used by
256 /// [`u8::is_ascii_whitespace`]. Importantly, this definition excludes
257 /// the `\0x0B` byte even though it has the Unicode [`White_Space`] property
258 /// and is removed by [`str::trim_start`].
259 ///
260 /// [`White_Space`]: https://www.unicode.org/reports/tr44/#White_Space
261 ///
262 /// # Examples
263 ///
264 /// ```
265 /// assert_eq!(b" \t hello world\n".trim_ascii_start(), b"hello world\n");
266 /// assert_eq!(b" ".trim_ascii_start(), b"");
267 /// assert_eq!(b"".trim_ascii_start(), b"");
268 /// ```
269 #[stable(feature = "byte_slice_trim_ascii", since = "1.80.0")]
270 #[rustc_const_stable(feature = "byte_slice_trim_ascii", since = "1.80.0")]
271 #[inline]
272 pub const fn trim_ascii_start(&self) -> &[u8] {
273 let mut bytes = self;
274 // Note: A pattern matching based approach (instead of indexing) allows
275 // making the function const.
276 while let [first, rest @ ..] = bytes {
277 if first.is_ascii_whitespace() {
278 bytes = rest;
279 } else {
280 break;
281 }
282 }
283 bytes
284 }
285
286 /// Returns a byte slice with trailing ASCII whitespace bytes removed.
287 ///
288 /// 'Whitespace' refers to the definition used by
289 /// [`u8::is_ascii_whitespace`]. Importantly, this definition excludes
290 /// the `\0x0B` byte even though it has the Unicode [`White_Space`] property
291 /// and is removed by [`str::trim_end`].
292 ///
293 /// [`White_Space`]: https://www.unicode.org/reports/tr44/#White_Space
294 ///
295 /// # Examples
296 ///
297 /// ```
298 /// assert_eq!(b"\r hello world\n ".trim_ascii_end(), b"\r hello world");
299 /// assert_eq!(b" ".trim_ascii_end(), b"");
300 /// assert_eq!(b"".trim_ascii_end(), b"");
301 /// ```
302 #[stable(feature = "byte_slice_trim_ascii", since = "1.80.0")]
303 #[rustc_const_stable(feature = "byte_slice_trim_ascii", since = "1.80.0")]
304 #[inline]
305 pub const fn trim_ascii_end(&self) -> &[u8] {
306 let mut bytes = self;
307 // Note: A pattern matching based approach (instead of indexing) allows
308 // making the function const.
309 while let [rest @ .., last] = bytes {
310 if last.is_ascii_whitespace() {
311 bytes = rest;
312 } else {
313 break;
314 }
315 }
316 bytes
317 }
318
319 /// Returns a byte slice with leading and trailing ASCII whitespace bytes
320 /// removed.
321 ///
322 /// 'Whitespace' refers to the definition used by
323 /// [`u8::is_ascii_whitespace`]. Importantly, this definition excludes
324 /// the `\0x0B` byte even though it has the Unicode [`White_Space`] property
325 /// and is removed by [`str::trim`].
326 ///
327 /// [`White_Space`]: https://www.unicode.org/reports/tr44/#White_Space
328 ///
329 /// # Examples
330 ///
331 /// ```
332 /// assert_eq!(b"\r hello world\n ".trim_ascii(), b"hello world");
333 /// assert_eq!(b" ".trim_ascii(), b"");
334 /// assert_eq!(b"".trim_ascii(), b"");
335 /// ```
336 #[stable(feature = "byte_slice_trim_ascii", since = "1.80.0")]
337 #[rustc_const_stable(feature = "byte_slice_trim_ascii", since = "1.80.0")]
338 #[inline]
339 pub const fn trim_ascii(&self) -> &[u8] {
340 self.trim_ascii_start().trim_ascii_end()
341 }
342
343 /// Splits a byte slice by ASCII whitespace.
344 ///
345 /// The returned iterator yields byte slices that are subslices of the
346 /// original byte slice, separated by any amount of ASCII whitespace.
347 ///
348 /// This uses the same definition as [`u8::is_ascii_whitespace`].
349 ///
350 /// # Examples
351 ///
352 /// Basic usage:
353 ///
354 /// ```
355 /// #![feature(u8_split_ascii_whitespace)]
356 ///
357 /// let mut iter = b"A few words".split_ascii_whitespace();
358 ///
359 /// assert_eq!(Some(&b"A"[..]), iter.next());
360 /// assert_eq!(Some(&b"few"[..]), iter.next());
361 /// assert_eq!(Some(&b"words"[..]), iter.next());
362 ///
363 /// assert_eq!(None, iter.next());
364 /// ```
365 ///
366 /// Various kinds of ASCII whitespace are considered
367 /// (see [`u8::is_ascii_whitespace`]):
368 ///
369 /// ```
370 /// #![feature(u8_split_ascii_whitespace)]
371 ///
372 /// let mut iter = b" Mary had\ta little \n\t lamb".split_ascii_whitespace();
373 ///
374 /// assert_eq!(Some(&b"Mary"[..]), iter.next());
375 /// assert_eq!(Some(&b"had"[..]), iter.next());
376 /// assert_eq!(Some(&b"a"[..]), iter.next());
377 /// assert_eq!(Some(&b"little"[..]), iter.next());
378 /// assert_eq!(Some(&b"lamb"[..]), iter.next());
379 ///
380 /// assert_eq!(None, iter.next());
381 /// ```
382 ///
383 /// If the byte slice is empty or contains only ASCII whitespace, the iterator
384 /// yields no byte slices:
385 ///
386 /// ```
387 /// #![feature(u8_split_ascii_whitespace)]
388 ///
389 /// assert_eq!(b"".split_ascii_whitespace().next(), None);
390 /// assert_eq!(b" ".split_ascii_whitespace().next(), None);
391 /// ```
392 #[must_use = "this returns the split byte slice as an iterator, without modifying the original"]
393 #[unstable(feature = "u8_split_ascii_whitespace", issue = "147878")]
394 #[inline]
395 pub fn split_ascii_whitespace(&self) -> SplitAsciiWhitespace<'_> {
396 let inner = self.split(IsAsciiWhitespace).filter(BytesIsNotEmpty);
397 SplitAsciiWhitespace { inner }
398 }
399}
400
401/// An iterator over the non-ASCII-whitespace subslices of a byte slice,
402/// separated by any amount of ASCII whitespace.
403///
404/// This struct is created by the [`split_ascii_whitespace`] method on [`[u8]`][byteslice].
405/// See its documentation for more.
406///
407/// [`split_ascii_whitespace`]: slice::split_ascii_whitespace
408/// [byteslice]: prim@slice
409#[unstable(feature = "u8_split_ascii_whitespace", issue = "147878")]
410#[derive(Clone, Debug)]
411pub struct SplitAsciiWhitespace<'a> {
412 pub(crate) inner: Filter<Split<'a, u8, IsAsciiWhitespace>, BytesIsNotEmpty>,
413}
414
415#[unstable(feature = "u8_split_ascii_whitespace", issue = "147878")]
416impl<'a> Iterator for SplitAsciiWhitespace<'a> {
417 type Item = &'a [u8];
418
419 #[inline]
420 fn next(&mut self) -> Option<&'a [u8]> {
421 self.inner.next()
422 }
423
424 #[inline]
425 fn size_hint(&self) -> (usize, Option<usize>) {
426 self.inner.size_hint()
427 }
428
429 #[inline]
430 fn last(mut self) -> Option<&'a [u8]> {
431 self.next_back()
432 }
433}
434
435#[unstable(feature = "u8_split_ascii_whitespace", issue = "147878")]
436impl<'a> DoubleEndedIterator for SplitAsciiWhitespace<'a> {
437 #[inline]
438 fn next_back(&mut self) -> Option<&'a [u8]> {
439 self.inner.next_back()
440 }
441}
442
443#[unstable(feature = "u8_split_ascii_whitespace", issue = "147878")]
444impl FusedIterator for SplitAsciiWhitespace<'_> {}
445
446impl<'a> SplitAsciiWhitespace<'a> {
447 /// Returns remainder of the split slice.
448 ///
449 /// If the iterator is empty, returns `None`.
450 ///
451 /// # Examples
452 ///
453 /// ```
454 /// #![feature(u8_split_ascii_whitespace)]
455 ///
456 /// let mut split = b"Mary had a little lamb".split_ascii_whitespace();
457 /// assert_eq!(split.remainder(), Some(b"Mary had a little lamb".as_slice()));
458 ///
459 /// split.next();
460 /// assert_eq!(split.remainder(), Some(b"had a little lamb".as_slice()));
461 ///
462 /// split.by_ref().for_each(drop);
463 /// assert_eq!(split.remainder(), None);
464 /// ```
465 #[inline]
466 #[must_use]
467 // This is also blocked on: https://github.com/rust-lang/rust/issues/77998
468 #[unstable(feature = "u8_split_ascii_whitespace", issue = "147878")]
469 pub fn remainder(&self) -> Option<&'a [u8]> {
470 if self.inner.iter.finished {
471 return None;
472 }
473
474 Some(self.inner.iter.v)
475 }
476}
477
478impl_fn_for_zst! {
479 #[derive(Clone)]
480 struct EscapeByte impl Fn = |byte: &u8| -> ascii::EscapeDefault {
481 ascii::escape_default(*byte)
482 };
483}
484
485/// An iterator over the escaped version of a byte slice.
486///
487/// This `struct` is created by the [`slice::escape_ascii`] method. See its
488/// documentation for more information.
489#[stable(feature = "inherent_ascii_escape", since = "1.60.0")]
490#[derive(Clone)]
491#[must_use = "iterators are lazy and do nothing unless consumed"]
492#[ferrocene::prevalidated]
493pub struct EscapeAscii<'a> {
494 inner: iter::FlatMap<super::Iter<'a, u8>, ascii::EscapeDefault, EscapeByte>,
495}
496
497#[stable(feature = "inherent_ascii_escape", since = "1.60.0")]
498impl<'a> iter::Iterator for EscapeAscii<'a> {
499 type Item = u8;
500 #[inline]
501 fn next(&mut self) -> Option<u8> {
502 self.inner.next()
503 }
504 #[inline]
505 fn size_hint(&self) -> (usize, Option<usize>) {
506 self.inner.size_hint()
507 }
508 #[inline]
509 fn try_fold<Acc, Fold, R>(&mut self, init: Acc, fold: Fold) -> R
510 where
511 Fold: FnMut(Acc, Self::Item) -> R,
512 R: ops::Try<Output = Acc>,
513 {
514 self.inner.try_fold(init, fold)
515 }
516 #[inline]
517 fn fold<Acc, Fold>(self, init: Acc, fold: Fold) -> Acc
518 where
519 Fold: FnMut(Acc, Self::Item) -> Acc,
520 {
521 self.inner.fold(init, fold)
522 }
523 #[inline]
524 fn last(mut self) -> Option<u8> {
525 self.next_back()
526 }
527}
528
529#[stable(feature = "inherent_ascii_escape", since = "1.60.0")]
530impl<'a> iter::DoubleEndedIterator for EscapeAscii<'a> {
531 fn next_back(&mut self) -> Option<u8> {
532 self.inner.next_back()
533 }
534}
535#[stable(feature = "inherent_ascii_escape", since = "1.60.0")]
536impl<'a> iter::FusedIterator for EscapeAscii<'a> {}
537#[stable(feature = "inherent_ascii_escape", since = "1.60.0")]
538impl<'a> fmt::Display for EscapeAscii<'a> {
539 #[ferrocene::prevalidated]
540 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
541 // disassemble iterator, including front/back parts of flatmap in case it has been partially consumed
542 let (front, slice, back) = self.clone().inner.into_parts();
543 let front = front.unwrap_or(EscapeDefault::empty());
544 let mut bytes = slice.unwrap_or_default().as_slice();
545 let back = back.unwrap_or(EscapeDefault::empty());
546
547 // usually empty, so the formatter won't have to do any work
548 for byte in front {
549 f.write_char(byte as char)?;
550 }
551
552 #[ferrocene::prevalidated]
553 fn needs_escape(b: u8) -> bool {
554 b > 0x7E || b < 0x20 || b == b'\\' || b == b'\'' || b == b'"'
555 }
556
557 while !bytes.is_empty() {
558 // fast path for the printable, non-escaped subset of ascii
559 let prefix = bytes.iter().take_while(|&&b| !needs_escape(b)).count();
560 // SAFETY: prefix length was derived by counting bytes in the same splice, so it's in-bounds
561 let (prefix, remainder) = unsafe { bytes.split_at_unchecked(prefix) };
562 // SAFETY: prefix is a valid utf8 sequence, as it's a subset of ASCII
563 let prefix = unsafe { crate::str::from_utf8_unchecked(prefix) };
564
565 f.write_str(prefix)?; // the fast part
566
567 bytes = remainder;
568
569 if let Some(&b) = bytes.first() {
570 // guaranteed to be non-empty, better to write it as a str
571 fmt::Display::fmt(&ascii::escape_default(b), f)?;
572 bytes = &bytes[1..];
573 }
574 }
575
576 // also usually empty
577 for byte in back {
578 f.write_char(byte as char)?;
579 }
580 Ok(())
581 }
582}
583#[stable(feature = "inherent_ascii_escape", since = "1.60.0")]
584impl<'a> fmt::Debug for EscapeAscii<'a> {
585 #[ferrocene::prevalidated]
586 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
587 f.debug_struct("EscapeAscii").finish_non_exhaustive()
588 }
589}
590
591/// ASCII test *without* the chunk-at-a-time optimizations.
592///
593/// This is carefully structured to produce nice small code -- it's smaller in
594/// `-O` than what the "obvious" ways produces under `-C opt-level=s`. If you
595/// touch it, be sure to run (and update if needed) the assembly test.
596#[unstable(feature = "str_internals", issue = "none")]
597#[doc(hidden)]
598#[inline]
599#[ferrocene::prevalidated]
600pub const fn is_ascii_simple(mut bytes: &[u8]) -> bool {
601 while let [rest @ .., last] = bytes {
602 if !last.is_ascii() {
603 break;
604 }
605 bytes = rest;
606 }
607 bytes.is_empty()
608}
609
610/// Optimized ASCII test that will use usize-at-a-time operations instead of
611/// byte-at-a-time operations (when possible).
612///
613/// The algorithm we use here is pretty simple. If `s` is too short, we just
614/// check each byte and be done with it. Otherwise:
615///
616/// - Read the first word with an unaligned load.
617/// - Align the pointer, read subsequent words until end with aligned loads.
618/// - Read the last `usize` from `s` with an unaligned load.
619///
620/// If any of these loads produces something for which `contains_nonascii`
621/// (above) returns true, then we know the answer is false.
622#[cfg(not(any(
623 all(target_arch = "x86_64", target_feature = "sse2"),
624 all(target_arch = "loongarch64", target_feature = "lsx"),
625 all(target_arch = "aarch64", target_feature = "neon")
626)))]
627#[inline]
628#[rustc_allow_const_fn_unstable(const_eval_select)] // fallback impl has same behavior
629#[ferrocene::prevalidated]
630const fn is_ascii(s: &[u8]) -> bool {
631 // The runtime version behaves the same as the compiletime version, it's
632 // just more optimized.
633 const_eval_select!(
634 @capture { s: &[u8] } -> bool:
635 if const {
636 is_ascii_simple(s)
637 } else {
638 /// Returns `true` if any byte in the word `v` is nonascii (>= 128). Snarfed
639 /// from `../str/mod.rs`, which does something similar for utf8 validation.
640 #[ferrocene::prevalidated]
641 const fn contains_nonascii(v: usize) -> bool {
642 const NONASCII_MASK: usize = usize::repeat_u8(0x80);
643 (NONASCII_MASK & v) != 0
644 }
645
646 const USIZE_SIZE: usize = size_of::<usize>();
647
648 let len = s.len();
649 let align_offset = s.as_ptr().align_offset(USIZE_SIZE);
650
651 // If we wouldn't gain anything from the word-at-a-time implementation, fall
652 // back to a scalar loop.
653 //
654 // We also do this for architectures where `size_of::<usize>()` isn't
655 // sufficient alignment for `usize`, because it's a weird edge case.
656 if len < USIZE_SIZE || len < align_offset || USIZE_SIZE < align_of::<usize>() {
657 return is_ascii_simple(s);
658 }
659
660 // We always read the first word unaligned, which means `align_offset` is
661 // 0, we'd read the same value again for the aligned read.
662 let offset_to_aligned = if align_offset == 0 { USIZE_SIZE } else { align_offset };
663
664 let start = s.as_ptr();
665 // SAFETY: We verify `len < USIZE_SIZE` above.
666 let first_word = unsafe { (start as *const usize).read_unaligned() };
667
668 if contains_nonascii(first_word) {
669 return false;
670 }
671 // We checked this above, somewhat implicitly. Note that `offset_to_aligned`
672 // is either `align_offset` or `USIZE_SIZE`, both of are explicitly checked
673 // above.
674 debug_assert!(offset_to_aligned <= len);
675
676 // SAFETY: word_ptr is the (properly aligned) usize ptr we use to read the
677 // middle chunk of the slice.
678 let mut word_ptr = unsafe { start.add(offset_to_aligned) as *const usize };
679
680 // `byte_pos` is the byte index of `word_ptr`, used for loop end checks.
681 let mut byte_pos = offset_to_aligned;
682
683 // Paranoia check about alignment, since we're about to do a bunch of
684 // unaligned loads. In practice this should be impossible barring a bug in
685 // `align_offset` though.
686 // While this method is allowed to spuriously fail in CTFE, if it doesn't
687 // have alignment information it should have given a `usize::MAX` for
688 // `align_offset` earlier, sending things through the scalar path instead of
689 // this one, so this check should pass if it's reachable.
690 debug_assert!(word_ptr.is_aligned_to(align_of::<usize>()));
691
692 // Read subsequent words until the last aligned word, excluding the last
693 // aligned word by itself to be done in tail check later, to ensure that
694 // tail is always one `usize` at most to extra branch `byte_pos == len`.
695 while byte_pos < len - USIZE_SIZE {
696 // Sanity check that the read is in bounds
697 debug_assert!(byte_pos + USIZE_SIZE <= len);
698 // And that our assumptions about `byte_pos` hold.
699 debug_assert!(word_ptr.cast::<u8>() == start.wrapping_add(byte_pos));
700
701 // SAFETY: We know `word_ptr` is properly aligned (because of
702 // `align_offset`), and we know that we have enough bytes between `word_ptr` and the end
703 let word = unsafe { word_ptr.read() };
704 if contains_nonascii(word) {
705 return false;
706 }
707
708 byte_pos += USIZE_SIZE;
709 // SAFETY: We know that `byte_pos <= len - USIZE_SIZE`, which means that
710 // after this `add`, `word_ptr` will be at most one-past-the-end.
711 word_ptr = unsafe { word_ptr.add(1) };
712 }
713
714 // Sanity check to ensure there really is only one `usize` left. This should
715 // be guaranteed by our loop condition.
716 debug_assert!(byte_pos <= len && len - byte_pos <= USIZE_SIZE);
717
718 // SAFETY: This relies on `len >= USIZE_SIZE`, which we check at the start.
719 let last_word = unsafe { (start.add(len - USIZE_SIZE) as *const usize).read_unaligned() };
720
721 !contains_nonascii(last_word)
722 }
723 )
724}
725
726/// Chunk size for SSE2 vectorized ASCII checking (4x 16-byte loads).
727#[cfg(all(target_arch = "x86_64", target_feature = "sse2"))]
728const SSE2_CHUNK_SIZE: usize = 64;
729
730#[ferrocene::prevalidated]
731#[cfg(all(target_arch = "x86_64", target_feature = "sse2"))]
732#[inline]
733fn is_ascii_sse2(bytes: &[u8]) -> bool {
734 use crate::arch::x86_64::{__m128i, _mm_loadu_si128, _mm_movemask_epi8, _mm_or_si128};
735
736 let (chunks, rest) = bytes.as_chunks::<SSE2_CHUNK_SIZE>();
737
738 for chunk in chunks {
739 let ptr = chunk.as_ptr();
740 // SAFETY: chunk is 64 bytes. SSE2 is baseline on x86_64.
741 let mask = unsafe {
742 let a1 = _mm_loadu_si128(ptr as *const __m128i);
743 let a2 = _mm_loadu_si128(ptr.add(16) as *const __m128i);
744 let b1 = _mm_loadu_si128(ptr.add(32) as *const __m128i);
745 let b2 = _mm_loadu_si128(ptr.add(48) as *const __m128i);
746 // OR all chunks - if any byte has high bit set, combined will too.
747 let combined = _mm_or_si128(_mm_or_si128(a1, a2), _mm_or_si128(b1, b2));
748 // Create a mask from the MSBs of each byte.
749 // If any byte is >= 128, its MSB is 1, so the mask will be non-zero.
750 _mm_movemask_epi8(combined)
751 };
752 if mask != 0 {
753 return false;
754 }
755 }
756
757 // Handle remaining bytes
758 rest.iter().all(|b| b.is_ascii())
759}
760
761/// Chunk size for NEON vectorized ASCII checking (4x 16-byte loads).
762#[cfg(all(target_arch = "aarch64", target_feature = "neon"))]
763const NEON_CHUNK_SIZE: usize = 64;
764
765/// Width of a single NEON vector, used to vectorize the tail left over by the
766/// unrolled `NEON_CHUNK_SIZE` loop.
767#[cfg(all(target_arch = "aarch64", target_feature = "neon"))]
768const NEON_VECTOR_SIZE: usize = 16;
769
770#[cfg(all(target_arch = "aarch64", target_feature = "neon"))]
771#[inline]
772#[ferrocene::prevalidated]
773fn is_ascii_neon(bytes: &[u8]) -> bool {
774 use crate::arch::aarch64::{vld1q_u8, vmaxvq_u8, vorrq_u8};
775
776 let (chunks, rest) = bytes.as_chunks::<NEON_CHUNK_SIZE>();
777
778 for chunk in chunks {
779 let ptr = chunk.as_ptr();
780 // SAFETY: chunk is 64 bytes, and `vld1q_u8` has no alignment requirement.
781 let max = unsafe {
782 let a1 = vld1q_u8(ptr);
783 let a2 = vld1q_u8(ptr.add(16));
784 let b1 = vld1q_u8(ptr.add(32));
785 let b2 = vld1q_u8(ptr.add(48));
786 // OR all chunks - if any byte has high bit set, combined will too.
787 let combined = vorrq_u8(vorrq_u8(a1, a2), vorrq_u8(b1, b2));
788 // `vmaxvq_u8` is a horizontal reduction with a longer latency than
789 // `vorrq_u8`, so it runs once per 64 bytes rather than once per load.
790 vmaxvq_u8(combined)
791 };
792 if max >= 128 {
793 return false;
794 }
795 }
796
797 // The unrolled loop above leaves up to 63 bytes, so sweep those a vector at
798 // a time before falling back to a byte-at-a-time check.
799 let (vectors, rest) = rest.as_chunks::<NEON_VECTOR_SIZE>();
800
801 for vector in vectors {
802 // SAFETY: vector is 16 bytes, and `vld1q_u8` has no alignment requirement.
803 let max = unsafe { vmaxvq_u8(vld1q_u8(vector.as_ptr())) };
804 if max >= 128 {
805 return false;
806 }
807 }
808
809 // Handle remaining bytes
810 rest.iter().all(|b| b.is_ascii())
811}
812
813/// Uses explicit SIMD intrinsics to prevent LLVM from auto-vectorizing with
814/// broken code (e.g., AVX-512 on x86-64 that extracts mask bits one-by-one).
815#[cfg(any(
816 all(target_arch = "x86_64", target_feature = "sse2"),
817 all(target_arch = "aarch64", target_feature = "neon")
818))]
819#[inline]
820#[rustc_allow_const_fn_unstable(const_eval_select)]
821#[ferrocene::prevalidated]
822const fn is_ascii(bytes: &[u8]) -> bool {
823 const USIZE_SIZE: usize = size_of::<usize>();
824 const NONASCII_MASK: usize = usize::MAX / 255 * 0x80;
825
826 #[cfg(all(target_arch = "x86_64", target_feature = "sse2"))]
827 const SIMD_MIN_LEN: usize = SSE2_CHUNK_SIZE;
828 #[cfg(all(target_arch = "aarch64", target_feature = "neon"))]
829 const SIMD_MIN_LEN: usize = NEON_CHUNK_SIZE;
830
831 const_eval_select!(
832 @capture { bytes: &[u8] } -> bool:
833 if const {
834 is_ascii_simple(bytes)
835 } else {
836 // For small inputs, use usize-at-a-time processing to avoid SSE2 call overhead.
837 if bytes.len() < SIMD_MIN_LEN {
838 let (chunks, remainder) = bytes.as_chunks::<USIZE_SIZE>();
839 for chunk in chunks {
840 let word = usize::from_ne_bytes(*chunk);
841 if (word & NONASCII_MASK) != 0 {
842 return false;
843 }
844 }
845 return remainder.iter().all(|b| b.is_ascii());
846 }
847
848 #[cfg(all(target_arch = "x86_64", target_feature = "sse2"))]
849 {
850 // Bug in the lint: is_ascii isn't validated, only the expansion of `is_ascii::runtime`
851 #[allow(ferrocene::unvalidated)]
852 is_ascii_sse2(bytes)
853 }
854 #[cfg(all(target_arch = "aarch64", target_feature = "neon"))]
855 { is_ascii_neon(bytes) }
856 }
857 )
858}
859
860/// ASCII test optimized to use the `vmskltz.b` instruction on `loongarch64`.
861///
862/// Other platforms are not likely to benefit from this code structure, so they
863/// use SWAR techniques to test for ASCII in `usize`-sized chunks.
864#[cfg(all(target_arch = "loongarch64", target_feature = "lsx"))]
865#[inline]
866const fn is_ascii(bytes: &[u8]) -> bool {
867 // Process chunks of 32 bytes at a time in the fast path to enable
868 // auto-vectorization and use of `vmskltz.b`. Two 128-bit vector registers
869 // can be OR'd together and then the resulting vector can be tested for
870 // non-ASCII bytes.
871 const CHUNK_SIZE: usize = 32;
872
873 let mut i = 0;
874
875 while i + CHUNK_SIZE <= bytes.len() {
876 let chunk_end = i + CHUNK_SIZE;
877
878 // Get LLVM to produce a `vmskltz.b` instruction on loongarch64 which
879 // creates a mask from the most significant bit of each byte.
880 // ASCII bytes are less than 128 (0x80), so their most significant
881 // bit is unset.
882 let mut count = 0;
883 while i < chunk_end {
884 count += bytes[i].is_ascii() as u8;
885 i += 1;
886 }
887
888 // All bytes should be <= 127 so count is equal to chunk size.
889 if count != CHUNK_SIZE as u8 {
890 return false;
891 }
892 }
893
894 // Process the remaining `bytes.len() % N` bytes.
895 let mut is_ascii = true;
896 while i < bytes.len() {
897 is_ascii &= bytes[i].is_ascii();
898 i += 1;
899 }
900
901 is_ascii
902}