1 | //! Operations on ASCII `[u8]`. |
2 | |
3 | use crate::ascii; |
4 | use crate::fmt::{self, Write}; |
5 | use crate::iter; |
6 | use crate::mem; |
7 | use crate::ops; |
8 | use core::ascii::EscapeDefault; |
9 | |
10 | #[cfg (not(test))] |
11 | impl [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 | |
196 | impl_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" ] |
210 | pub 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" )] |
215 | impl<'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" )] |
247 | impl<'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" )] |
253 | impl<'a> iter::FusedIterator for EscapeAscii<'a> {} |
254 | #[stable (feature = "inherent_ascii_escape" , since = "1.60.0" )] |
255 | impl<'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" )] |
299 | impl<'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 ] |
308 | const 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 ] |
321 | pub 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 ] |
344 | const 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 | |