1 // Copyright 2012-2014 The Rust Project Developers. See the COPYRIGHT
2 // file at the top-level directory of this distribution and at
3 // http://rust-lang.org/COPYRIGHT.
5 // Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
6 // http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
7 // <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
8 // option. This file may not be copied, modified, or distributed
9 // except according to those terms.
13 //! The `char` type represents a single character. More specifically, since
14 //! 'character' isn't a well-defined concept in Unicode, `char` is a '[Unicode
15 //! scalar value]', which is similar to, but not the same as, a '[Unicode code
18 //! [Unicode scalar value]: http://www.unicode.org/glossary/#unicode_scalar_value
19 //! [Unicode code point]: http://www.unicode.org/glossary/#code_point
21 //! This module exists for technical reasons, the primary documentation for
22 //! `char` is directly on [the `char` primitive type](../../std/primitive.char.html)
25 //! This module is the home of the iterator implementations for the iterators
26 //! implemented on `char`, as well as some useful constants and conversion
27 //! functions that convert various types to `char`.
29 #![stable(feature = "rust1", since = "1.0.0")]
31 use core
::char::CharExt
as C
;
33 use tables
::{derived_property, property, general_category, conversions}
;
36 #[stable(feature = "rust1", since = "1.0.0")]
37 pub use core
::char::{MAX, from_u32, from_u32_unchecked, from_digit}
;
38 #[stable(feature = "rust1", since = "1.0.0")]
39 pub use core
::char::{EscapeUnicode, EscapeDefault, EncodeUtf8, EncodeUtf16}
;
42 #[unstable(feature = "unicode", issue = "27783")]
43 pub use tables
::UNICODE_VERSION
;
45 /// Returns an iterator that yields the lowercase equivalent of a `char`.
47 /// This `struct` is created by the [`to_lowercase()`] method on [`char`]. See
48 /// its documentation for more.
50 /// [`to_lowercase()`]: ../../std/primitive.char.html#method.to_lowercase
51 /// [`char`]: ../../std/primitive.char.html
52 #[stable(feature = "rust1", since = "1.0.0")]
53 pub struct ToLowercase(CaseMappingIter
);
55 #[stable(feature = "rust1", since = "1.0.0")]
56 impl Iterator
for ToLowercase
{
58 fn next(&mut self) -> Option
<char> {
63 /// Returns an iterator that yields the uppercase equivalent of a `char`.
65 /// This `struct` is created by the [`to_uppercase()`] method on [`char`]. See
66 /// its documentation for more.
68 /// [`to_uppercase()`]: ../../std/primitive.char.html#method.to_uppercase
69 /// [`char`]: ../../std/primitive.char.html
70 #[stable(feature = "rust1", since = "1.0.0")]
71 pub struct ToUppercase(CaseMappingIter
);
73 #[stable(feature = "rust1", since = "1.0.0")]
74 impl Iterator
for ToUppercase
{
76 fn next(&mut self) -> Option
<char> {
82 enum CaseMappingIter
{
83 Three(char, char, char),
89 impl CaseMappingIter
{
90 fn new(chars
: [char; 3]) -> CaseMappingIter
{
93 CaseMappingIter
::One(chars
[0]) // Including if chars[0] == '\0'
95 CaseMappingIter
::Two(chars
[0], chars
[1])
98 CaseMappingIter
::Three(chars
[0], chars
[1], chars
[2])
103 impl Iterator
for CaseMappingIter
{
105 fn next(&mut self) -> Option
<char> {
107 CaseMappingIter
::Three(a
, b
, c
) => {
108 *self = CaseMappingIter
::Two(b
, c
);
111 CaseMappingIter
::Two(b
, c
) => {
112 *self = CaseMappingIter
::One(c
);
115 CaseMappingIter
::One(c
) => {
116 *self = CaseMappingIter
::Zero
;
119 CaseMappingIter
::Zero
=> None
,
126 /// Checks if a `char` is a digit in the given radix.
128 /// A 'radix' here is sometimes also called a 'base'. A radix of two
129 /// indicates a binary number, a radix of ten, decimal, and a radix of
130 /// sixteen, hexadecimal, to give some common values. Arbitrary
131 /// radicum are supported.
133 /// Compared to `is_numeric()`, this function only recognizes the characters
134 /// `0-9`, `a-z` and `A-Z`.
136 /// 'Digit' is defined to be only the following characters:
142 /// For a more comprehensive understanding of 'digit', see [`is_numeric()`][is_numeric].
144 /// [is_numeric]: #method.is_numeric
148 /// Panics if given a radix larger than 36.
155 /// assert!('1'.is_digit(10));
156 /// assert!('f'.is_digit(16));
157 /// assert!(!'f'.is_digit(10));
160 /// Passing a large radix, causing a panic:
165 /// let result = thread::spawn(|| {
167 /// '1'.is_digit(37);
170 /// assert!(result.is_err());
172 #[stable(feature = "rust1", since = "1.0.0")]
174 pub fn is_digit(self, radix
: u32) -> bool
{
175 C
::is_digit(self, radix
)
178 /// Converts a `char` to a digit in the given radix.
180 /// A 'radix' here is sometimes also called a 'base'. A radix of two
181 /// indicates a binary number, a radix of ten, decimal, and a radix of
182 /// sixteen, hexadecimal, to give some common values. Arbitrary
183 /// radicum are supported.
185 /// 'Digit' is defined to be only the following characters:
193 /// Returns `None` if the `char` does not refer to a digit in the given radix.
197 /// Panics if given a radix larger than 36.
204 /// assert_eq!('1'.to_digit(10), Some(1));
205 /// assert_eq!('f'.to_digit(16), Some(15));
208 /// Passing a non-digit results in failure:
211 /// assert_eq!('f'.to_digit(10), None);
212 /// assert_eq!('z'.to_digit(16), None);
215 /// Passing a large radix, causing a panic:
220 /// let result = thread::spawn(|| {
221 /// '1'.to_digit(37);
224 /// assert!(result.is_err());
226 #[stable(feature = "rust1", since = "1.0.0")]
228 pub fn to_digit(self, radix
: u32) -> Option
<u32> {
229 C
::to_digit(self, radix
)
232 /// Returns an iterator that yields the hexadecimal Unicode escape of a
233 /// character, as `char`s.
235 /// All characters are escaped with Rust syntax of the form `\\u{NNNN}`
236 /// where `NNNN` is the shortest hexadecimal representation.
243 /// for c in '❤'.escape_unicode() {
255 /// Collecting into a `String`:
258 /// let heart: String = '❤'.escape_unicode().collect();
260 /// assert_eq!(heart, r"\u{2764}");
262 #[stable(feature = "rust1", since = "1.0.0")]
264 pub fn escape_unicode(self) -> EscapeUnicode
{
265 C
::escape_unicode(self)
268 /// Returns an iterator that yields the literal escape code of a `char`.
270 /// The default is chosen with a bias toward producing literals that are
271 /// legal in a variety of languages, including C++11 and similar C-family
272 /// languages. The exact rules are:
274 /// * Tab is escaped as `\t`.
275 /// * Carriage return is escaped as `\r`.
276 /// * Line feed is escaped as `\n`.
277 /// * Single quote is escaped as `\'`.
278 /// * Double quote is escaped as `\"`.
279 /// * Backslash is escaped as `\\`.
280 /// * Any character in the 'printable ASCII' range `0x20` .. `0x7e`
281 /// inclusive is not escaped.
282 /// * All other characters are given hexadecimal Unicode escapes; see
283 /// [`escape_unicode`][escape_unicode].
285 /// [escape_unicode]: #method.escape_unicode
292 /// for i in '"'.escape_default() {
293 /// println!("{}", i);
304 /// Collecting into a `String`:
307 /// let quote: String = '"'.escape_default().collect();
309 /// assert_eq!(quote, "\\\"");
311 #[stable(feature = "rust1", since = "1.0.0")]
313 pub fn escape_default(self) -> EscapeDefault
{
314 C
::escape_default(self)
317 /// Returns the number of bytes this `char` would need if encoded in UTF-8.
319 /// That number of bytes is always between 1 and 4, inclusive.
326 /// let len = 'A'.len_utf8();
327 /// assert_eq!(len, 1);
329 /// let len = 'ß'.len_utf8();
330 /// assert_eq!(len, 2);
332 /// let len = 'ℝ'.len_utf8();
333 /// assert_eq!(len, 3);
335 /// let len = '💣'.len_utf8();
336 /// assert_eq!(len, 4);
339 /// The `&str` type guarantees that its contents are UTF-8, and so we can compare the length it
340 /// would take if each code point was represented as a `char` vs in the `&str` itself:
344 /// let eastern = '東';
345 /// let capitol = '京';
347 /// // both can be represented as three bytes
348 /// assert_eq!(3, eastern.len_utf8());
349 /// assert_eq!(3, capitol.len_utf8());
351 /// // as a &str, these two are encoded in UTF-8
352 /// let tokyo = "東京";
354 /// let len = eastern.len_utf8() + capitol.len_utf8();
356 /// // we can see that they take six bytes total...
357 /// assert_eq!(6, tokyo.len());
359 /// // ... just like the &str
360 /// assert_eq!(len, tokyo.len());
362 #[stable(feature = "rust1", since = "1.0.0")]
364 pub fn len_utf8(self) -> usize {
368 /// Returns the number of 16-bit code units this `char` would need if
369 /// encoded in UTF-16.
371 /// See the documentation for [`len_utf8()`] for more explanation of this
372 /// concept. This function is a mirror, but for UTF-16 instead of UTF-8.
374 /// [`len_utf8()`]: #method.len_utf8
381 /// let n = 'ß'.len_utf16();
382 /// assert_eq!(n, 1);
384 /// let len = '💣'.len_utf16();
385 /// assert_eq!(len, 2);
387 #[stable(feature = "rust1", since = "1.0.0")]
389 pub fn len_utf16(self) -> usize {
393 /// Returns an interator over the bytes of this character as UTF-8.
395 /// The returned iterator also has an `as_slice()` method to view the
396 /// encoded bytes as a byte slice.
401 /// #![feature(unicode)]
403 /// let iterator = 'ß'.encode_utf8();
404 /// assert_eq!(iterator.as_slice(), [0xc3, 0x9f]);
406 /// for (i, byte) in iterator.enumerate() {
407 /// println!("byte {}: {:x}", i, byte);
410 #[unstable(feature = "unicode", issue = "27784")]
412 pub fn encode_utf8(self) -> EncodeUtf8
{
416 /// Returns an interator over the `u16` entries of this character as UTF-16.
418 /// The returned iterator also has an `as_slice()` method to view the
419 /// encoded form as a slice.
424 /// #![feature(unicode)]
426 /// let iterator = '𝕊'.encode_utf16();
427 /// assert_eq!(iterator.as_slice(), [0xd835, 0xdd4a]);
429 /// for (i, val) in iterator.enumerate() {
430 /// println!("entry {}: {:x}", i, val);
433 #[unstable(feature = "unicode", issue = "27784")]
435 pub fn encode_utf16(self) -> EncodeUtf16
{
436 C
::encode_utf16(self)
439 /// Returns true if this `char` is an alphabetic code point, and false if not.
446 /// assert!('a'.is_alphabetic());
447 /// assert!('京'.is_alphabetic());
450 /// // love is many things, but it is not alphabetic
451 /// assert!(!c.is_alphabetic());
453 #[stable(feature = "rust1", since = "1.0.0")]
455 pub fn is_alphabetic(self) -> bool
{
457 'a'
...'z'
| 'A'
...'Z'
=> true,
458 c
if c
> '
\x7f'
=> derived_property
::Alphabetic(c
),
463 /// Returns true if this `char` satisfies the 'XID_Start' Unicode property, and false
466 /// 'XID_Start' is a Unicode Derived Property specified in
467 /// [UAX #31](http://unicode.org/reports/tr31/#NFKC_Modifications),
468 /// mostly similar to `ID_Start` but modified for closure under `NFKx`.
469 #[unstable(feature = "unicode",
470 reason
= "mainly needed for compiler internals",
473 pub fn is_xid_start(self) -> bool
{
474 derived_property
::XID_Start(self)
477 /// Returns true if this `char` satisfies the 'XID_Continue' Unicode property, and false
480 /// 'XID_Continue' is a Unicode Derived Property specified in
481 /// [UAX #31](http://unicode.org/reports/tr31/#NFKC_Modifications),
482 /// mostly similar to 'ID_Continue' but modified for closure under NFKx.
483 #[unstable(feature = "unicode",
484 reason
= "mainly needed for compiler internals",
487 pub fn is_xid_continue(self) -> bool
{
488 derived_property
::XID_Continue(self)
491 /// Returns true if this `char` is lowercase, and false otherwise.
493 /// 'Lowercase' is defined according to the terms of the Unicode Derived Core
494 /// Property `Lowercase`.
501 /// assert!('a'.is_lowercase());
502 /// assert!('δ'.is_lowercase());
503 /// assert!(!'A'.is_lowercase());
504 /// assert!(!'Δ'.is_lowercase());
506 /// // The various Chinese scripts do not have case, and so:
507 /// assert!(!'中'.is_lowercase());
509 #[stable(feature = "rust1", since = "1.0.0")]
511 pub fn is_lowercase(self) -> bool
{
514 c
if c
> '
\x7f'
=> derived_property
::Lowercase(c
),
519 /// Returns true if this `char` is uppercase, and false otherwise.
521 /// 'Uppercase' is defined according to the terms of the Unicode Derived Core
522 /// Property `Uppercase`.
529 /// assert!(!'a'.is_uppercase());
530 /// assert!(!'δ'.is_uppercase());
531 /// assert!('A'.is_uppercase());
532 /// assert!('Δ'.is_uppercase());
534 /// // The various Chinese scripts do not have case, and so:
535 /// assert!(!'中'.is_uppercase());
537 #[stable(feature = "rust1", since = "1.0.0")]
539 pub fn is_uppercase(self) -> bool
{
542 c
if c
> '
\x7f'
=> derived_property
::Uppercase(c
),
547 /// Returns true if this `char` is whitespace, and false otherwise.
549 /// 'Whitespace' is defined according to the terms of the Unicode Derived Core
550 /// Property `White_Space`.
557 /// assert!(' '.is_whitespace());
559 /// // a non-breaking space
560 /// assert!('\u{A0}'.is_whitespace());
562 /// assert!(!'越'.is_whitespace());
564 #[stable(feature = "rust1", since = "1.0.0")]
566 pub fn is_whitespace(self) -> bool
{
568 ' '
| '
\x09'
...'
\x0d'
=> true,
569 c
if c
> '
\x7f'
=> property
::White_Space(c
),
574 /// Returns true if this `char` is alphanumeric, and false otherwise.
576 /// 'Alphanumeric'-ness is defined in terms of the Unicode General Categories
577 /// 'Nd', 'Nl', 'No' and the Derived Core Property 'Alphabetic'.
584 /// assert!('٣'.is_alphanumeric());
585 /// assert!('7'.is_alphanumeric());
586 /// assert!('৬'.is_alphanumeric());
587 /// assert!('K'.is_alphanumeric());
588 /// assert!('و'.is_alphanumeric());
589 /// assert!('藏'.is_alphanumeric());
590 /// assert!(!'¾'.is_alphanumeric());
591 /// assert!(!'①'.is_alphanumeric());
593 #[stable(feature = "rust1", since = "1.0.0")]
595 pub fn is_alphanumeric(self) -> bool
{
596 self.is_alphabetic() || self.is_numeric()
599 /// Returns true if this `char` is a control code point, and false otherwise.
601 /// 'Control code point' is defined in terms of the Unicode General
609 /// // U+009C, STRING TERMINATOR
610 /// assert!('\9c'.is_control());
611 /// assert!(!'q'.is_control());
613 #[stable(feature = "rust1", since = "1.0.0")]
615 pub fn is_control(self) -> bool
{
616 general_category
::Cc(self)
619 /// Returns true if this `char` is numeric, and false otherwise.
621 /// 'Numeric'-ness is defined in terms of the Unicode General Categories
622 /// 'Nd', 'Nl', 'No'.
629 /// assert!('٣'.is_numeric());
630 /// assert!('7'.is_numeric());
631 /// assert!('৬'.is_numeric());
632 /// assert!(!'K'.is_numeric());
633 /// assert!(!'و'.is_numeric());
634 /// assert!(!'藏'.is_numeric());
635 /// assert!(!'¾'.is_numeric());
636 /// assert!(!'①'.is_numeric());
638 #[stable(feature = "rust1", since = "1.0.0")]
640 pub fn is_numeric(self) -> bool
{
643 c
if c
> '
\x7f'
=> general_category
::N(c
),
648 /// Returns an iterator that yields the lowercase equivalent of a `char`.
650 /// If no conversion is possible then an iterator with just the input character is returned.
652 /// This performs complex unconditional mappings with no tailoring: it maps
653 /// one Unicode character to its lowercase equivalent according to the
654 /// [Unicode database] and the additional complex mappings
655 /// [`SpecialCasing.txt`]. Conditional mappings (based on context or
656 /// language) are not considered here.
658 /// For a full reference, see [here][reference].
660 /// [Unicode database]: ftp://ftp.unicode.org/Public/UNIDATA/UnicodeData.txt
662 /// [`SpecialCasing.txt`]: ftp://ftp.unicode.org/Public/UNIDATA/SpecialCasing.txt
664 /// [reference]: http://www.unicode.org/versions/Unicode7.0.0/ch03.pdf#G33992
671 /// assert_eq!('C'.to_lowercase().next(), Some('c'));
673 /// // Japanese scripts do not have case, and so:
674 /// assert_eq!('山'.to_lowercase().next(), Some('山'));
676 #[stable(feature = "rust1", since = "1.0.0")]
678 pub fn to_lowercase(self) -> ToLowercase
{
679 ToLowercase(CaseMappingIter
::new(conversions
::to_lower(self)))
682 /// Returns an iterator that yields the uppercase equivalent of a `char`.
684 /// If no conversion is possible then an iterator with just the input character is returned.
686 /// This performs complex unconditional mappings with no tailoring: it maps
687 /// one Unicode character to its uppercase equivalent according to the
688 /// [Unicode database] and the additional complex mappings
689 /// [`SpecialCasing.txt`]. Conditional mappings (based on context or
690 /// language) are not considered here.
692 /// For a full reference, see [here][reference].
694 /// [Unicode database]: ftp://ftp.unicode.org/Public/UNIDATA/UnicodeData.txt
696 /// [`SpecialCasing.txt`]: ftp://ftp.unicode.org/Public/UNIDATA/SpecialCasing.txt
698 /// [reference]: http://www.unicode.org/versions/Unicode7.0.0/ch03.pdf#G33992
705 /// assert_eq!('c'.to_uppercase().next(), Some('C'));
707 /// // Japanese does not have case, and so:
708 /// assert_eq!('山'.to_uppercase().next(), Some('山'));
711 /// In Turkish, the equivalent of 'i' in Latin has five forms instead of two:
713 /// * 'Dotless': I / ı, sometimes written ï
714 /// * 'Dotted': İ / i
716 /// Note that the lowercase dotted 'i' is the same as the Latin. Therefore:
719 /// let upper_i = 'i'.to_uppercase().next();
722 /// The value of `upper_i` here relies on the language of the text: if we're
723 /// in `en-US`, it should be `Some('I')`, but if we're in `tr_TR`, it should
724 /// be `Some('İ')`. `to_uppercase()` does not take this into account, and so:
727 /// let upper_i = 'i'.to_uppercase().next();
729 /// assert_eq!(Some('I'), upper_i);
732 /// holds across languages.
733 #[stable(feature = "rust1", since = "1.0.0")]
735 pub fn to_uppercase(self) -> ToUppercase
{
736 ToUppercase(CaseMappingIter
::new(conversions
::to_upper(self)))
740 /// An iterator that decodes UTF-16 encoded code points from an iterator of `u16`s.
741 #[stable(feature = "decode_utf16", since = "1.9.0")]
743 pub struct DecodeUtf16
<I
>
744 where I
: Iterator
<Item
= u16>
750 /// An iterator that decodes UTF-16 encoded code points from an iterator of `u16`s.
751 #[stable(feature = "decode_utf16", since = "1.9.0")]
752 #[derive(Debug, Clone, Eq, PartialEq)]
753 pub struct DecodeUtf16Error
{
757 /// Create an iterator over the UTF-16 encoded code points in `iter`,
758 /// returning unpaired surrogates as `Err`s.
765 /// use std::char::decode_utf16;
768 /// // 𝄞mus<invalid>ic<invalid>
769 /// let v = [0xD834, 0xDD1E, 0x006d, 0x0075,
770 /// 0x0073, 0xDD1E, 0x0069, 0x0063,
773 /// assert_eq!(decode_utf16(v.iter().cloned())
774 /// .map(|r| r.map_err(|e| e.unpaired_surrogate()))
775 /// .collect::<Vec<_>>(),
777 /// Ok('m'), Ok('u'), Ok('s'),
779 /// Ok('i'), Ok('c'),
784 /// A lossy decoder can be obtained by replacing `Err` results with the replacement character:
787 /// use std::char::{decode_utf16, REPLACEMENT_CHARACTER};
790 /// // 𝄞mus<invalid>ic<invalid>
791 /// let v = [0xD834, 0xDD1E, 0x006d, 0x0075,
792 /// 0x0073, 0xDD1E, 0x0069, 0x0063,
795 /// assert_eq!(decode_utf16(v.iter().cloned())
796 /// .map(|r| r.unwrap_or(REPLACEMENT_CHARACTER))
797 /// .collect::<String>(),
801 #[stable(feature = "decode_utf16", since = "1.9.0")]
803 pub fn decode_utf16
<I
: IntoIterator
<Item
= u16>>(iter
: I
) -> DecodeUtf16
<I
::IntoIter
> {
805 iter
: iter
.into_iter(),
810 #[stable(feature = "decode_utf16", since = "1.9.0")]
811 impl<I
: Iterator
<Item
=u16>> Iterator
for DecodeUtf16
<I
> {
812 type Item
= Result
<char, DecodeUtf16Error
>;
814 fn next(&mut self) -> Option
<Result
<char, DecodeUtf16Error
>> {
815 let u
= match self.buf
.take() {
817 None
=> match self.iter
.next() {
823 if u
< 0xD800 || 0xDFFF < u
{
825 Some(Ok(unsafe { from_u32_unchecked(u as u32) }
))
826 } else if u
>= 0xDC00 {
827 // a trailing surrogate
828 Some(Err(DecodeUtf16Error { code: u }
))
830 let u2
= match self.iter
.next() {
833 None
=> return Some(Err(DecodeUtf16Error { code: u }
)),
835 if u2
< 0xDC00 || u2
> 0xDFFF {
836 // not a trailing surrogate so we're not a valid
837 // surrogate pair, so rewind to redecode u2 next time.
839 return Some(Err(DecodeUtf16Error { code: u }
));
842 // all ok, so lets decode it.
843 let c
= (((u
- 0xD800) as u32) << 10 | (u2
- 0xDC00) as u32) + 0x1_0000;
844 Some(Ok(unsafe { from_u32_unchecked(c) }
))
849 fn size_hint(&self) -> (usize, Option
<usize>) {
850 let (low
, high
) = self.iter
.size_hint();
851 // we could be entirely valid surrogates (2 elements per
852 // char), or entirely non-surrogates (1 element per char)
857 impl DecodeUtf16Error
{
858 /// Returns the unpaired surrogate which caused this error.
859 #[stable(feature = "decode_utf16", since = "1.9.0")]
860 pub fn unpaired_surrogate(&self) -> u16 {
865 #[stable(feature = "decode_utf16", since = "1.9.0")]
866 impl fmt
::Display
for DecodeUtf16Error
{
867 fn fmt(&self, f
: &mut fmt
::Formatter
) -> fmt
::Result
{
868 write
!(f
, "unpaired surrogate found: {:x}", self.code
)
872 /// `U+FFFD REPLACEMENT CHARACTER` (�) is used in Unicode to represent a
875 /// It can occur, for example, when giving ill-formed UTF-8 bytes to
876 /// [`String::from_utf8_lossy`](../../std/string/struct.String.html#method.from_utf8_lossy).
877 #[stable(feature = "decode_utf16", since = "1.9.0")]
878 pub const REPLACEMENT_CHARACTER
: char = '
\u{FFFD}'
;