core/ascii.rs
1//! Operations on ASCII strings and characters.
2//!
3//! Most string operations in Rust act on UTF-8 strings. However, at times it
4//! makes more sense to only consider the ASCII character set for a specific
5//! operation.
6//!
7//! The [`escape_default`] function provides an iterator over the bytes of an
8//! escaped version of the character given.
9
10#![stable(feature = "core_ascii", since = "1.26.0")]
11
12use crate::escape::{AlwaysEscaped, EscapeIterInner};
13use crate::fmt;
14use crate::iter::FusedIterator;
15use crate::num::NonZero;
16
17mod ascii_char;
18#[doc(alias("AsciiChar"))]
19#[unstable(feature = "ascii_char", issue = "110998")]
20pub use ascii_char::AsciiChar as Char;
21
22/// An iterator over the escaped version of a byte.
23///
24/// This `struct` is created by the [`escape_default`] function. See its
25/// documentation for more.
26#[must_use = "iterators are lazy and do nothing unless consumed"]
27#[stable(feature = "rust1", since = "1.0.0")]
28#[derive(Clone)]
29pub struct EscapeDefault(EscapeIterInner<4, AlwaysEscaped>);
30
31/// Returns an iterator that produces an escaped version of a `u8`.
32///
33/// The default is chosen with a bias toward producing literals that are
34/// legal in a variety of languages, including C++11 and similar C-family
35/// languages. The exact rules are:
36///
37/// * Tab is escaped as `\t`.
38/// * Carriage return is escaped as `\r`.
39/// * Line feed is escaped as `\n`.
40/// * Single quote is escaped as `\'`.
41/// * Double quote is escaped as `\"`.
42/// * Backslash is escaped as `\\`.
43/// * Any character in the 'printable ASCII' range `0x20` .. `0x7e`
44/// inclusive is not escaped.
45/// * Any other chars are given hex escapes of the form '\xNN'.
46/// * Unicode escapes are never generated by this function.
47///
48/// # Examples
49///
50/// ```
51/// use std::ascii;
52///
53/// let escaped = ascii::escape_default(b'0').next().unwrap();
54/// assert_eq!(b'0', escaped);
55///
56/// let mut escaped = ascii::escape_default(b'\t');
57///
58/// assert_eq!(b'\\', escaped.next().unwrap());
59/// assert_eq!(b't', escaped.next().unwrap());
60///
61/// let mut escaped = ascii::escape_default(b'\r');
62///
63/// assert_eq!(b'\\', escaped.next().unwrap());
64/// assert_eq!(b'r', escaped.next().unwrap());
65///
66/// let mut escaped = ascii::escape_default(b'\n');
67///
68/// assert_eq!(b'\\', escaped.next().unwrap());
69/// assert_eq!(b'n', escaped.next().unwrap());
70///
71/// let mut escaped = ascii::escape_default(b'\'');
72///
73/// assert_eq!(b'\\', escaped.next().unwrap());
74/// assert_eq!(b'\'', escaped.next().unwrap());
75///
76/// let mut escaped = ascii::escape_default(b'"');
77///
78/// assert_eq!(b'\\', escaped.next().unwrap());
79/// assert_eq!(b'"', escaped.next().unwrap());
80///
81/// let mut escaped = ascii::escape_default(b'\\');
82///
83/// assert_eq!(b'\\', escaped.next().unwrap());
84/// assert_eq!(b'\\', escaped.next().unwrap());
85///
86/// let mut escaped = ascii::escape_default(b'\x9d');
87///
88/// assert_eq!(b'\\', escaped.next().unwrap());
89/// assert_eq!(b'x', escaped.next().unwrap());
90/// assert_eq!(b'9', escaped.next().unwrap());
91/// assert_eq!(b'd', escaped.next().unwrap());
92/// ```
93#[stable(feature = "rust1", since = "1.0.0")]
94pub fn escape_default(c: u8) -> EscapeDefault {
95 EscapeDefault::new(c)
96}
97
98impl EscapeDefault {
99 #[inline]
100 pub(crate) const fn new(c: u8) -> Self {
101 Self(EscapeIterInner::ascii(c))
102 }
103
104 #[inline]
105 pub(crate) fn empty() -> Self {
106 Self(EscapeIterInner::empty())
107 }
108}
109
110#[stable(feature = "rust1", since = "1.0.0")]
111impl Iterator for EscapeDefault {
112 type Item = u8;
113
114 #[inline]
115 fn next(&mut self) -> Option<u8> {
116 self.0.next()
117 }
118
119 #[inline]
120 fn size_hint(&self) -> (usize, Option<usize>) {
121 let n = self.0.len();
122 (n, Some(n))
123 }
124
125 #[inline]
126 fn count(self) -> usize {
127 self.0.len()
128 }
129
130 #[inline]
131 fn last(mut self) -> Option<u8> {
132 self.0.next_back()
133 }
134
135 #[inline]
136 fn advance_by(&mut self, n: usize) -> Result<(), NonZero<usize>> {
137 self.0.advance_by(n)
138 }
139}
140
141#[stable(feature = "rust1", since = "1.0.0")]
142impl DoubleEndedIterator for EscapeDefault {
143 #[inline]
144 fn next_back(&mut self) -> Option<u8> {
145 self.0.next_back()
146 }
147
148 #[inline]
149 fn advance_back_by(&mut self, n: usize) -> Result<(), NonZero<usize>> {
150 self.0.advance_back_by(n)
151 }
152}
153
154#[stable(feature = "rust1", since = "1.0.0")]
155impl ExactSizeIterator for EscapeDefault {
156 #[inline]
157 fn len(&self) -> usize {
158 self.0.len()
159 }
160}
161
162#[stable(feature = "fused", since = "1.26.0")]
163impl FusedIterator for EscapeDefault {}
164
165#[stable(feature = "ascii_escape_display", since = "1.39.0")]
166impl fmt::Display for EscapeDefault {
167 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
168 fmt::Display::fmt(&self.0, f)
169 }
170}
171
172#[stable(feature = "std_debug", since = "1.16.0")]
173impl fmt::Debug for EscapeDefault {
174 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
175 f.debug_struct("EscapeDefault").finish_non_exhaustive()
176 }
177}