src/librustc_unicode/char.rs

   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.
   4 //
   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.
  10
  11 //! A character type.
  12 //!
  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
  16 //! point]'.
  17 //!
  18 //! [Unicode scalar value]: http://www.unicode.org/glossary/#unicode_scalar_value
  19 //! [Unicode code point]: http://www.unicode.org/glossary/#code_point
  20 //!
  21 //! This module exists for technical reasons, the primary documentation for
  22 //! `char` is directly on [the `char` primitive type](../../std/primitive.char.html)
  23 //! itself.
  24 //!
  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`.
  28
  29 #![stable(feature = "rust1", since = "1.0.0")]
  30
  31 use core::char::CharExt as C;
  32 use core::fmt;
  33 use tables::{conversions, derived_property, general_category, property};
  34
  35 // stable reexports
  36 #[stable(feature = "rust1", since = "1.0.0")]
  37 pub use core::char::{MAX, from_digit, from_u32, from_u32_unchecked};
  38 #[stable(feature = "rust1", since = "1.0.0")]
  39 pub use core::char::{EncodeUtf16, EncodeUtf8, EscapeDefault, EscapeUnicode};
  40
  41 // unstable reexports
  42 #[unstable(feature = "unicode", issue = "27783")]
  43 pub use tables::UNICODE_VERSION;
  44
  45 /// Returns an iterator that yields the lowercase equivalent of a `char`.
  46 ///
  47 /// This `struct` is created by the [`to_lowercase()`] method on [`char`]. See
  48 /// its documentation for more.
  49 ///
  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);
  54
  55 #[stable(feature = "rust1", since = "1.0.0")]
  56 impl Iterator for ToLowercase {
  57     type Item = char;
  58     fn next(&mut self) -> Option<char> {
  59         self.0.next()
  60     }
  61 }
  62
  63 /// Returns an iterator that yields the uppercase equivalent of a `char`.
  64 ///
  65 /// This `struct` is created by the [`to_uppercase()`] method on [`char`]. See
  66 /// its documentation for more.
  67 ///
  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);
  72
  73 #[stable(feature = "rust1", since = "1.0.0")]
  74 impl Iterator for ToUppercase {
  75     type Item = char;
  76     fn next(&mut self) -> Option<char> {
  77         self.0.next()
  78     }
  79 }
  80
  81
  82 enum CaseMappingIter {
  83     Three(char, char, char),
  84     Two(char, char),
  85     One(char),
  86     Zero,
  87 }
  88
  89 impl CaseMappingIter {
  90     fn new(chars: [char; 3]) -> CaseMappingIter {
  91         if chars[2] == '\0' {
  92             if chars[1] == '\0' {
  93                 CaseMappingIter::One(chars[0])  // Including if chars[0] == '\0'
  94             } else {
  95                 CaseMappingIter::Two(chars[0], chars[1])
  96             }
  97         } else {
  98             CaseMappingIter::Three(chars[0], chars[1], chars[2])
  99         }
 100     }
 101 }
 102
 103 impl Iterator for CaseMappingIter {
 104     type Item = char;
 105     fn next(&mut self) -> Option<char> {
 106         match *self {
 107             CaseMappingIter::Three(a, b, c) => {
 108                 *self = CaseMappingIter::Two(b, c);
 109                 Some(a)
 110             }
 111             CaseMappingIter::Two(b, c) => {
 112                 *self = CaseMappingIter::One(c);
 113                 Some(b)
 114             }
 115             CaseMappingIter::One(c) => {
 116                 *self = CaseMappingIter::Zero;
 117                 Some(c)
 118             }
 119             CaseMappingIter::Zero => None,
 120         }
 121     }
 122 }
 123
 124 #[lang = "char"]
 125 impl char {
 126     /// Checks if a `char` is a digit in the given radix.
 127     ///
 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.
 132     ///
 133     /// Compared to `is_numeric()`, this function only recognizes the characters
 134     /// `0-9`, `a-z` and `A-Z`.
 135     ///
 136     /// 'Digit' is defined to be only the following characters:
 137     ///
 138     /// * `0-9`
 139     /// * `a-z`
 140     /// * `A-Z`
 141     ///
 142     /// For a more comprehensive understanding of 'digit', see [`is_numeric()`][is_numeric].
 143     ///
 144     /// [is_numeric]: #method.is_numeric
 145     ///
 146     /// # Panics
 147     ///
 148     /// Panics if given a radix larger than 36.
 149     ///
 150     /// # Examples
 151     ///
 152     /// Basic usage:
 153     ///
 154     /// ```
 155     /// assert!('1'.is_digit(10));
 156     /// assert!('f'.is_digit(16));
 157     /// assert!(!'f'.is_digit(10));
 158     /// ```
 159     ///
 160     /// Passing a large radix, causing a panic:
 161     ///
 162     /// ```
 163     /// use std::thread;
 164     ///
 165     /// let result = thread::spawn(|| {
 166     ///     // this panics
 167     ///     '1'.is_digit(37);
 168     /// }).join();
 169     ///
 170     /// assert!(result.is_err());
 171     /// ```
 172     #[stable(feature = "rust1", since = "1.0.0")]
 173     #[inline]
 174     pub fn is_digit(self, radix: u32) -> bool {
 175         C::is_digit(self, radix)
 176     }
 177
 178     /// Converts a `char` to a digit in the given radix.
 179     ///
 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.
 184     ///
 185     /// 'Digit' is defined to be only the following characters:
 186     ///
 187     /// * `0-9`
 188     /// * `a-z`
 189     /// * `A-Z`
 190     ///
 191     /// # Errors
 192     ///
 193     /// Returns `None` if the `char` does not refer to a digit in the given radix.
 194     ///
 195     /// # Panics
 196     ///
 197     /// Panics if given a radix larger than 36.
 198     ///
 199     /// # Examples
 200     ///
 201     /// Basic usage:
 202     ///
 203     /// ```
 204     /// assert_eq!('1'.to_digit(10), Some(1));
 205     /// assert_eq!('f'.to_digit(16), Some(15));
 206     /// ```
 207     ///
 208     /// Passing a non-digit results in failure:
 209     ///
 210     /// ```
 211     /// assert_eq!('f'.to_digit(10), None);
 212     /// assert_eq!('z'.to_digit(16), None);
 213     /// ```
 214     ///
 215     /// Passing a large radix, causing a panic:
 216     ///
 217     /// ```
 218     /// use std::thread;
 219     ///
 220     /// let result = thread::spawn(|| {
 221     ///     '1'.to_digit(37);
 222     /// }).join();
 223     ///
 224     /// assert!(result.is_err());
 225     /// ```
 226     #[stable(feature = "rust1", since = "1.0.0")]
 227     #[inline]
 228     pub fn to_digit(self, radix: u32) -> Option<u32> {
 229         C::to_digit(self, radix)
 230     }
 231
 232     /// Returns an iterator that yields the hexadecimal Unicode escape of a
 233     /// character, as `char`s.
 234     ///
 235     /// All characters are escaped with Rust syntax of the form `\\u{NNNN}`
 236     /// where `NNNN` is the shortest hexadecimal representation.
 237     ///
 238     /// # Examples
 239     ///
 240     /// Basic usage:
 241     ///
 242     /// ```
 243     /// for c in '❤'.escape_unicode() {
 244     ///     print!("{}", c);
 245     /// }
 246     /// println!("");
 247     /// ```
 248     ///
 249     /// This prints:
 250     ///
 251     /// ```text
 252     /// \u{2764}
 253     /// ```
 254     ///
 255     /// Collecting into a `String`:
 256     ///
 257     /// ```
 258     /// let heart: String = '❤'.escape_unicode().collect();
 259     ///
 260     /// assert_eq!(heart, r"\u{2764}");
 261     /// ```
 262     #[stable(feature = "rust1", since = "1.0.0")]
 263     #[inline]
 264     pub fn escape_unicode(self) -> EscapeUnicode {
 265         C::escape_unicode(self)
 266     }
 267
 268     /// Returns an iterator that yields the literal escape code of a `char`.
 269     ///
 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:
 273     ///
 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].
 284     ///
 285     /// [escape_unicode]: #method.escape_unicode
 286     ///
 287     /// # Examples
 288     ///
 289     /// Basic usage:
 290     ///
 291     /// ```
 292     /// for i in '"'.escape_default() {
 293     ///     println!("{}", i);
 294     /// }
 295     /// ```
 296     ///
 297     /// This prints:
 298     ///
 299     /// ```text
 300     /// \
 301     /// "
 302     /// ```
 303     ///
 304     /// Collecting into a `String`:
 305     ///
 306     /// ```
 307     /// let quote: String = '"'.escape_default().collect();
 308     ///
 309     /// assert_eq!(quote, "\\\"");
 310     /// ```
 311     #[stable(feature = "rust1", since = "1.0.0")]
 312     #[inline]
 313     pub fn escape_default(self) -> EscapeDefault {
 314         C::escape_default(self)
 315     }
 316
 317     /// Returns the number of bytes this `char` would need if encoded in UTF-8.
 318     ///
 319     /// That number of bytes is always between 1 and 4, inclusive.
 320     ///
 321     /// # Examples
 322     ///
 323     /// Basic usage:
 324     ///
 325     /// ```
 326     /// let len = 'A'.len_utf8();
 327     /// assert_eq!(len, 1);
 328     ///
 329     /// let len = 'ß'.len_utf8();
 330     /// assert_eq!(len, 2);
 331     ///
 332     /// let len = 'ℝ'.len_utf8();
 333     /// assert_eq!(len, 3);
 334     ///
 335     /// let len = '💣'.len_utf8();
 336     /// assert_eq!(len, 4);
 337     /// ```
 338     ///
 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:
 341     ///
 342     /// ```
 343     /// // as chars
 344     /// let eastern = '東';
 345     /// let capitol = '京';
 346     ///
 347     /// // both can be represented as three bytes
 348     /// assert_eq!(3, eastern.len_utf8());
 349     /// assert_eq!(3, capitol.len_utf8());
 350     ///
 351     /// // as a &str, these two are encoded in UTF-8
 352     /// let tokyo = "東京";
 353     ///
 354     /// let len = eastern.len_utf8() + capitol.len_utf8();
 355     ///
 356     /// // we can see that they take six bytes total...
 357     /// assert_eq!(6, tokyo.len());
 358     ///
 359     /// // ... just like the &str
 360     /// assert_eq!(len, tokyo.len());
 361     /// ```
 362     #[stable(feature = "rust1", since = "1.0.0")]
 363     #[inline]
 364     pub fn len_utf8(self) -> usize {
 365         C::len_utf8(self)
 366     }
 367
 368     /// Returns the number of 16-bit code units this `char` would need if
 369     /// encoded in UTF-16.
 370     ///
 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.
 373     ///
 374     /// [`len_utf8()`]: #method.len_utf8
 375     ///
 376     /// # Examples
 377     ///
 378     /// Basic usage:
 379     ///
 380     /// ```
 381     /// let n = 'ß'.len_utf16();
 382     /// assert_eq!(n, 1);
 383     ///
 384     /// let len = '💣'.len_utf16();
 385     /// assert_eq!(len, 2);
 386     /// ```
 387     #[stable(feature = "rust1", since = "1.0.0")]
 388     #[inline]
 389     pub fn len_utf16(self) -> usize {
 390         C::len_utf16(self)
 391     }
 392
 393     /// Returns an interator over the bytes of this character as UTF-8.
 394     ///
 395     /// The returned iterator also has an `as_slice()` method to view the
 396     /// encoded bytes as a byte slice.
 397     ///
 398     /// # Examples
 399     ///
 400     /// ```
 401     /// #![feature(unicode)]
 402     ///
 403     /// let iterator = 'ß'.encode_utf8();
 404     /// assert_eq!(iterator.as_slice(), [0xc3, 0x9f]);
 405     ///
 406     /// for (i, byte) in iterator.enumerate() {
 407     ///     println!("byte {}: {:x}", i, byte);
 408     /// }
 409     /// ```
 410     #[unstable(feature = "unicode", issue = "27784")]
 411     #[inline]
 412     pub fn encode_utf8(self) -> EncodeUtf8 {
 413         C::encode_utf8(self)
 414     }
 415
 416     /// Returns an interator over the `u16` entries of this character as UTF-16.
 417     ///
 418     /// The returned iterator also has an `as_slice()` method to view the
 419     /// encoded form as a slice.
 420     ///
 421     /// # Examples
 422     ///
 423     /// ```
 424     /// #![feature(unicode)]
 425     ///
 426     /// let iterator = '𝕊'.encode_utf16();
 427     /// assert_eq!(iterator.as_slice(), [0xd835, 0xdd4a]);
 428     ///
 429     /// for (i, val) in iterator.enumerate() {
 430     ///     println!("entry {}: {:x}", i, val);
 431     /// }
 432     /// ```
 433     #[unstable(feature = "unicode", issue = "27784")]
 434     #[inline]
 435     pub fn encode_utf16(self) -> EncodeUtf16 {
 436         C::encode_utf16(self)
 437     }
 438
 439     /// Returns true if this `char` is an alphabetic code point, and false if not.
 440     ///
 441     /// # Examples
 442     ///
 443     /// Basic usage:
 444     ///
 445     /// ```
 446     /// assert!('a'.is_alphabetic());
 447     /// assert!('京'.is_alphabetic());
 448     ///
 449     /// let c = '💝';
 450     /// // love is many things, but it is not alphabetic
 451     /// assert!(!c.is_alphabetic());
 452     /// ```
 453     #[stable(feature = "rust1", since = "1.0.0")]
 454     #[inline]
 455     pub fn is_alphabetic(self) -> bool {
 456         match self {
 457             'a'...'z' | 'A'...'Z' => true,
 458             c if c > '\x7f' => derived_property::Alphabetic(c),
 459             _ => false,
 460         }
 461     }
 462
 463     /// Returns true if this `char` satisfies the 'XID_Start' Unicode property, and false
 464     /// otherwise.
 465     ///
 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",
 471                issue = "0")]
 472     #[inline]
 473     pub fn is_xid_start(self) -> bool {
 474         derived_property::XID_Start(self)
 475     }
 476
 477     /// Returns true if this `char` satisfies the 'XID_Continue' Unicode property, and false
 478     /// otherwise.
 479     ///
 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",
 485                issue = "0")]
 486     #[inline]
 487     pub fn is_xid_continue(self) -> bool {
 488         derived_property::XID_Continue(self)
 489     }
 490
 491     /// Returns true if this `char` is lowercase, and false otherwise.
 492     ///
 493     /// 'Lowercase' is defined according to the terms of the Unicode Derived Core
 494     /// Property `Lowercase`.
 495     ///
 496     /// # Examples
 497     ///
 498     /// Basic usage:
 499     ///
 500     /// ```
 501     /// assert!('a'.is_lowercase());
 502     /// assert!('δ'.is_lowercase());
 503     /// assert!(!'A'.is_lowercase());
 504     /// assert!(!'Δ'.is_lowercase());
 505     ///
 506     /// // The various Chinese scripts do not have case, and so:
 507     /// assert!(!'中'.is_lowercase());
 508     /// ```
 509     #[stable(feature = "rust1", since = "1.0.0")]
 510     #[inline]
 511     pub fn is_lowercase(self) -> bool {
 512         match self {
 513             'a'...'z' => true,
 514             c if c > '\x7f' => derived_property::Lowercase(c),
 515             _ => false,
 516         }
 517     }
 518
 519     /// Returns true if this `char` is uppercase, and false otherwise.
 520     ///
 521     /// 'Uppercase' is defined according to the terms of the Unicode Derived Core
 522     /// Property `Uppercase`.
 523     ///
 524     /// # Examples
 525     ///
 526     /// Basic usage:
 527     ///
 528     /// ```
 529     /// assert!(!'a'.is_uppercase());
 530     /// assert!(!'δ'.is_uppercase());
 531     /// assert!('A'.is_uppercase());
 532     /// assert!('Δ'.is_uppercase());
 533     ///
 534     /// // The various Chinese scripts do not have case, and so:
 535     /// assert!(!'中'.is_uppercase());
 536     /// ```
 537     #[stable(feature = "rust1", since = "1.0.0")]
 538     #[inline]
 539     pub fn is_uppercase(self) -> bool {
 540         match self {
 541             'A'...'Z' => true,
 542             c if c > '\x7f' => derived_property::Uppercase(c),
 543             _ => false,
 544         }
 545     }
 546
 547     /// Returns true if this `char` is whitespace, and false otherwise.
 548     ///
 549     /// 'Whitespace' is defined according to the terms of the Unicode Derived Core
 550     /// Property `White_Space`.
 551     ///
 552     /// # Examples
 553     ///
 554     /// Basic usage:
 555     ///
 556     /// ```
 557     /// assert!(' '.is_whitespace());
 558     ///
 559     /// // a non-breaking space
 560     /// assert!('\u{A0}'.is_whitespace());
 561     ///
 562     /// assert!(!'越'.is_whitespace());
 563     /// ```
 564     #[stable(feature = "rust1", since = "1.0.0")]
 565     #[inline]
 566     pub fn is_whitespace(self) -> bool {
 567         match self {
 568             ' ' | '\x09'...'\x0d' => true,
 569             c if c > '\x7f' => property::White_Space(c),
 570             _ => false,
 571         }
 572     }
 573
 574     /// Returns true if this `char` is alphanumeric, and false otherwise.
 575     ///
 576     /// 'Alphanumeric'-ness is defined in terms of the Unicode General Categories
 577     /// 'Nd', 'Nl', 'No' and the Derived Core Property 'Alphabetic'.
 578     ///
 579     /// # Examples
 580     ///
 581     /// Basic usage:
 582     ///
 583     /// ```
 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());
 592     /// ```
 593     #[stable(feature = "rust1", since = "1.0.0")]
 594     #[inline]
 595     pub fn is_alphanumeric(self) -> bool {
 596         self.is_alphabetic() || self.is_numeric()
 597     }
 598
 599     /// Returns true if this `char` is a control code point, and false otherwise.
 600     ///
 601     /// 'Control code point' is defined in terms of the Unicode General
 602     /// Category `Cc`.
 603     ///
 604     /// # Examples
 605     ///
 606     /// Basic usage:
 607     ///
 608     /// ```
 609     /// // U+009C, STRING TERMINATOR
 610     /// assert!('\9c'.is_control());
 611     /// assert!(!'q'.is_control());
 612     /// ```
 613     #[stable(feature = "rust1", since = "1.0.0")]
 614     #[inline]
 615     pub fn is_control(self) -> bool {
 616         general_category::Cc(self)
 617     }
 618
 619     /// Returns true if this `char` is numeric, and false otherwise.
 620     ///
 621     /// 'Numeric'-ness is defined in terms of the Unicode General Categories
 622     /// 'Nd', 'Nl', 'No'.
 623     ///
 624     /// # Examples
 625     ///
 626     /// Basic usage:
 627     ///
 628     /// ```
 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());
 637     /// ```
 638     #[stable(feature = "rust1", since = "1.0.0")]
 639     #[inline]
 640     pub fn is_numeric(self) -> bool {
 641         match self {
 642             '0'...'9' => true,
 643             c if c > '\x7f' => general_category::N(c),
 644             _ => false,
 645         }
 646     }
 647
 648     /// Returns an iterator that yields the lowercase equivalent of a `char`.
 649     ///
 650     /// If no conversion is possible then an iterator with just the input character is returned.
 651     ///
 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.
 657     ///
 658     /// For a full reference, see [here][reference].
 659     ///
 660     /// [Unicode database]: ftp://ftp.unicode.org/Public/UNIDATA/UnicodeData.txt
 661     ///
 662     /// [`SpecialCasing.txt`]: ftp://ftp.unicode.org/Public/UNIDATA/SpecialCasing.txt
 663     ///
 664     /// [reference]: http://www.unicode.org/versions/Unicode7.0.0/ch03.pdf#G33992
 665     ///
 666     /// # Examples
 667     ///
 668     /// Basic usage:
 669     ///
 670     /// ```
 671     /// assert_eq!('C'.to_lowercase().next(), Some('c'));
 672     ///
 673     /// // Japanese scripts do not have case, and so:
 674     /// assert_eq!('山'.to_lowercase().next(), Some('山'));
 675     /// ```
 676     #[stable(feature = "rust1", since = "1.0.0")]
 677     #[inline]
 678     pub fn to_lowercase(self) -> ToLowercase {
 679         ToLowercase(CaseMappingIter::new(conversions::to_lower(self)))
 680     }
 681
 682     /// Returns an iterator that yields the uppercase equivalent of a `char`.
 683     ///
 684     /// If no conversion is possible then an iterator with just the input character is returned.
 685     ///
 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.
 691     ///
 692     /// For a full reference, see [here][reference].
 693     ///
 694     /// [Unicode database]: ftp://ftp.unicode.org/Public/UNIDATA/UnicodeData.txt
 695     ///
 696     /// [`SpecialCasing.txt`]: ftp://ftp.unicode.org/Public/UNIDATA/SpecialCasing.txt
 697     ///
 698     /// [reference]: http://www.unicode.org/versions/Unicode7.0.0/ch03.pdf#G33992
 699     ///
 700     /// # Examples
 701     ///
 702     /// Basic usage:
 703     ///
 704     /// ```
 705     /// assert_eq!('c'.to_uppercase().next(), Some('C'));
 706     ///
 707     /// // Japanese does not have case, and so:
 708     /// assert_eq!('山'.to_uppercase().next(), Some('山'));
 709     /// ```
 710     ///
 711     /// In Turkish, the equivalent of 'i' in Latin has five forms instead of two:
 712     ///
 713     /// * 'Dotless': I / ı, sometimes written ï
 714     /// * 'Dotted': İ / i
 715     ///
 716     /// Note that the lowercase dotted 'i' is the same as the Latin. Therefore:
 717     ///
 718     /// ```
 719     /// let upper_i = 'i'.to_uppercase().next();
 720     /// ```
 721     ///
 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:
 725     ///
 726     /// ```
 727     /// let upper_i = 'i'.to_uppercase().next();
 728     ///
 729     /// assert_eq!(Some('I'), upper_i);
 730     /// ```
 731     ///
 732     /// holds across languages.
 733     #[stable(feature = "rust1", since = "1.0.0")]
 734     #[inline]
 735     pub fn to_uppercase(self) -> ToUppercase {
 736         ToUppercase(CaseMappingIter::new(conversions::to_upper(self)))
 737     }
 738 }
 739
 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")]
 742 #[derive(Clone)]
 743 pub struct DecodeUtf16<I>
 744     where I: Iterator<Item = u16>
 745 {
 746     iter: I,
 747     buf: Option<u16>,
 748 }
 749
 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 {
 754     code: u16,
 755 }
 756
 757 /// Create an iterator over the UTF-16 encoded code points in `iter`,
 758 /// returning unpaired surrogates as `Err`s.
 759 ///
 760 /// # Examples
 761 ///
 762 /// Basic usage:
 763 ///
 764 /// ```
 765 /// use std::char::decode_utf16;
 766 ///
 767 /// fn main() {
 768 ///     // 𝄞mus<invalid>ic<invalid>
 769 ///     let v = [0xD834, 0xDD1E, 0x006d, 0x0075,
 770 ///              0x0073, 0xDD1E, 0x0069, 0x0063,
 771 ///              0xD834];
 772 ///
 773 ///     assert_eq!(decode_utf16(v.iter().cloned())
 774 ///                            .map(|r| r.map_err(|e| e.unpaired_surrogate()))
 775 ///                            .collect::<Vec<_>>(),
 776 ///                vec![Ok('𝄞'),
 777 ///                     Ok('m'), Ok('u'), Ok('s'),
 778 ///                     Err(0xDD1E),
 779 ///                     Ok('i'), Ok('c'),
 780 ///                     Err(0xD834)]);
 781 /// }
 782 /// ```
 783 ///
 784 /// A lossy decoder can be obtained by replacing `Err` results with the replacement character:
 785 ///
 786 /// ```
 787 /// use std::char::{decode_utf16, REPLACEMENT_CHARACTER};
 788 ///
 789 /// fn main() {
 790 ///     // 𝄞mus<invalid>ic<invalid>
 791 ///     let v = [0xD834, 0xDD1E, 0x006d, 0x0075,
 792 ///              0x0073, 0xDD1E, 0x0069, 0x0063,
 793 ///              0xD834];
 794 ///
 795 ///     assert_eq!(decode_utf16(v.iter().cloned())
 796 ///                    .map(|r| r.unwrap_or(REPLACEMENT_CHARACTER))
 797 ///                    .collect::<String>(),
 798 ///                "𝄞mus�ic�");
 799 /// }
 800 /// ```
 801 #[stable(feature = "decode_utf16", since = "1.9.0")]
 802 #[inline]
 803 pub fn decode_utf16<I: IntoIterator<Item = u16>>(iter: I) -> DecodeUtf16<I::IntoIter> {
 804     DecodeUtf16 {
 805         iter: iter.into_iter(),
 806         buf: None,
 807     }
 808 }
 809
 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>;
 813
 814     fn next(&mut self) -> Option<Result<char, DecodeUtf16Error>> {
 815         let u = match self.buf.take() {
 816             Some(buf) => buf,
 817             None => {
 818                 match self.iter.next() {
 819                     Some(u) => u,
 820                     None => return None,
 821                 }
 822             }
 823         };
 824
 825         if u < 0xD800 || 0xDFFF < u {
 826             // not a surrogate
 827             Some(Ok(unsafe { from_u32_unchecked(u as u32) }))
 828         } else if u >= 0xDC00 {
 829             // a trailing surrogate
 830             Some(Err(DecodeUtf16Error { code: u }))
 831         } else {
 832             let u2 = match self.iter.next() {
 833                 Some(u2) => u2,
 834                 // eof
 835                 None => return Some(Err(DecodeUtf16Error { code: u })),
 836             };
 837             if u2 < 0xDC00 || u2 > 0xDFFF {
 838                 // not a trailing surrogate so we're not a valid
 839                 // surrogate pair, so rewind to redecode u2 next time.
 840                 self.buf = Some(u2);
 841                 return Some(Err(DecodeUtf16Error { code: u }));
 842             }
 843
 844             // all ok, so lets decode it.
 845             let c = (((u - 0xD800) as u32) << 10 | (u2 - 0xDC00) as u32) + 0x1_0000;
 846             Some(Ok(unsafe { from_u32_unchecked(c) }))
 847         }
 848     }
 849
 850     #[inline]
 851     fn size_hint(&self) -> (usize, Option<usize>) {
 852         let (low, high) = self.iter.size_hint();
 853         // we could be entirely valid surrogates (2 elements per
 854         // char), or entirely non-surrogates (1 element per char)
 855         (low / 2, high)
 856     }
 857 }
 858
 859 impl DecodeUtf16Error {
 860     /// Returns the unpaired surrogate which caused this error.
 861     #[stable(feature = "decode_utf16", since = "1.9.0")]
 862     pub fn unpaired_surrogate(&self) -> u16 {
 863         self.code
 864     }
 865 }
 866
 867 #[stable(feature = "decode_utf16", since = "1.9.0")]
 868 impl fmt::Display for DecodeUtf16Error {
 869     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
 870         write!(f, "unpaired surrogate found: {:x}", self.code)
 871     }
 872 }
 873
 874 /// `U+FFFD REPLACEMENT CHARACTER` (�) is used in Unicode to represent a
 875 /// decoding error.
 876 ///
 877 /// It can occur, for example, when giving ill-formed UTF-8 bytes to
 878 /// [`String::from_utf8_lossy`](../../std/string/struct.String.html#method.from_utf8_lossy).
 879 #[stable(feature = "decode_utf16", since = "1.9.0")]
 880 pub const REPLACEMENT_CHARACTER: char = '\u{FFFD}';