1//! Operations on ASCII `[u8]`.
2
3use crate::ascii;
4use crate::fmt::{self, Write};
5use crate::iter;
6use crate::mem;
7use crate::ops;
8use core::ascii::EscapeDefault;
9
10#[cfg(not(test))]
11impl [u8] {
12 /// Checks if all bytes in this slice are within the ASCII range.
13 #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")]
14 #[rustc_const_stable(feature = "const_slice_is_ascii", since = "1.74.0")]
15 #[must_use]
16 #[inline]
17 pub const fn is_ascii(&self) -> bool {
18 is_ascii(self)
19 }
20
21 /// If this slice [`is_ascii`](Self::is_ascii), returns it as a slice of
22 /// [ASCII characters](`ascii::Char`), otherwise returns `None`.
23 #[unstable(feature = "ascii_char", issue = "110998")]
24 #[must_use]
25 #[inline]
26 pub const fn as_ascii(&self) -> Option<&[ascii::Char]> {
27 if self.is_ascii() {
28 // SAFETY: Just checked that it's ASCII
29 Some(unsafe { self.as_ascii_unchecked() })
30 } else {
31 None
32 }
33 }
34
35 /// Converts this slice of bytes into a slice of ASCII characters,
36 /// without checking whether they're valid.
37 ///
38 /// # Safety
39 ///
40 /// Every byte in the slice must be in `0..=127`, or else this is UB.
41 #[unstable(feature = "ascii_char", issue = "110998")]
42 #[must_use]
43 #[inline]
44 pub const unsafe fn as_ascii_unchecked(&self) -> &[ascii::Char] {
45 let byte_ptr: *const [u8] = self;
46 let ascii_ptr = byte_ptr as *const [ascii::Char];
47 // SAFETY: The caller promised all the bytes are ASCII
48 unsafe { &*ascii_ptr }
49 }
50
51 /// Checks that two slices are an ASCII case-insensitive match.
52 ///
53 /// Same as `to_ascii_lowercase(a) == to_ascii_lowercase(b)`,
54 /// but without allocating and copying temporaries.
55 #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")]
56 #[must_use]
57 #[inline]
58 pub fn eq_ignore_ascii_case(&self, other: &[u8]) -> bool {
59 self.len() == other.len() && iter::zip(self, other).all(|(a, b)| a.eq_ignore_ascii_case(b))
60 }
61
62 /// Converts this slice to its ASCII upper case equivalent in-place.
63 ///
64 /// ASCII letters 'a' to 'z' are mapped to 'A' to 'Z',
65 /// but non-ASCII letters are unchanged.
66 ///
67 /// To return a new uppercased value without modifying the existing one, use
68 /// [`to_ascii_uppercase`].
69 ///
70 /// [`to_ascii_uppercase`]: #method.to_ascii_uppercase
71 #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")]
72 #[inline]
73 pub fn make_ascii_uppercase(&mut self) {
74 for byte in self {
75 byte.make_ascii_uppercase();
76 }
77 }
78
79 /// Converts this slice to its ASCII lower case equivalent in-place.
80 ///
81 /// ASCII letters 'A' to 'Z' are mapped to 'a' to 'z',
82 /// but non-ASCII letters are unchanged.
83 ///
84 /// To return a new lowercased value without modifying the existing one, use
85 /// [`to_ascii_lowercase`].
86 ///
87 /// [`to_ascii_lowercase`]: #method.to_ascii_lowercase
88 #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")]
89 #[inline]
90 pub fn make_ascii_lowercase(&mut self) {
91 for byte in self {
92 byte.make_ascii_lowercase();
93 }
94 }
95
96 /// Returns an iterator that produces an escaped version of this slice,
97 /// treating it as an ASCII string.
98 ///
99 /// # Examples
100 ///
101 /// ```
102 ///
103 /// let s = b"0\t\r\n'\"\\\x9d";
104 /// let escaped = s.escape_ascii().to_string();
105 /// assert_eq!(escaped, "0\\t\\r\\n\\'\\\"\\\\\\x9d");
106 /// ```
107 #[must_use = "this returns the escaped bytes as an iterator, \
108 without modifying the original"]
109 #[stable(feature = "inherent_ascii_escape", since = "1.60.0")]
110 pub fn escape_ascii(&self) -> EscapeAscii<'_> {
111 EscapeAscii { inner: self.iter().flat_map(EscapeByte) }
112 }
113
114 /// Returns a byte slice with leading ASCII whitespace bytes removed.
115 ///
116 /// 'Whitespace' refers to the definition used by
117 /// `u8::is_ascii_whitespace`.
118 ///
119 /// # Examples
120 ///
121 /// ```
122 /// #![feature(byte_slice_trim_ascii)]
123 ///
124 /// assert_eq!(b" \t hello world\n".trim_ascii_start(), b"hello world\n");
125 /// assert_eq!(b" ".trim_ascii_start(), b"");
126 /// assert_eq!(b"".trim_ascii_start(), b"");
127 /// ```
128 #[unstable(feature = "byte_slice_trim_ascii", issue = "94035")]
129 #[inline]
130 pub const fn trim_ascii_start(&self) -> &[u8] {
131 let mut bytes = self;
132 // Note: A pattern matching based approach (instead of indexing) allows
133 // making the function const.
134 while let [first, rest @ ..] = bytes {
135 if first.is_ascii_whitespace() {
136 bytes = rest;
137 } else {
138 break;
139 }
140 }
141 bytes
142 }
143
144 /// Returns a byte slice with trailing ASCII whitespace bytes removed.
145 ///
146 /// 'Whitespace' refers to the definition used by
147 /// `u8::is_ascii_whitespace`.
148 ///
149 /// # Examples
150 ///
151 /// ```
152 /// #![feature(byte_slice_trim_ascii)]
153 ///
154 /// assert_eq!(b"\r hello world\n ".trim_ascii_end(), b"\r hello world");
155 /// assert_eq!(b" ".trim_ascii_end(), b"");
156 /// assert_eq!(b"".trim_ascii_end(), b"");
157 /// ```
158 #[unstable(feature = "byte_slice_trim_ascii", issue = "94035")]
159 #[inline]
160 pub const fn trim_ascii_end(&self) -> &[u8] {
161 let mut bytes = self;
162 // Note: A pattern matching based approach (instead of indexing) allows
163 // making the function const.
164 while let [rest @ .., last] = bytes {
165 if last.is_ascii_whitespace() {
166 bytes = rest;
167 } else {
168 break;
169 }
170 }
171 bytes
172 }
173
174 /// Returns a byte slice with leading and trailing ASCII whitespace bytes
175 /// removed.
176 ///
177 /// 'Whitespace' refers to the definition used by
178 /// `u8::is_ascii_whitespace`.
179 ///
180 /// # Examples
181 ///
182 /// ```
183 /// #![feature(byte_slice_trim_ascii)]
184 ///
185 /// assert_eq!(b"\r hello world\n ".trim_ascii(), b"hello world");
186 /// assert_eq!(b" ".trim_ascii(), b"");
187 /// assert_eq!(b"".trim_ascii(), b"");
188 /// ```
189 #[unstable(feature = "byte_slice_trim_ascii", issue = "94035")]
190 #[inline]
191 pub const fn trim_ascii(&self) -> &[u8] {
192 self.trim_ascii_start().trim_ascii_end()
193 }
194}
195
196impl_fn_for_zst! {
197 #[derive(Clone)]
198 struct EscapeByte impl Fn = |byte: &u8| -> ascii::EscapeDefault {
199 ascii::escape_default(*byte)
200 };
201}
202
203/// An iterator over the escaped version of a byte slice.
204///
205/// This `struct` is created by the [`slice::escape_ascii`] method. See its
206/// documentation for more information.
207#[stable(feature = "inherent_ascii_escape", since = "1.60.0")]
208#[derive(Clone)]
209#[must_use = "iterators are lazy and do nothing unless consumed"]
210pub struct EscapeAscii<'a> {
211 inner: iter::FlatMap<super::Iter<'a, u8>, ascii::EscapeDefault, EscapeByte>,
212}
213
214#[stable(feature = "inherent_ascii_escape", since = "1.60.0")]
215impl<'a> iter::Iterator for EscapeAscii<'a> {
216 type Item = u8;
217 #[inline]
218 fn next(&mut self) -> Option<u8> {
219 self.inner.next()
220 }
221 #[inline]
222 fn size_hint(&self) -> (usize, Option<usize>) {
223 self.inner.size_hint()
224 }
225 #[inline]
226 fn try_fold<Acc, Fold, R>(&mut self, init: Acc, fold: Fold) -> R
227 where
228 Fold: FnMut(Acc, Self::Item) -> R,
229 R: ops::Try<Output = Acc>,
230 {
231 self.inner.try_fold(init, fold)
232 }
233 #[inline]
234 fn fold<Acc, Fold>(self, init: Acc, fold: Fold) -> Acc
235 where
236 Fold: FnMut(Acc, Self::Item) -> Acc,
237 {
238 self.inner.fold(init, fold)
239 }
240 #[inline]
241 fn last(mut self) -> Option<u8> {
242 self.next_back()
243 }
244}
245
246#[stable(feature = "inherent_ascii_escape", since = "1.60.0")]
247impl<'a> iter::DoubleEndedIterator for EscapeAscii<'a> {
248 fn next_back(&mut self) -> Option<u8> {
249 self.inner.next_back()
250 }
251}
252#[stable(feature = "inherent_ascii_escape", since = "1.60.0")]
253impl<'a> iter::FusedIterator for EscapeAscii<'a> {}
254#[stable(feature = "inherent_ascii_escape", since = "1.60.0")]
255impl<'a> fmt::Display for EscapeAscii<'a> {
256 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
257 // disassemble iterator, including front/back parts of flatmap in case it has been partially consumed
258 let (front, slice, back) = self.clone().inner.into_parts();
259 let front = front.unwrap_or(EscapeDefault::empty());
260 let mut bytes = slice.unwrap_or_default().as_slice();
261 let back = back.unwrap_or(EscapeDefault::empty());
262
263 // usually empty, so the formatter won't have to do any work
264 for byte in front {
265 f.write_char(byte as char)?;
266 }
267
268 fn needs_escape(b: u8) -> bool {
269 b > 0x7E || b < 0x20 || b == b'\\' || b == b'\'' || b == b'"'
270 }
271
272 while bytes.len() > 0 {
273 // fast path for the printable, non-escaped subset of ascii
274 let prefix = bytes.iter().take_while(|&&b| !needs_escape(b)).count();
275 // SAFETY: prefix length was derived by counting bytes in the same splice, so it's in-bounds
276 let (prefix, remainder) = unsafe { bytes.split_at_unchecked(prefix) };
277 // SAFETY: prefix is a valid utf8 sequence, as it's a subset of ASCII
278 let prefix = unsafe { crate::str::from_utf8_unchecked(prefix) };
279
280 f.write_str(prefix)?; // the fast part
281
282 bytes = remainder;
283
284 if let Some(&b) = bytes.first() {
285 // guaranteed to be non-empty, better to write it as a str
286 f.write_str(ascii::escape_default(b).as_str())?;
287 bytes = &bytes[1..];
288 }
289 }
290
291 // also usually empty
292 for byte in back {
293 f.write_char(byte as char)?;
294 }
295 Ok(())
296 }
297}
298#[stable(feature = "inherent_ascii_escape", since = "1.60.0")]
299impl<'a> fmt::Debug for EscapeAscii<'a> {
300 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
301 f.debug_struct(name:"EscapeAscii").finish_non_exhaustive()
302 }
303}
304
305/// Returns `true` if any byte in the word `v` is nonascii (>= 128). Snarfed
306/// from `../str/mod.rs`, which does something similar for utf8 validation.
307#[inline]
308const fn contains_nonascii(v: usize) -> bool {
309 const NONASCII_MASK: usize = usize::repeat_u8(0x80);
310 (NONASCII_MASK & v) != 0
311}
312
313/// ASCII test *without* the chunk-at-a-time optimizations.
314///
315/// This is carefully structured to produce nice small code -- it's smaller in
316/// `-O` than what the "obvious" ways produces under `-C opt-level=s`. If you
317/// touch it, be sure to run (and update if needed) the assembly test.
318#[unstable(feature = "str_internals", issue = "none")]
319#[doc(hidden)]
320#[inline]
321pub const fn is_ascii_simple(mut bytes: &[u8]) -> bool {
322 while let [rest: &[u8] @ .., last: &u8] = bytes {
323 if !last.is_ascii() {
324 break;
325 }
326 bytes = rest;
327 }
328 bytes.is_empty()
329}
330
331/// Optimized ASCII test that will use usize-at-a-time operations instead of
332/// byte-at-a-time operations (when possible).
333///
334/// The algorithm we use here is pretty simple. If `s` is too short, we just
335/// check each byte and be done with it. Otherwise:
336///
337/// - Read the first word with an unaligned load.
338/// - Align the pointer, read subsequent words until end with aligned loads.
339/// - Read the last `usize` from `s` with an unaligned load.
340///
341/// If any of these loads produces something for which `contains_nonascii`
342/// (above) returns true, then we know the answer is false.
343#[inline]
344const fn is_ascii(s: &[u8]) -> bool {
345 const USIZE_SIZE: usize = mem::size_of::<usize>();
346
347 let len = s.len();
348 let align_offset = s.as_ptr().align_offset(USIZE_SIZE);
349
350 // If we wouldn't gain anything from the word-at-a-time implementation, fall
351 // back to a scalar loop.
352 //
353 // We also do this for architectures where `size_of::<usize>()` isn't
354 // sufficient alignment for `usize`, because it's a weird edge case.
355 if len < USIZE_SIZE || len < align_offset || USIZE_SIZE < mem::align_of::<usize>() {
356 return is_ascii_simple(s);
357 }
358
359 // We always read the first word unaligned, which means `align_offset` is
360 // 0, we'd read the same value again for the aligned read.
361 let offset_to_aligned = if align_offset == 0 { USIZE_SIZE } else { align_offset };
362
363 let start = s.as_ptr();
364 // SAFETY: We verify `len < USIZE_SIZE` above.
365 let first_word = unsafe { (start as *const usize).read_unaligned() };
366
367 if contains_nonascii(first_word) {
368 return false;
369 }
370 // We checked this above, somewhat implicitly. Note that `offset_to_aligned`
371 // is either `align_offset` or `USIZE_SIZE`, both of are explicitly checked
372 // above.
373 debug_assert!(offset_to_aligned <= len);
374
375 // SAFETY: word_ptr is the (properly aligned) usize ptr we use to read the
376 // middle chunk of the slice.
377 let mut word_ptr = unsafe { start.add(offset_to_aligned) as *const usize };
378
379 // `byte_pos` is the byte index of `word_ptr`, used for loop end checks.
380 let mut byte_pos = offset_to_aligned;
381
382 // Paranoia check about alignment, since we're about to do a bunch of
383 // unaligned loads. In practice this should be impossible barring a bug in
384 // `align_offset` though.
385 // While this method is allowed to spuriously fail in CTFE, if it doesn't
386 // have alignment information it should have given a `usize::MAX` for
387 // `align_offset` earlier, sending things through the scalar path instead of
388 // this one, so this check should pass if it's reachable.
389 debug_assert!(word_ptr.is_aligned_to(mem::align_of::<usize>()));
390
391 // Read subsequent words until the last aligned word, excluding the last
392 // aligned word by itself to be done in tail check later, to ensure that
393 // tail is always one `usize` at most to extra branch `byte_pos == len`.
394 while byte_pos < len - USIZE_SIZE {
395 // Sanity check that the read is in bounds
396 debug_assert!(byte_pos + USIZE_SIZE <= len);
397 // And that our assumptions about `byte_pos` hold.
398 debug_assert!(matches!(
399 word_ptr.cast::<u8>().guaranteed_eq(start.wrapping_add(byte_pos)),
400 // These are from the same allocation, so will hopefully always be
401 // known to match even in CTFE, but if it refuses to compare them
402 // that's ok since it's just a debug check anyway.
403 None | Some(true),
404 ));
405
406 // SAFETY: We know `word_ptr` is properly aligned (because of
407 // `align_offset`), and we know that we have enough bytes between `word_ptr` and the end
408 let word = unsafe { word_ptr.read() };
409 if contains_nonascii(word) {
410 return false;
411 }
412
413 byte_pos += USIZE_SIZE;
414 // SAFETY: We know that `byte_pos <= len - USIZE_SIZE`, which means that
415 // after this `add`, `word_ptr` will be at most one-past-the-end.
416 word_ptr = unsafe { word_ptr.add(1) };
417 }
418
419 // Sanity check to ensure there really is only one `usize` left. This should
420 // be guaranteed by our loop condition.
421 debug_assert!(byte_pos <= len && len - byte_pos <= USIZE_SIZE);
422
423 // SAFETY: This relies on `len >= USIZE_SIZE`, which we check at the start.
424 let last_word = unsafe { (start.add(len - USIZE_SIZE) as *const usize).read_unaligned() };
425
426 !contains_nonascii(last_word)
427}
428