1 //! Operations on ASCII `[u8]`.
4 use crate::fmt::{self, Write};
11 /// Checks if all bytes in this slice are within the ASCII range.
12 #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")]
15 pub fn is_ascii(&self) -> bool {
19 /// Checks that two slices are an ASCII case-insensitive match.
21 /// Same as `to_ascii_lowercase(a) == to_ascii_lowercase(b)`,
22 /// but without allocating and copying temporaries.
23 #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")]
26 pub fn eq_ignore_ascii_case(&self, other: &[u8]) -> bool {
27 self.len() == other.len() && iter::zip(self, other).all(|(a, b)| a.eq_ignore_ascii_case(b))
30 /// Converts this slice to its ASCII upper case equivalent in-place.
32 /// ASCII letters 'a' to 'z' are mapped to 'A' to 'Z',
33 /// but non-ASCII letters are unchanged.
35 /// To return a new uppercased value without modifying the existing one, use
36 /// [`to_ascii_uppercase`].
38 /// [`to_ascii_uppercase`]: #method.to_ascii_uppercase
39 #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")]
41 pub fn make_ascii_uppercase(&mut self) {
43 byte.make_ascii_uppercase();
47 /// Converts this slice to its ASCII lower case equivalent in-place.
49 /// ASCII letters 'A' to 'Z' are mapped to 'a' to 'z',
50 /// but non-ASCII letters are unchanged.
52 /// To return a new lowercased value without modifying the existing one, use
53 /// [`to_ascii_lowercase`].
55 /// [`to_ascii_lowercase`]: #method.to_ascii_lowercase
56 #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")]
58 pub fn make_ascii_lowercase(&mut self) {
60 byte.make_ascii_lowercase();
64 /// Returns an iterator that produces an escaped version of this slice,
65 /// treating it as an ASCII string.
71 /// let s = b"0\t\r\n'\"\\\x9d";
72 /// let escaped = s.escape_ascii().to_string();
73 /// assert_eq!(escaped, "0\\t\\r\\n\\'\\\"\\\\\\x9d");
75 #[must_use = "this returns the escaped bytes as an iterator, \
76 without modifying the original"]
77 #[stable(feature = "inherent_ascii_escape", since = "1.60.0")]
78 pub fn escape_ascii(&self) -> EscapeAscii<'_> {
79 EscapeAscii { inner: self.iter().flat_map(EscapeByte) }
82 /// Returns a byte slice with leading ASCII whitespace bytes removed.
84 /// 'Whitespace' refers to the definition used by
85 /// `u8::is_ascii_whitespace`.
90 /// #![feature(byte_slice_trim_ascii)]
92 /// assert_eq!(b" \t hello world\n".trim_ascii_start(), b"hello world\n");
93 /// assert_eq!(b" ".trim_ascii_start(), b"");
94 /// assert_eq!(b"".trim_ascii_start(), b"");
96 #[unstable(feature = "byte_slice_trim_ascii", issue = "94035")]
97 pub const fn trim_ascii_start(&self) -> &[u8] {
99 // Note: A pattern matching based approach (instead of indexing) allows
100 // making the function const.
101 while let [first, rest @ ..] = bytes {
102 if first.is_ascii_whitespace() {
111 /// Returns a byte slice with trailing ASCII whitespace bytes removed.
113 /// 'Whitespace' refers to the definition used by
114 /// `u8::is_ascii_whitespace`.
119 /// #![feature(byte_slice_trim_ascii)]
121 /// assert_eq!(b"\r hello world\n ".trim_ascii_end(), b"\r hello world");
122 /// assert_eq!(b" ".trim_ascii_end(), b"");
123 /// assert_eq!(b"".trim_ascii_end(), b"");
125 #[unstable(feature = "byte_slice_trim_ascii", issue = "94035")]
126 pub const fn trim_ascii_end(&self) -> &[u8] {
127 let mut bytes = self;
128 // Note: A pattern matching based approach (instead of indexing) allows
129 // making the function const.
130 while let [rest @ .., last] = bytes {
131 if last.is_ascii_whitespace() {
140 /// Returns a byte slice with leading and trailing ASCII whitespace bytes
143 /// 'Whitespace' refers to the definition used by
144 /// `u8::is_ascii_whitespace`.
149 /// #![feature(byte_slice_trim_ascii)]
151 /// assert_eq!(b"\r hello world\n ".trim_ascii(), b"hello world");
152 /// assert_eq!(b" ".trim_ascii(), b"");
153 /// assert_eq!(b"".trim_ascii(), b"");
155 #[unstable(feature = "byte_slice_trim_ascii", issue = "94035")]
156 pub const fn trim_ascii(&self) -> &[u8] {
157 self.trim_ascii_start().trim_ascii_end()
163 struct EscapeByte impl Fn = |byte: &u8| -> ascii::EscapeDefault {
164 ascii::escape_default(*byte)
168 /// An iterator over the escaped version of a byte slice.
170 /// This `struct` is created by the [`slice::escape_ascii`] method. See its
171 /// documentation for more information.
172 #[stable(feature = "inherent_ascii_escape", since = "1.60.0")]
174 #[must_use = "iterators are lazy and do nothing unless consumed"]
175 pub struct EscapeAscii<'a> {
176 inner: iter::FlatMap<super::Iter<'a, u8>, ascii::EscapeDefault, EscapeByte>,
179 #[stable(feature = "inherent_ascii_escape", since = "1.60.0")]
180 impl<'a> iter::Iterator for EscapeAscii<'a> {
183 fn next(&mut self) -> Option<u8> {
187 fn size_hint(&self) -> (usize, Option<usize>) {
188 self.inner.size_hint()
191 fn try_fold<Acc, Fold, R>(&mut self, init: Acc, fold: Fold) -> R
193 Fold: FnMut(Acc, Self::Item) -> R,
194 R: ops::Try<Output = Acc>,
196 self.inner.try_fold(init, fold)
199 fn fold<Acc, Fold>(self, init: Acc, fold: Fold) -> Acc
201 Fold: FnMut(Acc, Self::Item) -> Acc,
203 self.inner.fold(init, fold)
206 fn last(mut self) -> Option<u8> {
211 #[stable(feature = "inherent_ascii_escape", since = "1.60.0")]
212 impl<'a> iter::DoubleEndedIterator for EscapeAscii<'a> {
213 fn next_back(&mut self) -> Option<u8> {
214 self.inner.next_back()
217 #[stable(feature = "inherent_ascii_escape", since = "1.60.0")]
218 impl<'a> iter::FusedIterator for EscapeAscii<'a> {}
219 #[stable(feature = "inherent_ascii_escape", since = "1.60.0")]
220 impl<'a> fmt::Display for EscapeAscii<'a> {
221 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
222 self.clone().try_for_each(|b| f.write_char(b as char))
225 #[stable(feature = "inherent_ascii_escape", since = "1.60.0")]
226 impl<'a> fmt::Debug for EscapeAscii<'a> {
227 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
228 f.debug_struct("EscapeAscii").finish_non_exhaustive()
232 /// Returns `true` if any byte in the word `v` is nonascii (>= 128). Snarfed
233 /// from `../str/mod.rs`, which does something similar for utf8 validation.
235 fn contains_nonascii(v: usize) -> bool {
236 const NONASCII_MASK: usize = usize::repeat_u8(0x80);
237 (NONASCII_MASK & v) != 0
240 /// Optimized ASCII test that will use usize-at-a-time operations instead of
241 /// byte-at-a-time operations (when possible).
243 /// The algorithm we use here is pretty simple. If `s` is too short, we just
244 /// check each byte and be done with it. Otherwise:
246 /// - Read the first word with an unaligned load.
247 /// - Align the pointer, read subsequent words until end with aligned loads.
248 /// - Read the last `usize` from `s` with an unaligned load.
250 /// If any of these loads produces something for which `contains_nonascii`
251 /// (above) returns true, then we know the answer is false.
253 fn is_ascii(s: &[u8]) -> bool {
254 const USIZE_SIZE: usize = mem::size_of::<usize>();
257 let align_offset = s.as_ptr().align_offset(USIZE_SIZE);
259 // If we wouldn't gain anything from the word-at-a-time implementation, fall
260 // back to a scalar loop.
262 // We also do this for architectures where `size_of::<usize>()` isn't
263 // sufficient alignment for `usize`, because it's a weird edge case.
264 if len < USIZE_SIZE || len < align_offset || USIZE_SIZE < mem::align_of::<usize>() {
265 return s.iter().all(|b| b.is_ascii());
268 // We always read the first word unaligned, which means `align_offset` is
269 // 0, we'd read the same value again for the aligned read.
270 let offset_to_aligned = if align_offset == 0 { USIZE_SIZE } else { align_offset };
272 let start = s.as_ptr();
273 // SAFETY: We verify `len < USIZE_SIZE` above.
274 let first_word = unsafe { (start as *const usize).read_unaligned() };
276 if contains_nonascii(first_word) {
279 // We checked this above, somewhat implicitly. Note that `offset_to_aligned`
280 // is either `align_offset` or `USIZE_SIZE`, both of are explicitly checked
282 debug_assert!(offset_to_aligned <= len);
284 // SAFETY: word_ptr is the (properly aligned) usize ptr we use to read the
285 // middle chunk of the slice.
286 let mut word_ptr = unsafe { start.add(offset_to_aligned) as *const usize };
288 // `byte_pos` is the byte index of `word_ptr`, used for loop end checks.
289 let mut byte_pos = offset_to_aligned;
291 // Paranoia check about alignment, since we're about to do a bunch of
292 // unaligned loads. In practice this should be impossible barring a bug in
293 // `align_offset` though.
294 debug_assert_eq!(word_ptr.addr() % mem::align_of::<usize>(), 0);
296 // Read subsequent words until the last aligned word, excluding the last
297 // aligned word by itself to be done in tail check later, to ensure that
298 // tail is always one `usize` at most to extra branch `byte_pos == len`.
299 while byte_pos < len - USIZE_SIZE {
301 // Sanity check that the read is in bounds
302 (word_ptr.addr() + USIZE_SIZE) <= start.addr().wrapping_add(len) &&
303 // And that our assumptions about `byte_pos` hold.
304 (word_ptr.addr() - start.addr()) == byte_pos
307 // SAFETY: We know `word_ptr` is properly aligned (because of
308 // `align_offset`), and we know that we have enough bytes between `word_ptr` and the end
309 let word = unsafe { word_ptr.read() };
310 if contains_nonascii(word) {
314 byte_pos += USIZE_SIZE;
315 // SAFETY: We know that `byte_pos <= len - USIZE_SIZE`, which means that
316 // after this `add`, `word_ptr` will be at most one-past-the-end.
317 word_ptr = unsafe { word_ptr.add(1) };
320 // Sanity check to ensure there really is only one `usize` left. This should
321 // be guaranteed by our loop condition.
322 debug_assert!(byte_pos <= len && len - byte_pos <= USIZE_SIZE);
324 // SAFETY: This relies on `len >= USIZE_SIZE`, which we check at the start.
325 let last_word = unsafe { (start.add(len - USIZE_SIZE) as *const usize).read_unaligned() };
327 !contains_nonascii(last_word)