Skip to content

Commit a96cddb

Browse files
Dylan-DPCDylan-DPC
authored
Rollup merge of rust-lang#95566 - eduardosm:std_char_consts_and_methods, r=Mark-Simulacrum
Avoid duplication of doc comments in `std::char` constants and functions For those consts and functions, only the summary is kept and a reference to the `char` associated const/method is included. Additionaly, re-exported functions have been converted to function definitions that call the previously re-exported function. This makes it easier to add a deprecated attribute to these functions in the future.
2 parents fd1889b + a8ff1ae commit a96cddb

File tree

3 files changed

+54
-203
lines changed

3 files changed

+54
-203
lines changed

‎library/core/src/char/convert.rs‎

Lines changed: 7 additions & 132 deletions
Original file line numberDiff line numberDiff line change
@@ -6,97 +6,22 @@ use crate::fmt;
66
use crate::mem::transmute;
77
use crate::str::FromStr;
88

9-
/// Converts a `u32` to a `char`.
10-
///
11-
/// Note that all [`char`]s are valid [`u32`]s, and can be cast to one with
12-
/// `as`:
13-
///
14-
/// ```
15-
/// let c = '💯';
16-
/// let i = c as u32;
17-
///
18-
/// assert_eq!(128175, i);
19-
/// ```
20-
///
21-
/// However, the reverse is not true: not all valid [`u32`]s are valid
22-
/// [`char`]s. `from_u32()` will return `None` if the input is not a valid value
23-
/// for a [`char`].
24-
///
25-
/// For an unsafe version of this function which ignores these checks, see
26-
/// [`from_u32_unchecked`].
27-
///
28-
/// # Examples
29-
///
30-
/// Basic usage:
31-
///
32-
/// ```
33-
/// use std::char;
34-
///
35-
/// let c = char::from_u32(0x2764);
36-
///
37-
/// assert_eq!(Some('❤'), c);
38-
/// ```
39-
///
40-
/// Returning `None` when the input is not a valid [`char`]:
41-
///
42-
/// ```
43-
/// use std::char;
44-
///
45-
/// let c = char::from_u32(0x110000);
46-
///
47-
/// assert_eq!(None, c);
48-
/// ```
49-
#[doc(alias = "chr")]
9+
/// Converts a `u32` to a `char`. See [`char::from_u32`].
5010
#[must_use]
5111
#[inline]
52-
#[stable(feature = "rust1", since = "1.0.0")]
53-
#[rustc_const_unstable(feature = "const_char_convert", issue = "89259")]
54-
pub const fn from_u32(i: u32) -> Option<char> {
12+
pub(super) const fn from_u32(i: u32) -> Option<char> {
5513
// FIXME: once Result::ok is const fn, use it here
5614
match char_try_from_u32(i) {
5715
Ok(c) => Some(c),
5816
Err(_) => None,
5917
}
6018
}
6119

62-
/// Converts a `u32` to a `char`, ignoring validity.
63-
///
64-
/// Note that all [`char`]s are valid [`u32`]s, and can be cast to one with
65-
/// `as`:
66-
///
67-
/// ```
68-
/// let c = '💯';
69-
/// let i = c as u32;
70-
///
71-
/// assert_eq!(128175, i);
72-
/// ```
73-
///
74-
/// However, the reverse is not true: not all valid [`u32`]s are valid
75-
/// [`char`]s. `from_u32_unchecked()` will ignore this, and blindly cast to
76-
/// [`char`], possibly creating an invalid one.
77-
///
78-
/// # Safety
79-
///
80-
/// This function is unsafe, as it may construct invalid `char` values.
81-
///
82-
/// For a safe version of this function, see the [`from_u32`] function.
83-
///
84-
/// # Examples
85-
///
86-
/// Basic usage:
87-
///
88-
/// ```
89-
/// use std::char;
90-
///
91-
/// let c = unsafe { char::from_u32_unchecked(0x2764) };
92-
///
93-
/// assert_eq!('❤', c);
94-
/// ```
20+
/// Converts a `u32` to a `char`, ignoring validity. See [`char::from_u32_unchecked`].
21+
#[rustc_const_unstable(feature = "const_char_convert", issue = "89259")]
9522
#[inline]
9623
#[must_use]
97-
#[stable(feature = "char_from_unchecked", since = "1.5.0")]
98-
#[rustc_const_unstable(feature = "const_char_convert", issue = "89259")]
99-
pub const unsafe fn from_u32_unchecked(i: u32) -> char {
24+
pub(super) const unsafe fn from_u32_unchecked(i: u32) -> char {
10025
// SAFETY: the caller must guarantee that `i` is a valid char value.
10126
if cfg!(debug_assertions) { char::from_u32(i).unwrap() } else { unsafe { transmute(i) } }
10227
}
@@ -317,60 +242,10 @@ impl fmt::Display for CharTryFromError {
317242
}
318243
}
319244

320-
/// Converts a digit in the given radix to a `char`.
321-
///
322-
/// A 'radix' here is sometimes also called a 'base'. A radix of two
323-
/// indicates a binary number, a radix of ten, decimal, and a radix of
324-
/// sixteen, hexadecimal, to give some common values. Arbitrary
325-
/// radices are supported.
326-
///
327-
/// `from_digit()` will return `None` if the input is not a digit in
328-
/// the given radix.
329-
///
330-
/// # Panics
331-
///
332-
/// Panics if given a radix larger than 36.
333-
///
334-
/// # Examples
335-
///
336-
/// Basic usage:
337-
///
338-
/// ```
339-
/// use std::char;
340-
///
341-
/// let c = char::from_digit(4, 10);
342-
///
343-
/// assert_eq!(Some('4'), c);
344-
///
345-
/// // Decimal 11 is a single digit in base 16
346-
/// let c = char::from_digit(11, 16);
347-
///
348-
/// assert_eq!(Some('b'), c);
349-
/// ```
350-
///
351-
/// Returning `None` when the input is not a digit:
352-
///
353-
/// ```
354-
/// use std::char;
355-
///
356-
/// let c = char::from_digit(20, 10);
357-
///
358-
/// assert_eq!(None, c);
359-
/// ```
360-
///
361-
/// Passing a large radix, causing a panic:
362-
///
363-
/// ```should_panic
364-
/// use std::char;
365-
///
366-
/// // this panics
367-
/// let c = char::from_digit(1, 37);
368-
/// ```
245+
/// Converts a digit in the given radix to a `char`. See [`char::from_digit`].
369246
#[inline]
370247
#[must_use]
371-
#[stable(feature = "rust1", since = "1.0.0")]
372-
#[rustc_const_unstable(feature = "const_char_convert", issue = "89259")]
373-
pub const fn from_digit(num: u32, radix: u32) -> Option<char> {
248+
pub(super) const fn from_digit(num: u32, radix: u32) -> Option<char> {
374249
if radix > 36 {
375250
panic!("from_digit: radix is too high (maximum 36)");
376251
}

‎library/core/src/char/decode.rs‎

Lines changed: 2 additions & 47 deletions
Original file line numberDiff line numberDiff line change
@@ -30,54 +30,9 @@ pub struct DecodeUtf16Error {
3030
}
3131

3232
/// Creates an iterator over the UTF-16 encoded code points in `iter`,
33-
/// returning unpaired surrogates as `Err`s.
34-
///
35-
/// # Examples
36-
///
37-
/// Basic usage:
38-
///
39-
/// ```
40-
/// use std::char::decode_utf16;
41-
///
42-
/// // 𝄞mus<invalid>ic<invalid>
43-
/// let v = [
44-
/// 0xD834, 0xDD1E, 0x006d, 0x0075, 0x0073, 0xDD1E, 0x0069, 0x0063, 0xD834,
45-
/// ];
46-
///
47-
/// assert_eq!(
48-
/// decode_utf16(v.iter().cloned())
49-
/// .map(|r| r.map_err(|e| e.unpaired_surrogate()))
50-
/// .collect::<Vec<_>>(),
51-
/// vec![
52-
/// Ok('𝄞'),
53-
/// Ok('m'), Ok('u'), Ok('s'),
54-
/// Err(0xDD1E),
55-
/// Ok('i'), Ok('c'),
56-
/// Err(0xD834)
57-
/// ]
58-
/// );
59-
/// ```
60-
///
61-
/// A lossy decoder can be obtained by replacing `Err` results with the replacement character:
62-
///
63-
/// ```
64-
/// use std::char::{decode_utf16, REPLACEMENT_CHARACTER};
65-
///
66-
/// // 𝄞mus<invalid>ic<invalid>
67-
/// let v = [
68-
/// 0xD834, 0xDD1E, 0x006d, 0x0075, 0x0073, 0xDD1E, 0x0069, 0x0063, 0xD834,
69-
/// ];
70-
///
71-
/// assert_eq!(
72-
/// decode_utf16(v.iter().cloned())
73-
/// .map(|r| r.unwrap_or(REPLACEMENT_CHARACTER))
74-
/// .collect::<String>(),
75-
/// "𝄞mus�ic�"
76-
/// );
77-
/// ```
78-
#[stable(feature = "decode_utf16", since = "1.9.0")]
33+
/// returning unpaired surrogates as `Err`s. See [`char::decode_utf16`].
7934
#[inline]
80-
pub fn decode_utf16<I: IntoIterator<Item = u16>>(iter: I) -> DecodeUtf16<I::IntoIter> {
35+
pub(super) fn decode_utf16<I: IntoIterator<Item = u16>>(iter: I) -> DecodeUtf16<I::IntoIter> {
8136
DecodeUtf16 { iter: iter.into_iter(), buf: None }
8237
}
8338

‎library/core/src/char/mod.rs‎

Lines changed: 45 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -23,18 +23,12 @@ mod decode;
2323
mod methods;
2424

2525
// stable re-exports
26-
#[stable(feature = "char_from_unchecked", since = "1.5.0")]
27-
pub use self::convert::from_u32_unchecked;
2826
#[stable(feature = "try_from", since = "1.34.0")]
2927
pub use self::convert::CharTryFromError;
3028
#[stable(feature = "char_from_str", since = "1.20.0")]
3129
pub use self::convert::ParseCharError;
32-
#[stable(feature = "rust1", since = "1.0.0")]
33-
pub use self::convert::{from_digit, from_u32};
3430
#[stable(feature = "decode_utf16", since = "1.9.0")]
35-
pub use self::decode::{decode_utf16, DecodeUtf16, DecodeUtf16Error};
36-
#[stable(feature = "unicode_version", since = "1.45.0")]
37-
pub use crate::unicode::UNICODE_VERSION;
31+
pub use self::decode::{DecodeUtf16, DecodeUtf16Error};
3832

3933
// perma-unstable re-exports
4034
#[unstable(feature = "char_internals", reason = "exposed only for libstd", issue = "none")]
@@ -89,30 +83,57 @@ const MAX_THREE_B: u32 = 0x10000;
8983
Cn Unassigned a reserved unassigned code point or a noncharacter
9084
*/
9185

92-
/// The highest valid code point a `char` can have, `'\u{10FFFF}'`.
93-
///
94-
/// # Examples
95-
///
96-
/// ```
97-
/// # fn something_which_returns_char() -> char { 'a' }
98-
/// let c: char = something_which_returns_char();
99-
/// assert!(c <= char::MAX);
100-
///
101-
/// let value_at_max = char::MAX as u32;
102-
/// assert_eq!(char::from_u32(value_at_max), Some('\u{10FFFF}'));
103-
/// assert_eq!(char::from_u32(value_at_max + 1), None);
104-
/// ```
86+
/// The highest valid code point a `char` can have, `'\u{10FFFF}'`. Use [`char::MAX`] instead.
10587
#[stable(feature = "rust1", since = "1.0.0")]
10688
pub const MAX: char = char::MAX;
10789

10890
/// `U+FFFD REPLACEMENT CHARACTER` (�) is used in Unicode to represent a
109-
/// decoding error.
110-
///
111-
/// It can occur, for example, when giving ill-formed UTF-8 bytes to
112-
/// [`String::from_utf8_lossy`](../../std/string/struct.String.html#method.from_utf8_lossy).
91+
/// decoding error. Use [`char::REPLACEMENT_CHARACTER`] instead.
11392
#[stable(feature = "decode_utf16", since = "1.9.0")]
11493
pub const REPLACEMENT_CHARACTER: char = char::REPLACEMENT_CHARACTER;
11594

95+
/// The version of [Unicode](https://www.unicode.org/) that the Unicode parts of
96+
/// `char` and `str` methods are based on. Use [`char::UNICODE_VERSION`] instead.
97+
#[stable(feature = "unicode_version", since = "1.45.0")]
98+
pub const UNICODE_VERSION: (u8, u8, u8) = char::UNICODE_VERSION;
99+
100+
/// Creates an iterator over the UTF-16 encoded code points in `iter`, returning
101+
/// unpaired surrogates as `Err`s. Use [`char::decode_utf16`] instead.
102+
#[stable(feature = "decode_utf16", since = "1.9.0")]
103+
#[inline]
104+
pub fn decode_utf16<I: IntoIterator<Item = u16>>(iter: I) -> DecodeUtf16<I::IntoIter> {
105+
self::decode::decode_utf16(iter)
106+
}
107+
108+
/// Converts a `u32` to a `char`. Use [`char::from_u32`] instead.
109+
#[stable(feature = "rust1", since = "1.0.0")]
110+
#[rustc_const_unstable(feature = "const_char_convert", issue = "89259")]
111+
#[must_use]
112+
#[inline]
113+
pub const fn from_u32(i: u32) -> Option<char> {
114+
self::convert::from_u32(i)
115+
}
116+
117+
/// Converts a `u32` to a `char`, ignoring validity. Use [`char::from_u32_unchecked`].
118+
/// instead.
119+
#[stable(feature = "char_from_unchecked", since = "1.5.0")]
120+
#[rustc_const_unstable(feature = "const_char_convert", issue = "89259")]
121+
#[must_use]
122+
#[inline]
123+
pub const unsafe fn from_u32_unchecked(i: u32) -> char {
124+
// SAFETY: the safety contract must be upheld by the caller.
125+
unsafe { self::convert::from_u32_unchecked(i) }
126+
}
127+
128+
/// Converts a digit in the given radix to a `char`. Use [`char::from_digit`] instead.
129+
#[stable(feature = "rust1", since = "1.0.0")]
130+
#[rustc_const_unstable(feature = "const_char_convert", issue = "89259")]
131+
#[must_use]
132+
#[inline]
133+
pub const fn from_digit(num: u32, radix: u32) -> Option<char> {
134+
self::convert::from_digit(num, radix)
135+
}
136+
116137
/// Returns an iterator that yields the hexadecimal Unicode escape of a
117138
/// character, as `char`s.
118139
///

0 commit comments

Comments
 (0)