Skip to content

Commit 469fe7a

Browse files
authored
Rollup merge of rust-lang#40988 - eugene-bulkin:ascii-docs, r=frewsxcv
API Docs: ascii Add/update docs for the `ascii` module per rust-lang#29341. r? @steveklabnik
2 parents b0aefe3 + a5d775d commit 469fe7a

File tree

1 file changed

+58
-8
lines changed

1 file changed

+58
-8
lines changed

src/libstd/ascii.rs

+58-8
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,20 @@
99
// except according to those terms.
1010

1111
//! Operations on ASCII strings and characters.
12+
//!
13+
//! Most string operations in Rust act on UTF-8 strings. However, at times it
14+
//! makes more sense to only consider the ASCII character set for a specific
15+
//! operation.
16+
//!
17+
//! The [`AsciiExt`] trait provides methods that allow for character
18+
//! operations that only act on the ASCII subset and leave non-ASCII characters
19+
//! alone.
20+
//!
21+
//! The [`escape_default`] function provides an iterator over the bytes of an
22+
//! escaped version of the character given.
23+
//!
24+
//! [`AsciiExt`]: trait.AsciiExt.html
25+
//! [`escape_default`]: fn.escape_default.html
1226
1327
#![stable(feature = "rust1", since = "1.0.0")]
1428

@@ -53,11 +67,11 @@ pub trait AsciiExt {
5367
/// use std::ascii::AsciiExt;
5468
///
5569
/// let ascii = 'a';
56-
/// let utf8 = '❤';
70+
/// let non_ascii = '❤';
5771
/// let int_ascii = 97;
5872
///
5973
/// assert!(ascii.is_ascii());
60-
/// assert!(!utf8.is_ascii());
74+
/// assert!(!non_ascii.is_ascii());
6175
/// assert!(int_ascii.is_ascii());
6276
/// ```
6377
#[stable(feature = "rust1", since = "1.0.0")]
@@ -79,11 +93,11 @@ pub trait AsciiExt {
7993
/// use std::ascii::AsciiExt;
8094
///
8195
/// let ascii = 'a';
82-
/// let utf8 = '❤';
96+
/// let non_ascii = '❤';
8397
/// let int_ascii = 97;
8498
///
8599
/// assert_eq!('A', ascii.to_ascii_uppercase());
86-
/// assert_eq!('❤', utf8.to_ascii_uppercase());
100+
/// assert_eq!('❤', non_ascii.to_ascii_uppercase());
87101
/// assert_eq!(65, int_ascii.to_ascii_uppercase());
88102
/// ```
89103
///
@@ -108,11 +122,11 @@ pub trait AsciiExt {
108122
/// use std::ascii::AsciiExt;
109123
///
110124
/// let ascii = 'A';
111-
/// let utf8 = '❤';
125+
/// let non_ascii = '❤';
112126
/// let int_ascii = 65;
113127
///
114128
/// assert_eq!('a', ascii.to_ascii_lowercase());
115-
/// assert_eq!('❤', utf8.to_ascii_lowercase());
129+
/// assert_eq!('❤', non_ascii.to_ascii_lowercase());
116130
/// assert_eq!(97, int_ascii.to_ascii_lowercase());
117131
/// ```
118132
///
@@ -934,8 +948,12 @@ impl AsciiExt for char {
934948
}
935949
}
936950

937-
/// An iterator over the escaped version of a byte, constructed via
938-
/// `std::ascii::escape_default`.
951+
/// An iterator over the escaped version of a byte.
952+
///
953+
/// This `struct` is created by the [`escape_default`] function. See its
954+
/// documentation for more.
955+
///
956+
/// [`escape_default`]: fn.escape_default.html
939957
#[stable(feature = "rust1", since = "1.0.0")]
940958
pub struct EscapeDefault {
941959
range: Range<usize>,
@@ -966,6 +984,38 @@ pub struct EscapeDefault {
966984
///
967985
/// assert_eq!(b'\\', escaped.next().unwrap());
968986
/// assert_eq!(b't', escaped.next().unwrap());
987+
///
988+
/// let mut escaped = ascii::escape_default(b'\r');
989+
///
990+
/// assert_eq!(b'\\', escaped.next().unwrap());
991+
/// assert_eq!(b'r', escaped.next().unwrap());
992+
///
993+
/// let mut escaped = ascii::escape_default(b'\n');
994+
///
995+
/// assert_eq!(b'\\', escaped.next().unwrap());
996+
/// assert_eq!(b'n', escaped.next().unwrap());
997+
///
998+
/// let mut escaped = ascii::escape_default(b'\'');
999+
///
1000+
/// assert_eq!(b'\\', escaped.next().unwrap());
1001+
/// assert_eq!(b'\'', escaped.next().unwrap());
1002+
///
1003+
/// let mut escaped = ascii::escape_default(b'"');
1004+
///
1005+
/// assert_eq!(b'\\', escaped.next().unwrap());
1006+
/// assert_eq!(b'"', escaped.next().unwrap());
1007+
///
1008+
/// let mut escaped = ascii::escape_default(b'\\');
1009+
///
1010+
/// assert_eq!(b'\\', escaped.next().unwrap());
1011+
/// assert_eq!(b'\\', escaped.next().unwrap());
1012+
///
1013+
/// let mut escaped = ascii::escape_default(b'\x9d');
1014+
///
1015+
/// assert_eq!(b'\\', escaped.next().unwrap());
1016+
/// assert_eq!(b'x', escaped.next().unwrap());
1017+
/// assert_eq!(b'9', escaped.next().unwrap());
1018+
/// assert_eq!(b'd', escaped.next().unwrap());
9691019
/// ```
9701020
#[stable(feature = "rust1", since = "1.0.0")]
9711021
pub fn escape_default(c: u8) -> EscapeDefault {

0 commit comments

Comments
 (0)