]> git.proxmox.com Git - rustc.git/blob - src/librustc_unicode/char.rs
Imported Upstream version 1.9.0+dfsg1
[rustc.git] / 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::{derived_property, property, general_category, conversions};
34
35 // stable reexports
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};
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 => match self.iter.next() {
818 Some(u) => u,
819 None => return None,
820 },
821 };
822
823 if u < 0xD800 || 0xDFFF < u {
824 // not a surrogate
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 }))
829 } else {
830 let u2 = match self.iter.next() {
831 Some(u2) => u2,
832 // eof
833 None => return Some(Err(DecodeUtf16Error { code: u })),
834 };
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.
838 self.buf = Some(u2);
839 return Some(Err(DecodeUtf16Error { code: u }));
840 }
841
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) }))
845 }
846 }
847
848 #[inline]
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)
853 (low / 2, high)
854 }
855 }
856
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 {
861 self.code
862 }
863 }
864
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)
869 }
870 }
871
872 /// `U+FFFD REPLACEMENT CHARACTER` (�) is used in Unicode to represent a
873 /// decoding error.
874 ///
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}';