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