core/char/methods.rs
1//! impl char {}
2
3use super::*;
4use crate::panic::const_panic;
5use crate::slice;
6use crate::str::from_utf8_unchecked_mut;
7use crate::ub_checks::assert_unsafe_precondition;
8use crate::unicode::printable::is_printable;
9use crate::unicode::{self, conversions};
10
11impl char {
12 /// The lowest valid code point a `char` can have, `'\0'`.
13 ///
14 /// Unlike integer types, `char` actually has a gap in the middle,
15 /// meaning that the range of possible `char`s is smaller than you
16 /// might expect. Ranges of `char` will automatically hop this gap
17 /// for you:
18 ///
19 /// ```
20 /// let dist = u32::from(char::MAX) - u32::from(char::MIN);
21 /// let size = (char::MIN..=char::MAX).count() as u32;
22 /// assert!(size < dist);
23 /// ```
24 ///
25 /// Despite this gap, the `MIN` and [`MAX`] values can be used as bounds for
26 /// all `char` values.
27 ///
28 /// [`MAX`]: char::MAX
29 ///
30 /// # Examples
31 ///
32 /// ```
33 /// # fn something_which_returns_char() -> char { 'a' }
34 /// let c: char = something_which_returns_char();
35 /// assert!(char::MIN <= c);
36 ///
37 /// let value_at_min = u32::from(char::MIN);
38 /// assert_eq!(char::from_u32(value_at_min), Some('\0'));
39 /// ```
40 #[stable(feature = "char_min", since = "1.83.0")]
41 pub const MIN: char = '\0';
42
43 /// The highest valid code point a `char` can have, `'\u{10FFFF}'`.
44 ///
45 /// Unlike integer types, `char` actually has a gap in the middle,
46 /// meaning that the range of possible `char`s is smaller than you
47 /// might expect. Ranges of `char` will automatically hop this gap
48 /// for you:
49 ///
50 /// ```
51 /// let dist = u32::from(char::MAX) - u32::from(char::MIN);
52 /// let size = (char::MIN..=char::MAX).count() as u32;
53 /// assert!(size < dist);
54 /// ```
55 ///
56 /// Despite this gap, the [`MIN`] and `MAX` values can be used as bounds for
57 /// all `char` values.
58 ///
59 /// [`MIN`]: char::MIN
60 ///
61 /// # Examples
62 ///
63 /// ```
64 /// # fn something_which_returns_char() -> char { 'a' }
65 /// let c: char = something_which_returns_char();
66 /// assert!(c <= char::MAX);
67 ///
68 /// let value_at_max = u32::from(char::MAX);
69 /// assert_eq!(char::from_u32(value_at_max), Some('\u{10FFFF}'));
70 /// assert_eq!(char::from_u32(value_at_max + 1), None);
71 /// ```
72 #[stable(feature = "assoc_char_consts", since = "1.52.0")]
73 pub const MAX: char = '\u{10FFFF}';
74
75 /// The maximum number of bytes required to [encode](char::encode_utf8) a `char` to
76 /// UTF-8 encoding.
77 #[unstable(feature = "char_max_len", issue = "121714")]
78 pub const MAX_LEN_UTF8: usize = 4;
79
80 /// The maximum number of two-byte units required to [encode](char::encode_utf16) a `char`
81 /// to UTF-16 encoding.
82 #[unstable(feature = "char_max_len", issue = "121714")]
83 pub const MAX_LEN_UTF16: usize = 2;
84
85 /// `U+FFFD REPLACEMENT CHARACTER` (�) is used in Unicode to represent a
86 /// decoding error.
87 ///
88 /// It can occur, for example, when giving ill-formed UTF-8 bytes to
89 /// [`String::from_utf8_lossy`](../std/string/struct.String.html#method.from_utf8_lossy).
90 #[stable(feature = "assoc_char_consts", since = "1.52.0")]
91 pub const REPLACEMENT_CHARACTER: char = '\u{FFFD}';
92
93 /// The version of [Unicode](https://www.unicode.org/) that the Unicode parts of
94 /// `char` and `str` methods are based on.
95 ///
96 /// New versions of Unicode are released regularly and subsequently all methods
97 /// in the standard library depending on Unicode are updated. Therefore the
98 /// behavior of some `char` and `str` methods and the value of this constant
99 /// changes over time. This is *not* considered to be a breaking change.
100 ///
101 /// The version numbering scheme is explained in
102 /// [Unicode 11.0 or later, Section 3.1 Versions of the Unicode Standard](https://www.unicode.org/versions/Unicode11.0.0/ch03.pdf#page=4).
103 #[stable(feature = "assoc_char_consts", since = "1.52.0")]
104 pub const UNICODE_VERSION: (u8, u8, u8) = crate::unicode::UNICODE_VERSION;
105
106 /// Creates an iterator over the native endian UTF-16 encoded code points in `iter`,
107 /// returning unpaired surrogates as `Err`s.
108 ///
109 /// # Examples
110 ///
111 /// Basic usage:
112 ///
113 /// ```
114 /// // 𝄞mus<invalid>ic<invalid>
115 /// let v = [
116 /// 0xD834, 0xDD1E, 0x006d, 0x0075, 0x0073, 0xDD1E, 0x0069, 0x0063, 0xD834,
117 /// ];
118 ///
119 /// assert_eq!(
120 /// char::decode_utf16(v)
121 /// .map(|r| r.map_err(|e| e.unpaired_surrogate()))
122 /// .collect::<Vec<_>>(),
123 /// vec![
124 /// Ok('𝄞'),
125 /// Ok('m'), Ok('u'), Ok('s'),
126 /// Err(0xDD1E),
127 /// Ok('i'), Ok('c'),
128 /// Err(0xD834)
129 /// ]
130 /// );
131 /// ```
132 ///
133 /// A lossy decoder can be obtained by replacing `Err` results with the replacement character:
134 ///
135 /// ```
136 /// // 𝄞mus<invalid>ic<invalid>
137 /// let v = [
138 /// 0xD834, 0xDD1E, 0x006d, 0x0075, 0x0073, 0xDD1E, 0x0069, 0x0063, 0xD834,
139 /// ];
140 ///
141 /// assert_eq!(
142 /// char::decode_utf16(v)
143 /// .map(|r| r.unwrap_or(char::REPLACEMENT_CHARACTER))
144 /// .collect::<String>(),
145 /// "𝄞mus�ic�"
146 /// );
147 /// ```
148 #[stable(feature = "assoc_char_funcs", since = "1.52.0")]
149 #[inline]
150 pub fn decode_utf16<I: IntoIterator<Item = u16>>(iter: I) -> DecodeUtf16<I::IntoIter> {
151 super::decode::decode_utf16(iter)
152 }
153
154 /// Converts a `u32` to a `char`.
155 ///
156 /// Note that all `char`s are valid [`u32`]s, and can be cast to one with
157 /// [`as`](../std/keyword.as.html):
158 ///
159 /// ```
160 /// let c = '💯';
161 /// let i = c as u32;
162 ///
163 /// assert_eq!(128175, i);
164 /// ```
165 ///
166 /// However, the reverse is not true: not all valid [`u32`]s are valid
167 /// `char`s. `from_u32()` will return `None` if the input is not a valid value
168 /// for a `char`.
169 ///
170 /// For an unsafe version of this function which ignores these checks, see
171 /// [`from_u32_unchecked`].
172 ///
173 /// [`from_u32_unchecked`]: #method.from_u32_unchecked
174 ///
175 /// # Examples
176 ///
177 /// Basic usage:
178 ///
179 /// ```
180 /// let c = char::from_u32(0x2764);
181 ///
182 /// assert_eq!(Some('❤'), c);
183 /// ```
184 ///
185 /// Returning `None` when the input is not a valid `char`:
186 ///
187 /// ```
188 /// let c = char::from_u32(0x110000);
189 ///
190 /// assert_eq!(None, c);
191 /// ```
192 #[stable(feature = "assoc_char_funcs", since = "1.52.0")]
193 #[rustc_const_stable(feature = "const_char_convert", since = "1.67.0")]
194 #[must_use]
195 #[inline]
196 pub const fn from_u32(i: u32) -> Option<char> {
197 super::convert::from_u32(i)
198 }
199
200 /// Converts a `u32` to a `char`, ignoring validity.
201 ///
202 /// Note that all `char`s are valid [`u32`]s, and can be cast to one with
203 /// `as`:
204 ///
205 /// ```
206 /// let c = '💯';
207 /// let i = c as u32;
208 ///
209 /// assert_eq!(128175, i);
210 /// ```
211 ///
212 /// However, the reverse is not true: not all valid [`u32`]s are valid
213 /// `char`s. `from_u32_unchecked()` will ignore this, and blindly cast to
214 /// `char`, possibly creating an invalid one.
215 ///
216 /// # Safety
217 ///
218 /// This function is unsafe, as it may construct invalid `char` values.
219 ///
220 /// For a safe version of this function, see the [`from_u32`] function.
221 ///
222 /// [`from_u32`]: #method.from_u32
223 ///
224 /// # Examples
225 ///
226 /// Basic usage:
227 ///
228 /// ```
229 /// let c = unsafe { char::from_u32_unchecked(0x2764) };
230 ///
231 /// assert_eq!('❤', c);
232 /// ```
233 #[stable(feature = "assoc_char_funcs", since = "1.52.0")]
234 #[rustc_const_stable(feature = "const_char_from_u32_unchecked", since = "1.81.0")]
235 #[must_use]
236 #[inline]
237 pub const unsafe fn from_u32_unchecked(i: u32) -> char {
238 // SAFETY: the safety contract must be upheld by the caller.
239 unsafe { super::convert::from_u32_unchecked(i) }
240 }
241
242 /// Converts a digit in the given radix to a `char`.
243 ///
244 /// A 'radix' here is sometimes also called a 'base'. A radix of two
245 /// indicates a binary number, a radix of ten, decimal, and a radix of
246 /// sixteen, hexadecimal, to give some common values. Arbitrary
247 /// radices are supported.
248 ///
249 /// `from_digit()` will return `None` if the input is not a digit in
250 /// the given radix.
251 ///
252 /// # Panics
253 ///
254 /// Panics if given a radix larger than 36.
255 ///
256 /// # Examples
257 ///
258 /// Basic usage:
259 ///
260 /// ```
261 /// let c = char::from_digit(4, 10);
262 ///
263 /// assert_eq!(Some('4'), c);
264 ///
265 /// // Decimal 11 is a single digit in base 16
266 /// let c = char::from_digit(11, 16);
267 ///
268 /// assert_eq!(Some('b'), c);
269 /// ```
270 ///
271 /// Returning `None` when the input is not a digit:
272 ///
273 /// ```
274 /// let c = char::from_digit(20, 10);
275 ///
276 /// assert_eq!(None, c);
277 /// ```
278 ///
279 /// Passing a large radix, causing a panic:
280 ///
281 /// ```should_panic
282 /// // this panics
283 /// let _c = char::from_digit(1, 37);
284 /// ```
285 #[stable(feature = "assoc_char_funcs", since = "1.52.0")]
286 #[rustc_const_stable(feature = "const_char_convert", since = "1.67.0")]
287 #[must_use]
288 #[inline]
289 pub const fn from_digit(num: u32, radix: u32) -> Option<char> {
290 super::convert::from_digit(num, radix)
291 }
292
293 /// Checks if a `char` is a digit in the given radix.
294 ///
295 /// A 'radix' here is sometimes also called a 'base'. A radix of two
296 /// indicates a binary number, a radix of ten, decimal, and a radix of
297 /// sixteen, hexadecimal, to give some common values. Arbitrary
298 /// radices are supported.
299 ///
300 /// Compared to [`is_numeric()`], this function only recognizes the characters
301 /// `0-9`, `a-z` and `A-Z`.
302 ///
303 /// 'Digit' is defined to be only the following characters:
304 ///
305 /// * `0-9`
306 /// * `a-z`
307 /// * `A-Z`
308 ///
309 /// For a more comprehensive understanding of 'digit', see [`is_numeric()`].
310 ///
311 /// [`is_numeric()`]: #method.is_numeric
312 ///
313 /// # Panics
314 ///
315 /// Panics if given a radix smaller than 2 or larger than 36.
316 ///
317 /// # Examples
318 ///
319 /// Basic usage:
320 ///
321 /// ```
322 /// assert!('1'.is_digit(10));
323 /// assert!('f'.is_digit(16));
324 /// assert!(!'f'.is_digit(10));
325 /// ```
326 ///
327 /// Passing a large radix, causing a panic:
328 ///
329 /// ```should_panic
330 /// // this panics
331 /// '1'.is_digit(37);
332 /// ```
333 ///
334 /// Passing a small radix, causing a panic:
335 ///
336 /// ```should_panic
337 /// // this panics
338 /// '1'.is_digit(1);
339 /// ```
340 #[stable(feature = "rust1", since = "1.0.0")]
341 #[rustc_const_stable(feature = "const_char_classify", since = "1.87.0")]
342 #[inline]
343 pub const fn is_digit(self, radix: u32) -> bool {
344 self.to_digit(radix).is_some()
345 }
346
347 /// Converts a `char` to a digit in the given radix.
348 ///
349 /// A 'radix' here is sometimes also called a 'base'. A radix of two
350 /// indicates a binary number, a radix of ten, decimal, and a radix of
351 /// sixteen, hexadecimal, to give some common values. Arbitrary
352 /// radices are supported.
353 ///
354 /// 'Digit' is defined to be only the following characters:
355 ///
356 /// * `0-9`
357 /// * `a-z`
358 /// * `A-Z`
359 ///
360 /// # Errors
361 ///
362 /// Returns `None` if the `char` does not refer to a digit in the given radix.
363 ///
364 /// # Panics
365 ///
366 /// Panics if given a radix smaller than 2 or larger than 36.
367 ///
368 /// # Examples
369 ///
370 /// Basic usage:
371 ///
372 /// ```
373 /// assert_eq!('1'.to_digit(10), Some(1));
374 /// assert_eq!('f'.to_digit(16), Some(15));
375 /// ```
376 ///
377 /// Passing a non-digit results in failure:
378 ///
379 /// ```
380 /// assert_eq!('f'.to_digit(10), None);
381 /// assert_eq!('z'.to_digit(16), None);
382 /// ```
383 ///
384 /// Passing a large radix, causing a panic:
385 ///
386 /// ```should_panic
387 /// // this panics
388 /// let _ = '1'.to_digit(37);
389 /// ```
390 /// Passing a small radix, causing a panic:
391 ///
392 /// ```should_panic
393 /// // this panics
394 /// let _ = '1'.to_digit(1);
395 /// ```
396 #[stable(feature = "rust1", since = "1.0.0")]
397 #[rustc_const_stable(feature = "const_char_convert", since = "1.67.0")]
398 #[rustc_diagnostic_item = "char_to_digit"]
399 #[must_use = "this returns the result of the operation, \
400 without modifying the original"]
401 #[inline]
402 pub const fn to_digit(self, radix: u32) -> Option<u32> {
403 assert!(
404 radix >= 2 && radix <= 36,
405 "to_digit: invalid radix -- radix must be in the range 2 to 36 inclusive"
406 );
407 // check radix to remove letter handling code when radix is a known constant
408 let value = if self > '9' && radix > 10 {
409 // mask to convert ASCII letters to uppercase
410 const TO_UPPERCASE_MASK: u32 = !0b0010_0000;
411 // Converts an ASCII letter to its corresponding integer value:
412 // A-Z => 10-35, a-z => 10-35. Other characters produce values >= 36.
413 //
414 // Add Overflow Safety:
415 // By applying the mask after the subtraction, the first addendum is
416 // constrained such that it never exceeds u32::MAX - 0x20.
417 ((self as u32).wrapping_sub('A' as u32) & TO_UPPERCASE_MASK) + 10
418 } else {
419 // convert digit to value, non-digits wrap to values > 36
420 (self as u32).wrapping_sub('0' as u32)
421 };
422 // FIXME(const-hack): once then_some is const fn, use it here
423 if value < radix { Some(value) } else { None }
424 }
425
426 /// Returns an iterator that yields the hexadecimal Unicode escape of a
427 /// character as `char`s.
428 ///
429 /// This will escape characters with the Rust syntax of the form
430 /// `\u{NNNNNN}` where `NNNNNN` is a hexadecimal representation.
431 ///
432 /// # Examples
433 ///
434 /// As an iterator:
435 ///
436 /// ```
437 /// for c in '❤'.escape_unicode() {
438 /// print!("{c}");
439 /// }
440 /// println!();
441 /// ```
442 ///
443 /// Using `println!` directly:
444 ///
445 /// ```
446 /// println!("{}", '❤'.escape_unicode());
447 /// ```
448 ///
449 /// Both are equivalent to:
450 ///
451 /// ```
452 /// println!("\\u{{2764}}");
453 /// ```
454 ///
455 /// Using [`to_string`](../std/string/trait.ToString.html#tymethod.to_string):
456 ///
457 /// ```
458 /// assert_eq!('❤'.escape_unicode().to_string(), "\\u{2764}");
459 /// ```
460 #[must_use = "this returns the escaped char as an iterator, \
461 without modifying the original"]
462 #[stable(feature = "rust1", since = "1.0.0")]
463 #[inline]
464 pub fn escape_unicode(self) -> EscapeUnicode {
465 EscapeUnicode::new(self)
466 }
467
468 /// An extended version of `escape_debug` that optionally permits escaping
469 /// Extended Grapheme codepoints, single quotes, and double quotes. This
470 /// allows us to format characters like nonspacing marks better when they're
471 /// at the start of a string, and allows escaping single quotes in
472 /// characters, and double quotes in strings.
473 #[inline]
474 pub(crate) fn escape_debug_ext(self, args: EscapeDebugExtArgs) -> EscapeDebug {
475 match self {
476 '\0' => EscapeDebug::backslash(ascii::Char::Digit0),
477 '\t' => EscapeDebug::backslash(ascii::Char::SmallT),
478 '\r' => EscapeDebug::backslash(ascii::Char::SmallR),
479 '\n' => EscapeDebug::backslash(ascii::Char::SmallN),
480 '\\' => EscapeDebug::backslash(ascii::Char::ReverseSolidus),
481 '\"' if args.escape_double_quote => EscapeDebug::backslash(ascii::Char::QuotationMark),
482 '\'' if args.escape_single_quote => EscapeDebug::backslash(ascii::Char::Apostrophe),
483 _ if args.escape_grapheme_extended && self.is_grapheme_extended() => {
484 EscapeDebug::unicode(self)
485 }
486 _ if is_printable(self) => EscapeDebug::printable(self),
487 _ => EscapeDebug::unicode(self),
488 }
489 }
490
491 /// Returns an iterator that yields the literal escape code of a character
492 /// as `char`s.
493 ///
494 /// This will escape the characters similar to the [`Debug`](core::fmt::Debug) implementations
495 /// of `str` or `char`.
496 ///
497 /// # Examples
498 ///
499 /// As an iterator:
500 ///
501 /// ```
502 /// for c in '\n'.escape_debug() {
503 /// print!("{c}");
504 /// }
505 /// println!();
506 /// ```
507 ///
508 /// Using `println!` directly:
509 ///
510 /// ```
511 /// println!("{}", '\n'.escape_debug());
512 /// ```
513 ///
514 /// Both are equivalent to:
515 ///
516 /// ```
517 /// println!("\\n");
518 /// ```
519 ///
520 /// Using [`to_string`](../std/string/trait.ToString.html#tymethod.to_string):
521 ///
522 /// ```
523 /// assert_eq!('\n'.escape_debug().to_string(), "\\n");
524 /// ```
525 #[must_use = "this returns the escaped char as an iterator, \
526 without modifying the original"]
527 #[stable(feature = "char_escape_debug", since = "1.20.0")]
528 #[inline]
529 pub fn escape_debug(self) -> EscapeDebug {
530 self.escape_debug_ext(EscapeDebugExtArgs::ESCAPE_ALL)
531 }
532
533 /// Returns an iterator that yields the literal escape code of a character
534 /// as `char`s.
535 ///
536 /// The default is chosen with a bias toward producing literals that are
537 /// legal in a variety of languages, including C++11 and similar C-family
538 /// languages. The exact rules are:
539 ///
540 /// * Tab is escaped as `\t`.
541 /// * Carriage return is escaped as `\r`.
542 /// * Line feed is escaped as `\n`.
543 /// * Single quote is escaped as `\'`.
544 /// * Double quote is escaped as `\"`.
545 /// * Backslash is escaped as `\\`.
546 /// * Any character in the 'printable ASCII' range `0x20` .. `0x7e`
547 /// inclusive is not escaped.
548 /// * All other characters are given hexadecimal Unicode escapes; see
549 /// [`escape_unicode`].
550 ///
551 /// [`escape_unicode`]: #method.escape_unicode
552 ///
553 /// # Examples
554 ///
555 /// As an iterator:
556 ///
557 /// ```
558 /// for c in '"'.escape_default() {
559 /// print!("{c}");
560 /// }
561 /// println!();
562 /// ```
563 ///
564 /// Using `println!` directly:
565 ///
566 /// ```
567 /// println!("{}", '"'.escape_default());
568 /// ```
569 ///
570 /// Both are equivalent to:
571 ///
572 /// ```
573 /// println!("\\\"");
574 /// ```
575 ///
576 /// Using [`to_string`](../std/string/trait.ToString.html#tymethod.to_string):
577 ///
578 /// ```
579 /// assert_eq!('"'.escape_default().to_string(), "\\\"");
580 /// ```
581 #[must_use = "this returns the escaped char as an iterator, \
582 without modifying the original"]
583 #[stable(feature = "rust1", since = "1.0.0")]
584 #[inline]
585 pub fn escape_default(self) -> EscapeDefault {
586 match self {
587 '\t' => EscapeDefault::backslash(ascii::Char::SmallT),
588 '\r' => EscapeDefault::backslash(ascii::Char::SmallR),
589 '\n' => EscapeDefault::backslash(ascii::Char::SmallN),
590 '\\' | '\'' | '\"' => EscapeDefault::backslash(self.as_ascii().unwrap()),
591 '\x20'..='\x7e' => EscapeDefault::printable(self.as_ascii().unwrap()),
592 _ => EscapeDefault::unicode(self),
593 }
594 }
595
596 /// Returns the number of bytes this `char` would need if encoded in UTF-8.
597 ///
598 /// That number of bytes is always between 1 and 4, inclusive.
599 ///
600 /// # Examples
601 ///
602 /// Basic usage:
603 ///
604 /// ```
605 /// let len = 'A'.len_utf8();
606 /// assert_eq!(len, 1);
607 ///
608 /// let len = 'ß'.len_utf8();
609 /// assert_eq!(len, 2);
610 ///
611 /// let len = 'ℝ'.len_utf8();
612 /// assert_eq!(len, 3);
613 ///
614 /// let len = '💣'.len_utf8();
615 /// assert_eq!(len, 4);
616 /// ```
617 ///
618 /// The `&str` type guarantees that its contents are UTF-8, and so we can compare the length it
619 /// would take if each code point was represented as a `char` vs in the `&str` itself:
620 ///
621 /// ```
622 /// // as chars
623 /// let eastern = '東';
624 /// let capital = '京';
625 ///
626 /// // both can be represented as three bytes
627 /// assert_eq!(3, eastern.len_utf8());
628 /// assert_eq!(3, capital.len_utf8());
629 ///
630 /// // as a &str, these two are encoded in UTF-8
631 /// let tokyo = "東京";
632 ///
633 /// let len = eastern.len_utf8() + capital.len_utf8();
634 ///
635 /// // we can see that they take six bytes total...
636 /// assert_eq!(6, tokyo.len());
637 ///
638 /// // ... just like the &str
639 /// assert_eq!(len, tokyo.len());
640 /// ```
641 #[stable(feature = "rust1", since = "1.0.0")]
642 #[rustc_const_stable(feature = "const_char_len_utf", since = "1.52.0")]
643 #[inline]
644 #[must_use]
645 pub const fn len_utf8(self) -> usize {
646 len_utf8(self as u32)
647 }
648
649 /// Returns the number of 16-bit code units this `char` would need if
650 /// encoded in UTF-16.
651 ///
652 /// That number of code units is always either 1 or 2, for unicode scalar values in
653 /// the [basic multilingual plane] or [supplementary planes] respectively.
654 ///
655 /// See the documentation for [`len_utf8()`] for more explanation of this
656 /// concept. This function is a mirror, but for UTF-16 instead of UTF-8.
657 ///
658 /// [basic multilingual plane]: http://www.unicode.org/glossary/#basic_multilingual_plane
659 /// [supplementary planes]: http://www.unicode.org/glossary/#supplementary_planes
660 /// [`len_utf8()`]: #method.len_utf8
661 ///
662 /// # Examples
663 ///
664 /// Basic usage:
665 ///
666 /// ```
667 /// let n = 'ß'.len_utf16();
668 /// assert_eq!(n, 1);
669 ///
670 /// let len = '💣'.len_utf16();
671 /// assert_eq!(len, 2);
672 /// ```
673 #[stable(feature = "rust1", since = "1.0.0")]
674 #[rustc_const_stable(feature = "const_char_len_utf", since = "1.52.0")]
675 #[inline]
676 #[must_use]
677 pub const fn len_utf16(self) -> usize {
678 len_utf16(self as u32)
679 }
680
681 /// Encodes this character as UTF-8 into the provided byte buffer,
682 /// and then returns the subslice of the buffer that contains the encoded character.
683 ///
684 /// # Panics
685 ///
686 /// Panics if the buffer is not large enough.
687 /// A buffer of length four is large enough to encode any `char`.
688 ///
689 /// # Examples
690 ///
691 /// In both of these examples, 'ß' takes two bytes to encode.
692 ///
693 /// ```
694 /// let mut b = [0; 2];
695 ///
696 /// let result = 'ß'.encode_utf8(&mut b);
697 ///
698 /// assert_eq!(result, "ß");
699 ///
700 /// assert_eq!(result.len(), 2);
701 /// ```
702 ///
703 /// A buffer that's too small:
704 ///
705 /// ```should_panic
706 /// let mut b = [0; 1];
707 ///
708 /// // this panics
709 /// 'ß'.encode_utf8(&mut b);
710 /// ```
711 #[stable(feature = "unicode_encode_char", since = "1.15.0")]
712 #[rustc_const_stable(feature = "const_char_encode_utf8", since = "1.83.0")]
713 #[inline]
714 pub const fn encode_utf8(self, dst: &mut [u8]) -> &mut str {
715 // SAFETY: `char` is not a surrogate, so this is valid UTF-8.
716 unsafe { from_utf8_unchecked_mut(encode_utf8_raw(self as u32, dst)) }
717 }
718
719 /// Encodes this character as native endian UTF-16 into the provided `u16` buffer,
720 /// and then returns the subslice of the buffer that contains the encoded character.
721 ///
722 /// # Panics
723 ///
724 /// Panics if the buffer is not large enough.
725 /// A buffer of length 2 is large enough to encode any `char`.
726 ///
727 /// # Examples
728 ///
729 /// In both of these examples, '𝕊' takes two `u16`s to encode.
730 ///
731 /// ```
732 /// let mut b = [0; 2];
733 ///
734 /// let result = '𝕊'.encode_utf16(&mut b);
735 ///
736 /// assert_eq!(result.len(), 2);
737 /// ```
738 ///
739 /// A buffer that's too small:
740 ///
741 /// ```should_panic
742 /// let mut b = [0; 1];
743 ///
744 /// // this panics
745 /// '𝕊'.encode_utf16(&mut b);
746 /// ```
747 #[stable(feature = "unicode_encode_char", since = "1.15.0")]
748 #[rustc_const_stable(feature = "const_char_encode_utf16", since = "1.84.0")]
749 #[inline]
750 pub const fn encode_utf16(self, dst: &mut [u16]) -> &mut [u16] {
751 encode_utf16_raw(self as u32, dst)
752 }
753
754 /// Returns `true` if this `char` has the `Alphabetic` property.
755 ///
756 /// `Alphabetic` is described in Chapter 4 (Character Properties) of the [Unicode Standard] and
757 /// specified in the [Unicode Character Database][ucd] [`DerivedCoreProperties.txt`].
758 ///
759 /// [Unicode Standard]: https://www.unicode.org/versions/latest/
760 /// [ucd]: https://www.unicode.org/reports/tr44/
761 /// [`DerivedCoreProperties.txt`]: https://www.unicode.org/Public/UCD/latest/ucd/DerivedCoreProperties.txt
762 ///
763 /// # Examples
764 ///
765 /// Basic usage:
766 ///
767 /// ```
768 /// assert!('a'.is_alphabetic());
769 /// assert!('京'.is_alphabetic());
770 ///
771 /// let c = '💝';
772 /// // love is many things, but it is not alphabetic
773 /// assert!(!c.is_alphabetic());
774 /// ```
775 #[must_use]
776 #[stable(feature = "rust1", since = "1.0.0")]
777 #[inline]
778 pub fn is_alphabetic(self) -> bool {
779 match self {
780 'a'..='z' | 'A'..='Z' => true,
781 c => c > '\x7f' && unicode::Alphabetic(c),
782 }
783 }
784
785 /// Returns `true` if this `char` has the `Lowercase` property.
786 ///
787 /// `Lowercase` is described in Chapter 4 (Character Properties) of the [Unicode Standard] and
788 /// specified in the [Unicode Character Database][ucd] [`DerivedCoreProperties.txt`].
789 ///
790 /// [Unicode Standard]: https://www.unicode.org/versions/latest/
791 /// [ucd]: https://www.unicode.org/reports/tr44/
792 /// [`DerivedCoreProperties.txt`]: https://www.unicode.org/Public/UCD/latest/ucd/DerivedCoreProperties.txt
793 ///
794 /// # Examples
795 ///
796 /// Basic usage:
797 ///
798 /// ```
799 /// assert!('a'.is_lowercase());
800 /// assert!('δ'.is_lowercase());
801 /// assert!(!'A'.is_lowercase());
802 /// assert!(!'Δ'.is_lowercase());
803 ///
804 /// // The various Chinese scripts and punctuation do not have case, and so:
805 /// assert!(!'中'.is_lowercase());
806 /// assert!(!' '.is_lowercase());
807 /// ```
808 ///
809 /// In a const context:
810 ///
811 /// ```
812 /// const CAPITAL_DELTA_IS_LOWERCASE: bool = 'Δ'.is_lowercase();
813 /// assert!(!CAPITAL_DELTA_IS_LOWERCASE);
814 /// ```
815 #[must_use]
816 #[stable(feature = "rust1", since = "1.0.0")]
817 #[rustc_const_stable(feature = "const_unicode_case_lookup", since = "1.84.0")]
818 #[inline]
819 pub const fn is_lowercase(self) -> bool {
820 match self {
821 'a'..='z' => true,
822 c => c > '\x7f' && unicode::Lowercase(c),
823 }
824 }
825
826 /// Returns `true` if this `char` has the `Uppercase` property.
827 ///
828 /// `Uppercase` is described in Chapter 4 (Character Properties) of the [Unicode Standard] and
829 /// specified in the [Unicode Character Database][ucd] [`DerivedCoreProperties.txt`].
830 ///
831 /// [Unicode Standard]: https://www.unicode.org/versions/latest/
832 /// [ucd]: https://www.unicode.org/reports/tr44/
833 /// [`DerivedCoreProperties.txt`]: https://www.unicode.org/Public/UCD/latest/ucd/DerivedCoreProperties.txt
834 ///
835 /// # Examples
836 ///
837 /// Basic usage:
838 ///
839 /// ```
840 /// assert!(!'a'.is_uppercase());
841 /// assert!(!'δ'.is_uppercase());
842 /// assert!('A'.is_uppercase());
843 /// assert!('Δ'.is_uppercase());
844 ///
845 /// // The various Chinese scripts and punctuation do not have case, and so:
846 /// assert!(!'中'.is_uppercase());
847 /// assert!(!' '.is_uppercase());
848 /// ```
849 ///
850 /// In a const context:
851 ///
852 /// ```
853 /// const CAPITAL_DELTA_IS_UPPERCASE: bool = 'Δ'.is_uppercase();
854 /// assert!(CAPITAL_DELTA_IS_UPPERCASE);
855 /// ```
856 #[must_use]
857 #[stable(feature = "rust1", since = "1.0.0")]
858 #[rustc_const_stable(feature = "const_unicode_case_lookup", since = "1.84.0")]
859 #[inline]
860 pub const fn is_uppercase(self) -> bool {
861 match self {
862 'A'..='Z' => true,
863 c => c > '\x7f' && unicode::Uppercase(c),
864 }
865 }
866
867 /// Returns `true` if this `char` has the `White_Space` property.
868 ///
869 /// `White_Space` is specified in the [Unicode Character Database][ucd] [`PropList.txt`].
870 ///
871 /// [ucd]: https://www.unicode.org/reports/tr44/
872 /// [`PropList.txt`]: https://www.unicode.org/Public/UCD/latest/ucd/PropList.txt
873 ///
874 /// # Examples
875 ///
876 /// Basic usage:
877 ///
878 /// ```
879 /// assert!(' '.is_whitespace());
880 ///
881 /// // line break
882 /// assert!('\n'.is_whitespace());
883 ///
884 /// // a non-breaking space
885 /// assert!('\u{A0}'.is_whitespace());
886 ///
887 /// assert!(!'越'.is_whitespace());
888 /// ```
889 #[must_use]
890 #[stable(feature = "rust1", since = "1.0.0")]
891 #[rustc_const_stable(feature = "const_char_classify", since = "1.87.0")]
892 #[inline]
893 pub const fn is_whitespace(self) -> bool {
894 match self {
895 ' ' | '\x09'..='\x0d' => true,
896 c => c > '\x7f' && unicode::White_Space(c),
897 }
898 }
899
900 /// Returns `true` if this `char` satisfies either [`is_alphabetic()`] or [`is_numeric()`].
901 ///
902 /// [`is_alphabetic()`]: #method.is_alphabetic
903 /// [`is_numeric()`]: #method.is_numeric
904 ///
905 /// # Examples
906 ///
907 /// Basic usage:
908 ///
909 /// ```
910 /// assert!('٣'.is_alphanumeric());
911 /// assert!('7'.is_alphanumeric());
912 /// assert!('৬'.is_alphanumeric());
913 /// assert!('¾'.is_alphanumeric());
914 /// assert!('①'.is_alphanumeric());
915 /// assert!('K'.is_alphanumeric());
916 /// assert!('و'.is_alphanumeric());
917 /// assert!('藏'.is_alphanumeric());
918 /// ```
919 #[must_use]
920 #[stable(feature = "rust1", since = "1.0.0")]
921 #[inline]
922 pub fn is_alphanumeric(self) -> bool {
923 if self.is_ascii() {
924 self.is_ascii_alphanumeric()
925 } else {
926 unicode::Alphabetic(self) || unicode::N(self)
927 }
928 }
929
930 /// Returns `true` if this `char` has the general category for control codes.
931 ///
932 /// Control codes (code points with the general category of `Cc`) are described in Chapter 4
933 /// (Character Properties) of the [Unicode Standard] and specified in the [Unicode Character
934 /// Database][ucd] [`UnicodeData.txt`].
935 ///
936 /// [Unicode Standard]: https://www.unicode.org/versions/latest/
937 /// [ucd]: https://www.unicode.org/reports/tr44/
938 /// [`UnicodeData.txt`]: https://www.unicode.org/Public/UCD/latest/ucd/UnicodeData.txt
939 ///
940 /// # Examples
941 ///
942 /// Basic usage:
943 ///
944 /// ```
945 /// // U+009C, STRING TERMINATOR
946 /// assert!(''.is_control());
947 /// assert!(!'q'.is_control());
948 /// ```
949 #[must_use]
950 #[stable(feature = "rust1", since = "1.0.0")]
951 #[inline]
952 pub fn is_control(self) -> bool {
953 // According to
954 // https://www.unicode.org/policies/stability_policy.html#Property_Value,
955 // the set of codepoints in `Cc` will never change.
956 // So we can just hard-code the patterns to match against instead of using a table.
957 matches!(self, '\0'..='\x1f' | '\x7f'..='\u{9f}')
958 }
959
960 /// Returns `true` if this `char` has the `Grapheme_Extend` property.
961 ///
962 /// `Grapheme_Extend` is described in [Unicode Standard Annex #29 (Unicode Text
963 /// Segmentation)][uax29] and specified in the [Unicode Character Database][ucd]
964 /// [`DerivedCoreProperties.txt`].
965 ///
966 /// [uax29]: https://www.unicode.org/reports/tr29/
967 /// [ucd]: https://www.unicode.org/reports/tr44/
968 /// [`DerivedCoreProperties.txt`]: https://www.unicode.org/Public/UCD/latest/ucd/DerivedCoreProperties.txt
969 #[must_use]
970 #[inline]
971 pub(crate) fn is_grapheme_extended(self) -> bool {
972 unicode::Grapheme_Extend(self)
973 }
974
975 /// Returns `true` if this `char` has one of the general categories for numbers.
976 ///
977 /// The general categories for numbers (`Nd` for decimal digits, `Nl` for letter-like numeric
978 /// characters, and `No` for other numeric characters) are specified in the [Unicode Character
979 /// Database][ucd] [`UnicodeData.txt`].
980 ///
981 /// This method doesn't cover everything that could be considered a number, e.g. ideographic numbers like '三'.
982 /// If you want everything including characters with overlapping purposes then you might want to use
983 /// a unicode or language-processing library that exposes the appropriate character properties instead
984 /// of looking at the unicode categories.
985 ///
986 /// If you want to parse ASCII decimal digits (0-9) or ASCII base-N, use
987 /// `is_ascii_digit` or `is_digit` instead.
988 ///
989 /// [Unicode Standard]: https://www.unicode.org/versions/latest/
990 /// [ucd]: https://www.unicode.org/reports/tr44/
991 /// [`UnicodeData.txt`]: https://www.unicode.org/Public/UCD/latest/ucd/UnicodeData.txt
992 ///
993 /// # Examples
994 ///
995 /// Basic usage:
996 ///
997 /// ```
998 /// assert!('٣'.is_numeric());
999 /// assert!('7'.is_numeric());
1000 /// assert!('৬'.is_numeric());
1001 /// assert!('¾'.is_numeric());
1002 /// assert!('①'.is_numeric());
1003 /// assert!(!'K'.is_numeric());
1004 /// assert!(!'و'.is_numeric());
1005 /// assert!(!'藏'.is_numeric());
1006 /// assert!(!'三'.is_numeric());
1007 /// ```
1008 #[must_use]
1009 #[stable(feature = "rust1", since = "1.0.0")]
1010 #[inline]
1011 pub fn is_numeric(self) -> bool {
1012 match self {
1013 '0'..='9' => true,
1014 c => c > '\x7f' && unicode::N(c),
1015 }
1016 }
1017
1018 /// Returns an iterator that yields the lowercase mapping of this `char` as one or more
1019 /// `char`s.
1020 ///
1021 /// If this `char` does not have a lowercase mapping, the iterator yields the same `char`.
1022 ///
1023 /// If this `char` has a one-to-one lowercase mapping given by the [Unicode Character
1024 /// Database][ucd] [`UnicodeData.txt`], the iterator yields that `char`.
1025 ///
1026 /// [ucd]: https://www.unicode.org/reports/tr44/
1027 /// [`UnicodeData.txt`]: https://www.unicode.org/Public/UCD/latest/ucd/UnicodeData.txt
1028 ///
1029 /// If this `char` requires special considerations (e.g. multiple `char`s) the iterator yields
1030 /// the `char`(s) given by [`SpecialCasing.txt`].
1031 ///
1032 /// [`SpecialCasing.txt`]: https://www.unicode.org/Public/UCD/latest/ucd/SpecialCasing.txt
1033 ///
1034 /// This operation performs an unconditional mapping without tailoring. That is, the conversion
1035 /// is independent of context and language.
1036 ///
1037 /// In the [Unicode Standard], Chapter 4 (Character Properties) discusses case mapping in
1038 /// general and Chapter 3 (Conformance) discusses the default algorithm for case conversion.
1039 ///
1040 /// [Unicode Standard]: https://www.unicode.org/versions/latest/
1041 ///
1042 /// # Examples
1043 ///
1044 /// As an iterator:
1045 ///
1046 /// ```
1047 /// for c in 'İ'.to_lowercase() {
1048 /// print!("{c}");
1049 /// }
1050 /// println!();
1051 /// ```
1052 ///
1053 /// Using `println!` directly:
1054 ///
1055 /// ```
1056 /// println!("{}", 'İ'.to_lowercase());
1057 /// ```
1058 ///
1059 /// Both are equivalent to:
1060 ///
1061 /// ```
1062 /// println!("i\u{307}");
1063 /// ```
1064 ///
1065 /// Using [`to_string`](../std/string/trait.ToString.html#tymethod.to_string):
1066 ///
1067 /// ```
1068 /// assert_eq!('C'.to_lowercase().to_string(), "c");
1069 ///
1070 /// // Sometimes the result is more than one character:
1071 /// assert_eq!('İ'.to_lowercase().to_string(), "i\u{307}");
1072 ///
1073 /// // Characters that do not have both uppercase and lowercase
1074 /// // convert into themselves.
1075 /// assert_eq!('山'.to_lowercase().to_string(), "山");
1076 /// ```
1077 #[must_use = "this returns the lowercase character as a new iterator, \
1078 without modifying the original"]
1079 #[stable(feature = "rust1", since = "1.0.0")]
1080 #[inline]
1081 pub fn to_lowercase(self) -> ToLowercase {
1082 ToLowercase(CaseMappingIter::new(conversions::to_lower(self)))
1083 }
1084
1085 /// Returns an iterator that yields the uppercase mapping of this `char` as one or more
1086 /// `char`s.
1087 ///
1088 /// If this `char` does not have an uppercase mapping, the iterator yields the same `char`.
1089 ///
1090 /// If this `char` has a one-to-one uppercase mapping given by the [Unicode Character
1091 /// Database][ucd] [`UnicodeData.txt`], the iterator yields that `char`.
1092 ///
1093 /// [ucd]: https://www.unicode.org/reports/tr44/
1094 /// [`UnicodeData.txt`]: https://www.unicode.org/Public/UCD/latest/ucd/UnicodeData.txt
1095 ///
1096 /// If this `char` requires special considerations (e.g. multiple `char`s) the iterator yields
1097 /// the `char`(s) given by [`SpecialCasing.txt`].
1098 ///
1099 /// [`SpecialCasing.txt`]: https://www.unicode.org/Public/UCD/latest/ucd/SpecialCasing.txt
1100 ///
1101 /// This operation performs an unconditional mapping without tailoring. That is, the conversion
1102 /// is independent of context and language.
1103 ///
1104 /// In the [Unicode Standard], Chapter 4 (Character Properties) discusses case mapping in
1105 /// general and Chapter 3 (Conformance) discusses the default algorithm for case conversion.
1106 ///
1107 /// [Unicode Standard]: https://www.unicode.org/versions/latest/
1108 ///
1109 /// # Examples
1110 ///
1111 /// As an iterator:
1112 ///
1113 /// ```
1114 /// for c in 'ß'.to_uppercase() {
1115 /// print!("{c}");
1116 /// }
1117 /// println!();
1118 /// ```
1119 ///
1120 /// Using `println!` directly:
1121 ///
1122 /// ```
1123 /// println!("{}", 'ß'.to_uppercase());
1124 /// ```
1125 ///
1126 /// Both are equivalent to:
1127 ///
1128 /// ```
1129 /// println!("SS");
1130 /// ```
1131 ///
1132 /// Using [`to_string`](../std/string/trait.ToString.html#tymethod.to_string):
1133 ///
1134 /// ```
1135 /// assert_eq!('c'.to_uppercase().to_string(), "C");
1136 ///
1137 /// // Sometimes the result is more than one character:
1138 /// assert_eq!('ß'.to_uppercase().to_string(), "SS");
1139 ///
1140 /// // Characters that do not have both uppercase and lowercase
1141 /// // convert into themselves.
1142 /// assert_eq!('山'.to_uppercase().to_string(), "山");
1143 /// ```
1144 ///
1145 /// # Note on locale
1146 ///
1147 /// In Turkish, the equivalent of 'i' in Latin has five forms instead of two:
1148 ///
1149 /// * 'Dotless': I / ı, sometimes written ï
1150 /// * 'Dotted': İ / i
1151 ///
1152 /// Note that the lowercase dotted 'i' is the same as the Latin. Therefore:
1153 ///
1154 /// ```
1155 /// let upper_i = 'i'.to_uppercase().to_string();
1156 /// ```
1157 ///
1158 /// The value of `upper_i` here relies on the language of the text: if we're
1159 /// in `en-US`, it should be `"I"`, but if we're in `tr_TR`, it should
1160 /// be `"İ"`. `to_uppercase()` does not take this into account, and so:
1161 ///
1162 /// ```
1163 /// let upper_i = 'i'.to_uppercase().to_string();
1164 ///
1165 /// assert_eq!(upper_i, "I");
1166 /// ```
1167 ///
1168 /// holds across languages.
1169 #[must_use = "this returns the uppercase character as a new iterator, \
1170 without modifying the original"]
1171 #[stable(feature = "rust1", since = "1.0.0")]
1172 #[inline]
1173 pub fn to_uppercase(self) -> ToUppercase {
1174 ToUppercase(CaseMappingIter::new(conversions::to_upper(self)))
1175 }
1176
1177 /// Checks if the value is within the ASCII range.
1178 ///
1179 /// # Examples
1180 ///
1181 /// ```
1182 /// let ascii = 'a';
1183 /// let non_ascii = '❤';
1184 ///
1185 /// assert!(ascii.is_ascii());
1186 /// assert!(!non_ascii.is_ascii());
1187 /// ```
1188 #[must_use]
1189 #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")]
1190 #[rustc_const_stable(feature = "const_char_is_ascii", since = "1.32.0")]
1191 #[rustc_diagnostic_item = "char_is_ascii"]
1192 #[inline]
1193 pub const fn is_ascii(&self) -> bool {
1194 *self as u32 <= 0x7F
1195 }
1196
1197 /// Returns `Some` if the value is within the ASCII range,
1198 /// or `None` if it's not.
1199 ///
1200 /// This is preferred to [`Self::is_ascii`] when you're passing the value
1201 /// along to something else that can take [`ascii::Char`] rather than
1202 /// needing to check again for itself whether the value is in ASCII.
1203 #[must_use]
1204 #[unstable(feature = "ascii_char", issue = "110998")]
1205 #[inline]
1206 pub const fn as_ascii(&self) -> Option<ascii::Char> {
1207 if self.is_ascii() {
1208 // SAFETY: Just checked that this is ASCII.
1209 Some(unsafe { ascii::Char::from_u8_unchecked(*self as u8) })
1210 } else {
1211 None
1212 }
1213 }
1214
1215 /// Converts this char into an [ASCII character](`ascii::Char`), without
1216 /// checking whether it is valid.
1217 ///
1218 /// # Safety
1219 ///
1220 /// This char must be within the ASCII range, or else this is UB.
1221 #[must_use]
1222 #[unstable(feature = "ascii_char", issue = "110998")]
1223 #[inline]
1224 pub const unsafe fn as_ascii_unchecked(&self) -> ascii::Char {
1225 assert_unsafe_precondition!(
1226 check_library_ub,
1227 "as_ascii_unchecked requires that the char is valid ASCII",
1228 (it: &char = self) => it.is_ascii()
1229 );
1230
1231 // SAFETY: the caller promised that this char is ASCII.
1232 unsafe { ascii::Char::from_u8_unchecked(*self as u8) }
1233 }
1234
1235 /// Makes a copy of the value in its ASCII upper case equivalent.
1236 ///
1237 /// ASCII letters 'a' to 'z' are mapped to 'A' to 'Z',
1238 /// but non-ASCII letters are unchanged.
1239 ///
1240 /// To uppercase the value in-place, use [`make_ascii_uppercase()`].
1241 ///
1242 /// To uppercase ASCII characters in addition to non-ASCII characters, use
1243 /// [`to_uppercase()`].
1244 ///
1245 /// # Examples
1246 ///
1247 /// ```
1248 /// let ascii = 'a';
1249 /// let non_ascii = '❤';
1250 ///
1251 /// assert_eq!('A', ascii.to_ascii_uppercase());
1252 /// assert_eq!('❤', non_ascii.to_ascii_uppercase());
1253 /// ```
1254 ///
1255 /// [`make_ascii_uppercase()`]: #method.make_ascii_uppercase
1256 /// [`to_uppercase()`]: #method.to_uppercase
1257 #[must_use = "to uppercase the value in-place, use `make_ascii_uppercase()`"]
1258 #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")]
1259 #[rustc_const_stable(feature = "const_ascii_methods_on_intrinsics", since = "1.52.0")]
1260 #[inline]
1261 pub const fn to_ascii_uppercase(&self) -> char {
1262 if self.is_ascii_lowercase() {
1263 (*self as u8).ascii_change_case_unchecked() as char
1264 } else {
1265 *self
1266 }
1267 }
1268
1269 /// Makes a copy of the value in its ASCII lower case equivalent.
1270 ///
1271 /// ASCII letters 'A' to 'Z' are mapped to 'a' to 'z',
1272 /// but non-ASCII letters are unchanged.
1273 ///
1274 /// To lowercase the value in-place, use [`make_ascii_lowercase()`].
1275 ///
1276 /// To lowercase ASCII characters in addition to non-ASCII characters, use
1277 /// [`to_lowercase()`].
1278 ///
1279 /// # Examples
1280 ///
1281 /// ```
1282 /// let ascii = 'A';
1283 /// let non_ascii = '❤';
1284 ///
1285 /// assert_eq!('a', ascii.to_ascii_lowercase());
1286 /// assert_eq!('❤', non_ascii.to_ascii_lowercase());
1287 /// ```
1288 ///
1289 /// [`make_ascii_lowercase()`]: #method.make_ascii_lowercase
1290 /// [`to_lowercase()`]: #method.to_lowercase
1291 #[must_use = "to lowercase the value in-place, use `make_ascii_lowercase()`"]
1292 #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")]
1293 #[rustc_const_stable(feature = "const_ascii_methods_on_intrinsics", since = "1.52.0")]
1294 #[inline]
1295 pub const fn to_ascii_lowercase(&self) -> char {
1296 if self.is_ascii_uppercase() {
1297 (*self as u8).ascii_change_case_unchecked() as char
1298 } else {
1299 *self
1300 }
1301 }
1302
1303 /// Checks that two values are an ASCII case-insensitive match.
1304 ///
1305 /// Equivalent to <code>[to_ascii_lowercase]\(a) == [to_ascii_lowercase]\(b)</code>.
1306 ///
1307 /// # Examples
1308 ///
1309 /// ```
1310 /// let upper_a = 'A';
1311 /// let lower_a = 'a';
1312 /// let lower_z = 'z';
1313 ///
1314 /// assert!(upper_a.eq_ignore_ascii_case(&lower_a));
1315 /// assert!(upper_a.eq_ignore_ascii_case(&upper_a));
1316 /// assert!(!upper_a.eq_ignore_ascii_case(&lower_z));
1317 /// ```
1318 ///
1319 /// [to_ascii_lowercase]: #method.to_ascii_lowercase
1320 #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")]
1321 #[rustc_const_stable(feature = "const_ascii_methods_on_intrinsics", since = "1.52.0")]
1322 #[inline]
1323 pub const fn eq_ignore_ascii_case(&self, other: &char) -> bool {
1324 self.to_ascii_lowercase() == other.to_ascii_lowercase()
1325 }
1326
1327 /// Converts this type to its ASCII upper case equivalent in-place.
1328 ///
1329 /// ASCII letters 'a' to 'z' are mapped to 'A' to 'Z',
1330 /// but non-ASCII letters are unchanged.
1331 ///
1332 /// To return a new uppercased value without modifying the existing one, use
1333 /// [`to_ascii_uppercase()`].
1334 ///
1335 /// # Examples
1336 ///
1337 /// ```
1338 /// let mut ascii = 'a';
1339 ///
1340 /// ascii.make_ascii_uppercase();
1341 ///
1342 /// assert_eq!('A', ascii);
1343 /// ```
1344 ///
1345 /// [`to_ascii_uppercase()`]: #method.to_ascii_uppercase
1346 #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")]
1347 #[rustc_const_stable(feature = "const_make_ascii", since = "1.84.0")]
1348 #[inline]
1349 pub const fn make_ascii_uppercase(&mut self) {
1350 *self = self.to_ascii_uppercase();
1351 }
1352
1353 /// Converts this type to its ASCII lower case equivalent in-place.
1354 ///
1355 /// ASCII letters 'A' to 'Z' are mapped to 'a' to 'z',
1356 /// but non-ASCII letters are unchanged.
1357 ///
1358 /// To return a new lowercased value without modifying the existing one, use
1359 /// [`to_ascii_lowercase()`].
1360 ///
1361 /// # Examples
1362 ///
1363 /// ```
1364 /// let mut ascii = 'A';
1365 ///
1366 /// ascii.make_ascii_lowercase();
1367 ///
1368 /// assert_eq!('a', ascii);
1369 /// ```
1370 ///
1371 /// [`to_ascii_lowercase()`]: #method.to_ascii_lowercase
1372 #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")]
1373 #[rustc_const_stable(feature = "const_make_ascii", since = "1.84.0")]
1374 #[inline]
1375 pub const fn make_ascii_lowercase(&mut self) {
1376 *self = self.to_ascii_lowercase();
1377 }
1378
1379 /// Checks if the value is an ASCII alphabetic character:
1380 ///
1381 /// - U+0041 'A' ..= U+005A 'Z', or
1382 /// - U+0061 'a' ..= U+007A 'z'.
1383 ///
1384 /// # Examples
1385 ///
1386 /// ```
1387 /// let uppercase_a = 'A';
1388 /// let uppercase_g = 'G';
1389 /// let a = 'a';
1390 /// let g = 'g';
1391 /// let zero = '0';
1392 /// let percent = '%';
1393 /// let space = ' ';
1394 /// let lf = '\n';
1395 /// let esc = '\x1b';
1396 ///
1397 /// assert!(uppercase_a.is_ascii_alphabetic());
1398 /// assert!(uppercase_g.is_ascii_alphabetic());
1399 /// assert!(a.is_ascii_alphabetic());
1400 /// assert!(g.is_ascii_alphabetic());
1401 /// assert!(!zero.is_ascii_alphabetic());
1402 /// assert!(!percent.is_ascii_alphabetic());
1403 /// assert!(!space.is_ascii_alphabetic());
1404 /// assert!(!lf.is_ascii_alphabetic());
1405 /// assert!(!esc.is_ascii_alphabetic());
1406 /// ```
1407 #[must_use]
1408 #[stable(feature = "ascii_ctype_on_intrinsics", since = "1.24.0")]
1409 #[rustc_const_stable(feature = "const_ascii_ctype_on_intrinsics", since = "1.47.0")]
1410 #[inline]
1411 pub const fn is_ascii_alphabetic(&self) -> bool {
1412 matches!(*self, 'A'..='Z' | 'a'..='z')
1413 }
1414
1415 /// Checks if the value is an ASCII uppercase character:
1416 /// U+0041 'A' ..= U+005A 'Z'.
1417 ///
1418 /// # Examples
1419 ///
1420 /// ```
1421 /// let uppercase_a = 'A';
1422 /// let uppercase_g = 'G';
1423 /// let a = 'a';
1424 /// let g = 'g';
1425 /// let zero = '0';
1426 /// let percent = '%';
1427 /// let space = ' ';
1428 /// let lf = '\n';
1429 /// let esc = '\x1b';
1430 ///
1431 /// assert!(uppercase_a.is_ascii_uppercase());
1432 /// assert!(uppercase_g.is_ascii_uppercase());
1433 /// assert!(!a.is_ascii_uppercase());
1434 /// assert!(!g.is_ascii_uppercase());
1435 /// assert!(!zero.is_ascii_uppercase());
1436 /// assert!(!percent.is_ascii_uppercase());
1437 /// assert!(!space.is_ascii_uppercase());
1438 /// assert!(!lf.is_ascii_uppercase());
1439 /// assert!(!esc.is_ascii_uppercase());
1440 /// ```
1441 #[must_use]
1442 #[stable(feature = "ascii_ctype_on_intrinsics", since = "1.24.0")]
1443 #[rustc_const_stable(feature = "const_ascii_ctype_on_intrinsics", since = "1.47.0")]
1444 #[inline]
1445 pub const fn is_ascii_uppercase(&self) -> bool {
1446 matches!(*self, 'A'..='Z')
1447 }
1448
1449 /// Checks if the value is an ASCII lowercase character:
1450 /// U+0061 'a' ..= U+007A 'z'.
1451 ///
1452 /// # Examples
1453 ///
1454 /// ```
1455 /// let uppercase_a = 'A';
1456 /// let uppercase_g = 'G';
1457 /// let a = 'a';
1458 /// let g = 'g';
1459 /// let zero = '0';
1460 /// let percent = '%';
1461 /// let space = ' ';
1462 /// let lf = '\n';
1463 /// let esc = '\x1b';
1464 ///
1465 /// assert!(!uppercase_a.is_ascii_lowercase());
1466 /// assert!(!uppercase_g.is_ascii_lowercase());
1467 /// assert!(a.is_ascii_lowercase());
1468 /// assert!(g.is_ascii_lowercase());
1469 /// assert!(!zero.is_ascii_lowercase());
1470 /// assert!(!percent.is_ascii_lowercase());
1471 /// assert!(!space.is_ascii_lowercase());
1472 /// assert!(!lf.is_ascii_lowercase());
1473 /// assert!(!esc.is_ascii_lowercase());
1474 /// ```
1475 #[must_use]
1476 #[stable(feature = "ascii_ctype_on_intrinsics", since = "1.24.0")]
1477 #[rustc_const_stable(feature = "const_ascii_ctype_on_intrinsics", since = "1.47.0")]
1478 #[inline]
1479 pub const fn is_ascii_lowercase(&self) -> bool {
1480 matches!(*self, 'a'..='z')
1481 }
1482
1483 /// Checks if the value is an ASCII alphanumeric character:
1484 ///
1485 /// - U+0041 'A' ..= U+005A 'Z', or
1486 /// - U+0061 'a' ..= U+007A 'z', or
1487 /// - U+0030 '0' ..= U+0039 '9'.
1488 ///
1489 /// # Examples
1490 ///
1491 /// ```
1492 /// let uppercase_a = 'A';
1493 /// let uppercase_g = 'G';
1494 /// let a = 'a';
1495 /// let g = 'g';
1496 /// let zero = '0';
1497 /// let percent = '%';
1498 /// let space = ' ';
1499 /// let lf = '\n';
1500 /// let esc = '\x1b';
1501 ///
1502 /// assert!(uppercase_a.is_ascii_alphanumeric());
1503 /// assert!(uppercase_g.is_ascii_alphanumeric());
1504 /// assert!(a.is_ascii_alphanumeric());
1505 /// assert!(g.is_ascii_alphanumeric());
1506 /// assert!(zero.is_ascii_alphanumeric());
1507 /// assert!(!percent.is_ascii_alphanumeric());
1508 /// assert!(!space.is_ascii_alphanumeric());
1509 /// assert!(!lf.is_ascii_alphanumeric());
1510 /// assert!(!esc.is_ascii_alphanumeric());
1511 /// ```
1512 #[must_use]
1513 #[stable(feature = "ascii_ctype_on_intrinsics", since = "1.24.0")]
1514 #[rustc_const_stable(feature = "const_ascii_ctype_on_intrinsics", since = "1.47.0")]
1515 #[inline]
1516 pub const fn is_ascii_alphanumeric(&self) -> bool {
1517 matches!(*self, '0'..='9') | matches!(*self, 'A'..='Z') | matches!(*self, 'a'..='z')
1518 }
1519
1520 /// Checks if the value is an ASCII decimal digit:
1521 /// U+0030 '0' ..= U+0039 '9'.
1522 ///
1523 /// # Examples
1524 ///
1525 /// ```
1526 /// let uppercase_a = 'A';
1527 /// let uppercase_g = 'G';
1528 /// let a = 'a';
1529 /// let g = 'g';
1530 /// let zero = '0';
1531 /// let percent = '%';
1532 /// let space = ' ';
1533 /// let lf = '\n';
1534 /// let esc = '\x1b';
1535 ///
1536 /// assert!(!uppercase_a.is_ascii_digit());
1537 /// assert!(!uppercase_g.is_ascii_digit());
1538 /// assert!(!a.is_ascii_digit());
1539 /// assert!(!g.is_ascii_digit());
1540 /// assert!(zero.is_ascii_digit());
1541 /// assert!(!percent.is_ascii_digit());
1542 /// assert!(!space.is_ascii_digit());
1543 /// assert!(!lf.is_ascii_digit());
1544 /// assert!(!esc.is_ascii_digit());
1545 /// ```
1546 #[must_use]
1547 #[stable(feature = "ascii_ctype_on_intrinsics", since = "1.24.0")]
1548 #[rustc_const_stable(feature = "const_ascii_ctype_on_intrinsics", since = "1.47.0")]
1549 #[inline]
1550 pub const fn is_ascii_digit(&self) -> bool {
1551 matches!(*self, '0'..='9')
1552 }
1553
1554 /// Checks if the value is an ASCII octal digit:
1555 /// U+0030 '0' ..= U+0037 '7'.
1556 ///
1557 /// # Examples
1558 ///
1559 /// ```
1560 /// #![feature(is_ascii_octdigit)]
1561 ///
1562 /// let uppercase_a = 'A';
1563 /// let a = 'a';
1564 /// let zero = '0';
1565 /// let seven = '7';
1566 /// let nine = '9';
1567 /// let percent = '%';
1568 /// let lf = '\n';
1569 ///
1570 /// assert!(!uppercase_a.is_ascii_octdigit());
1571 /// assert!(!a.is_ascii_octdigit());
1572 /// assert!(zero.is_ascii_octdigit());
1573 /// assert!(seven.is_ascii_octdigit());
1574 /// assert!(!nine.is_ascii_octdigit());
1575 /// assert!(!percent.is_ascii_octdigit());
1576 /// assert!(!lf.is_ascii_octdigit());
1577 /// ```
1578 #[must_use]
1579 #[unstable(feature = "is_ascii_octdigit", issue = "101288")]
1580 #[inline]
1581 pub const fn is_ascii_octdigit(&self) -> bool {
1582 matches!(*self, '0'..='7')
1583 }
1584
1585 /// Checks if the value is an ASCII hexadecimal digit:
1586 ///
1587 /// - U+0030 '0' ..= U+0039 '9', or
1588 /// - U+0041 'A' ..= U+0046 'F', or
1589 /// - U+0061 'a' ..= U+0066 'f'.
1590 ///
1591 /// # Examples
1592 ///
1593 /// ```
1594 /// let uppercase_a = 'A';
1595 /// let uppercase_g = 'G';
1596 /// let a = 'a';
1597 /// let g = 'g';
1598 /// let zero = '0';
1599 /// let percent = '%';
1600 /// let space = ' ';
1601 /// let lf = '\n';
1602 /// let esc = '\x1b';
1603 ///
1604 /// assert!(uppercase_a.is_ascii_hexdigit());
1605 /// assert!(!uppercase_g.is_ascii_hexdigit());
1606 /// assert!(a.is_ascii_hexdigit());
1607 /// assert!(!g.is_ascii_hexdigit());
1608 /// assert!(zero.is_ascii_hexdigit());
1609 /// assert!(!percent.is_ascii_hexdigit());
1610 /// assert!(!space.is_ascii_hexdigit());
1611 /// assert!(!lf.is_ascii_hexdigit());
1612 /// assert!(!esc.is_ascii_hexdigit());
1613 /// ```
1614 #[must_use]
1615 #[stable(feature = "ascii_ctype_on_intrinsics", since = "1.24.0")]
1616 #[rustc_const_stable(feature = "const_ascii_ctype_on_intrinsics", since = "1.47.0")]
1617 #[inline]
1618 pub const fn is_ascii_hexdigit(&self) -> bool {
1619 matches!(*self, '0'..='9') | matches!(*self, 'A'..='F') | matches!(*self, 'a'..='f')
1620 }
1621
1622 /// Checks if the value is an ASCII punctuation character:
1623 ///
1624 /// - U+0021 ..= U+002F `! " # $ % & ' ( ) * + , - . /`, or
1625 /// - U+003A ..= U+0040 `: ; < = > ? @`, or
1626 /// - U+005B ..= U+0060 ``[ \ ] ^ _ ` ``, or
1627 /// - U+007B ..= U+007E `{ | } ~`
1628 ///
1629 /// # Examples
1630 ///
1631 /// ```
1632 /// let uppercase_a = 'A';
1633 /// let uppercase_g = 'G';
1634 /// let a = 'a';
1635 /// let g = 'g';
1636 /// let zero = '0';
1637 /// let percent = '%';
1638 /// let space = ' ';
1639 /// let lf = '\n';
1640 /// let esc = '\x1b';
1641 ///
1642 /// assert!(!uppercase_a.is_ascii_punctuation());
1643 /// assert!(!uppercase_g.is_ascii_punctuation());
1644 /// assert!(!a.is_ascii_punctuation());
1645 /// assert!(!g.is_ascii_punctuation());
1646 /// assert!(!zero.is_ascii_punctuation());
1647 /// assert!(percent.is_ascii_punctuation());
1648 /// assert!(!space.is_ascii_punctuation());
1649 /// assert!(!lf.is_ascii_punctuation());
1650 /// assert!(!esc.is_ascii_punctuation());
1651 /// ```
1652 #[must_use]
1653 #[stable(feature = "ascii_ctype_on_intrinsics", since = "1.24.0")]
1654 #[rustc_const_stable(feature = "const_ascii_ctype_on_intrinsics", since = "1.47.0")]
1655 #[inline]
1656 pub const fn is_ascii_punctuation(&self) -> bool {
1657 matches!(*self, '!'..='/')
1658 | matches!(*self, ':'..='@')
1659 | matches!(*self, '['..='`')
1660 | matches!(*self, '{'..='~')
1661 }
1662
1663 /// Checks if the value is an ASCII graphic character:
1664 /// U+0021 '!' ..= U+007E '~'.
1665 ///
1666 /// # Examples
1667 ///
1668 /// ```
1669 /// let uppercase_a = 'A';
1670 /// let uppercase_g = 'G';
1671 /// let a = 'a';
1672 /// let g = 'g';
1673 /// let zero = '0';
1674 /// let percent = '%';
1675 /// let space = ' ';
1676 /// let lf = '\n';
1677 /// let esc = '\x1b';
1678 ///
1679 /// assert!(uppercase_a.is_ascii_graphic());
1680 /// assert!(uppercase_g.is_ascii_graphic());
1681 /// assert!(a.is_ascii_graphic());
1682 /// assert!(g.is_ascii_graphic());
1683 /// assert!(zero.is_ascii_graphic());
1684 /// assert!(percent.is_ascii_graphic());
1685 /// assert!(!space.is_ascii_graphic());
1686 /// assert!(!lf.is_ascii_graphic());
1687 /// assert!(!esc.is_ascii_graphic());
1688 /// ```
1689 #[must_use]
1690 #[stable(feature = "ascii_ctype_on_intrinsics", since = "1.24.0")]
1691 #[rustc_const_stable(feature = "const_ascii_ctype_on_intrinsics", since = "1.47.0")]
1692 #[inline]
1693 pub const fn is_ascii_graphic(&self) -> bool {
1694 matches!(*self, '!'..='~')
1695 }
1696
1697 /// Checks if the value is an ASCII whitespace character:
1698 /// U+0020 SPACE, U+0009 HORIZONTAL TAB, U+000A LINE FEED,
1699 /// U+000C FORM FEED, or U+000D CARRIAGE RETURN.
1700 ///
1701 /// Rust uses the WhatWG Infra Standard's [definition of ASCII
1702 /// whitespace][infra-aw]. There are several other definitions in
1703 /// wide use. For instance, [the POSIX locale][pct] includes
1704 /// U+000B VERTICAL TAB as well as all the above characters,
1705 /// but—from the very same specification—[the default rule for
1706 /// "field splitting" in the Bourne shell][bfs] considers *only*
1707 /// SPACE, HORIZONTAL TAB, and LINE FEED as whitespace.
1708 ///
1709 /// If you are writing a program that will process an existing
1710 /// file format, check what that format's definition of whitespace is
1711 /// before using this function.
1712 ///
1713 /// [infra-aw]: https://infra.spec.whatwg.org/#ascii-whitespace
1714 /// [pct]: https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap07.html#tag_07_03_01
1715 /// [bfs]: https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18_06_05
1716 ///
1717 /// # Examples
1718 ///
1719 /// ```
1720 /// let uppercase_a = 'A';
1721 /// let uppercase_g = 'G';
1722 /// let a = 'a';
1723 /// let g = 'g';
1724 /// let zero = '0';
1725 /// let percent = '%';
1726 /// let space = ' ';
1727 /// let lf = '\n';
1728 /// let esc = '\x1b';
1729 ///
1730 /// assert!(!uppercase_a.is_ascii_whitespace());
1731 /// assert!(!uppercase_g.is_ascii_whitespace());
1732 /// assert!(!a.is_ascii_whitespace());
1733 /// assert!(!g.is_ascii_whitespace());
1734 /// assert!(!zero.is_ascii_whitespace());
1735 /// assert!(!percent.is_ascii_whitespace());
1736 /// assert!(space.is_ascii_whitespace());
1737 /// assert!(lf.is_ascii_whitespace());
1738 /// assert!(!esc.is_ascii_whitespace());
1739 /// ```
1740 #[must_use]
1741 #[stable(feature = "ascii_ctype_on_intrinsics", since = "1.24.0")]
1742 #[rustc_const_stable(feature = "const_ascii_ctype_on_intrinsics", since = "1.47.0")]
1743 #[inline]
1744 pub const fn is_ascii_whitespace(&self) -> bool {
1745 matches!(*self, '\t' | '\n' | '\x0C' | '\r' | ' ')
1746 }
1747
1748 /// Checks if the value is an ASCII control character:
1749 /// U+0000 NUL ..= U+001F UNIT SEPARATOR, or U+007F DELETE.
1750 /// Note that most ASCII whitespace characters are control
1751 /// characters, but SPACE is not.
1752 ///
1753 /// # Examples
1754 ///
1755 /// ```
1756 /// let uppercase_a = 'A';
1757 /// let uppercase_g = 'G';
1758 /// let a = 'a';
1759 /// let g = 'g';
1760 /// let zero = '0';
1761 /// let percent = '%';
1762 /// let space = ' ';
1763 /// let lf = '\n';
1764 /// let esc = '\x1b';
1765 ///
1766 /// assert!(!uppercase_a.is_ascii_control());
1767 /// assert!(!uppercase_g.is_ascii_control());
1768 /// assert!(!a.is_ascii_control());
1769 /// assert!(!g.is_ascii_control());
1770 /// assert!(!zero.is_ascii_control());
1771 /// assert!(!percent.is_ascii_control());
1772 /// assert!(!space.is_ascii_control());
1773 /// assert!(lf.is_ascii_control());
1774 /// assert!(esc.is_ascii_control());
1775 /// ```
1776 #[must_use]
1777 #[stable(feature = "ascii_ctype_on_intrinsics", since = "1.24.0")]
1778 #[rustc_const_stable(feature = "const_ascii_ctype_on_intrinsics", since = "1.47.0")]
1779 #[inline]
1780 pub const fn is_ascii_control(&self) -> bool {
1781 matches!(*self, '\0'..='\x1F' | '\x7F')
1782 }
1783}
1784
1785pub(crate) struct EscapeDebugExtArgs {
1786 /// Escape Extended Grapheme codepoints?
1787 pub(crate) escape_grapheme_extended: bool,
1788
1789 /// Escape single quotes?
1790 pub(crate) escape_single_quote: bool,
1791
1792 /// Escape double quotes?
1793 pub(crate) escape_double_quote: bool,
1794}
1795
1796impl EscapeDebugExtArgs {
1797 pub(crate) const ESCAPE_ALL: Self = Self {
1798 escape_grapheme_extended: true,
1799 escape_single_quote: true,
1800 escape_double_quote: true,
1801 };
1802}
1803
1804#[inline]
1805#[must_use]
1806const fn len_utf8(code: u32) -> usize {
1807 match code {
1808 ..MAX_ONE_B => 1,
1809 ..MAX_TWO_B => 2,
1810 ..MAX_THREE_B => 3,
1811 _ => 4,
1812 }
1813}
1814
1815#[inline]
1816#[must_use]
1817const fn len_utf16(code: u32) -> usize {
1818 if (code & 0xFFFF) == code { 1 } else { 2 }
1819}
1820
1821/// Encodes a raw `u32` value as UTF-8 into the provided byte buffer,
1822/// and then returns the subslice of the buffer that contains the encoded character.
1823///
1824/// Unlike `char::encode_utf8`, this method also handles codepoints in the surrogate range.
1825/// (Creating a `char` in the surrogate range is UB.)
1826/// The result is valid [generalized UTF-8] but not valid UTF-8.
1827///
1828/// [generalized UTF-8]: https://simonsapin.github.io/wtf-8/#generalized-utf8
1829///
1830/// # Panics
1831///
1832/// Panics if the buffer is not large enough.
1833/// A buffer of length four is large enough to encode any `char`.
1834#[unstable(feature = "char_internals", reason = "exposed only for libstd", issue = "none")]
1835#[doc(hidden)]
1836#[inline]
1837pub const fn encode_utf8_raw(code: u32, dst: &mut [u8]) -> &mut [u8] {
1838 let len = len_utf8(code);
1839 if dst.len() < len {
1840 const_panic!(
1841 "encode_utf8: buffer does not have enough bytes to encode code point",
1842 "encode_utf8: need {len} bytes to encode U+{code:04X} but buffer has just {dst_len}",
1843 code: u32 = code,
1844 len: usize = len,
1845 dst_len: usize = dst.len(),
1846 );
1847 }
1848
1849 // SAFETY: `dst` is checked to be at least the length needed to encode the codepoint.
1850 unsafe { encode_utf8_raw_unchecked(code, dst.as_mut_ptr()) };
1851
1852 // SAFETY: `<&mut [u8]>::as_mut_ptr` is guaranteed to return a valid pointer and `len` has been tested to be within bounds.
1853 unsafe { slice::from_raw_parts_mut(dst.as_mut_ptr(), len) }
1854}
1855
1856/// Encodes a raw `u32` value as UTF-8 into the byte buffer pointed to by `dst`.
1857///
1858/// Unlike `char::encode_utf8`, this method also handles codepoints in the surrogate range.
1859/// (Creating a `char` in the surrogate range is UB.)
1860/// The result is valid [generalized UTF-8] but not valid UTF-8.
1861///
1862/// [generalized UTF-8]: https://simonsapin.github.io/wtf-8/#generalized-utf8
1863///
1864/// # Safety
1865///
1866/// The behavior is undefined if the buffer pointed to by `dst` is not
1867/// large enough to hold the encoded codepoint. A buffer of length four
1868/// is large enough to encode any `char`.
1869///
1870/// For a safe version of this function, see the [`encode_utf8_raw`] function.
1871#[unstable(feature = "char_internals", reason = "exposed only for libstd", issue = "none")]
1872#[doc(hidden)]
1873#[inline]
1874pub const unsafe fn encode_utf8_raw_unchecked(code: u32, dst: *mut u8) {
1875 let len = len_utf8(code);
1876 // SAFETY: The caller must guarantee that the buffer pointed to by `dst`
1877 // is at least `len` bytes long.
1878 unsafe {
1879 if len == 1 {
1880 *dst = code as u8;
1881 return;
1882 }
1883
1884 let last1 = (code >> 0 & 0x3F) as u8 | TAG_CONT;
1885 let last2 = (code >> 6 & 0x3F) as u8 | TAG_CONT;
1886 let last3 = (code >> 12 & 0x3F) as u8 | TAG_CONT;
1887 let last4 = (code >> 18 & 0x3F) as u8 | TAG_FOUR_B;
1888
1889 if len == 2 {
1890 *dst = last2 | TAG_TWO_B;
1891 *dst.add(1) = last1;
1892 return;
1893 }
1894
1895 if len == 3 {
1896 *dst = last3 | TAG_THREE_B;
1897 *dst.add(1) = last2;
1898 *dst.add(2) = last1;
1899 return;
1900 }
1901
1902 *dst = last4;
1903 *dst.add(1) = last3;
1904 *dst.add(2) = last2;
1905 *dst.add(3) = last1;
1906 }
1907}
1908
1909/// Encodes a raw `u32` value as native endian UTF-16 into the provided `u16` buffer,
1910/// and then returns the subslice of the buffer that contains the encoded character.
1911///
1912/// Unlike `char::encode_utf16`, this method also handles codepoints in the surrogate range.
1913/// (Creating a `char` in the surrogate range is UB.)
1914///
1915/// # Panics
1916///
1917/// Panics if the buffer is not large enough.
1918/// A buffer of length 2 is large enough to encode any `char`.
1919#[unstable(feature = "char_internals", reason = "exposed only for libstd", issue = "none")]
1920#[doc(hidden)]
1921#[inline]
1922pub const fn encode_utf16_raw(mut code: u32, dst: &mut [u16]) -> &mut [u16] {
1923 let len = len_utf16(code);
1924 match (len, &mut *dst) {
1925 (1, [a, ..]) => {
1926 *a = code as u16;
1927 }
1928 (2, [a, b, ..]) => {
1929 code -= 0x1_0000;
1930 *a = (code >> 10) as u16 | 0xD800;
1931 *b = (code & 0x3FF) as u16 | 0xDC00;
1932 }
1933 _ => {
1934 const_panic!(
1935 "encode_utf16: buffer does not have enough bytes to encode code point",
1936 "encode_utf16: need {len} bytes to encode U+{code:04X} but buffer has just {dst_len}",
1937 code: u32 = code,
1938 len: usize = len,
1939 dst_len: usize = dst.len(),
1940 )
1941 }
1942 };
1943 // SAFETY: `<&mut [u16]>::as_mut_ptr` is guaranteed to return a valid pointer and `len` has been tested to be within bounds.
1944 unsafe { slice::from_raw_parts_mut(dst.as_mut_ptr(), len) }
1945}