1 //! UTF-8 and UTF-16 decoding iterators
3 use crate::error
::Error
;
6 /// An iterator that decodes UTF-16 encoded code points from an iterator of `u16`s.
8 /// This `struct` is created by the [`decode_utf16`] method on [`char`]. See its
9 /// documentation for more.
11 /// [`decode_utf16`]: char::decode_utf16
12 #[stable(feature = "decode_utf16", since = "1.9.0")]
13 #[derive(Clone, Debug)]
14 pub struct DecodeUtf16
<I
>
16 I
: Iterator
<Item
= u16>,
22 /// An error that can be returned when decoding UTF-16 code points.
24 /// This `struct` is created when using the [`DecodeUtf16`] type.
25 #[stable(feature = "decode_utf16", since = "1.9.0")]
26 #[derive(Debug, Clone, Eq, PartialEq)]
27 pub struct DecodeUtf16Error
{
31 /// Creates an iterator over the UTF-16 encoded code points in `iter`,
32 /// returning unpaired surrogates as `Err`s. See [`char::decode_utf16`].
34 pub(super) fn decode_utf16
<I
: IntoIterator
<Item
= u16>>(iter
: I
) -> DecodeUtf16
<I
::IntoIter
> {
35 DecodeUtf16 { iter: iter.into_iter(), buf: None }
38 #[stable(feature = "decode_utf16", since = "1.9.0")]
39 impl<I
: Iterator
<Item
= u16>> Iterator
for DecodeUtf16
<I
> {
40 type Item
= Result
<char, DecodeUtf16Error
>;
42 fn next(&mut self) -> Option
<Result
<char, DecodeUtf16Error
>> {
43 let u
= match self.buf
.take() {
45 None
=> self.iter
.next()?
,
48 if !u
.is_utf16_surrogate() {
49 // SAFETY: not a surrogate
50 Some(Ok(unsafe { char::from_u32_unchecked(u as u32) }
))
51 } else if u
>= 0xDC00 {
52 // a trailing surrogate
53 Some(Err(DecodeUtf16Error { code: u }
))
55 let u2
= match self.iter
.next() {
58 None
=> return Some(Err(DecodeUtf16Error { code: u }
)),
60 if u2
< 0xDC00 || u2
> 0xDFFF {
61 // not a trailing surrogate so we're not a valid
62 // surrogate pair, so rewind to redecode u2 next time.
64 return Some(Err(DecodeUtf16Error { code: u }
));
67 // all ok, so lets decode it.
68 let c
= (((u
& 0x3ff) as u32) << 10 | (u2
& 0x3ff) as u32) + 0x1_0000;
69 // SAFETY: we checked that it's a legal unicode value
70 Some(Ok(unsafe { char::from_u32_unchecked(c) }
))
75 fn size_hint(&self) -> (usize, Option
<usize>) {
76 let (low
, high
) = self.iter
.size_hint();
78 let (low_buf
, high_buf
) = match self.buf
{
79 // buf is empty, no additional elements from it.
81 // `u` is a non surrogate, so it's always an additional character.
82 Some(u
) if !u
.is_utf16_surrogate() => (1, 1),
83 // `u` is a leading surrogate (it can never be a trailing surrogate and
84 // it's a surrogate due to the previous branch) and `self.iter` is empty.
86 // `u` can't be paired, since the `self.iter` is empty,
87 // so it will always become an additional element (error).
88 Some(_u
) if high
== Some(0) => (1, 1),
89 // `u` is a leading surrogate and `iter` may be non-empty.
91 // `u` can either pair with a trailing surrogate, in which case no additional elements
92 // are produced, or it can become an error, in which case it's an additional character (error).
96 // `self.iter` could contain entirely valid surrogates (2 elements per
97 // char), or entirely non-surrogates (1 element per char).
99 // On odd lower bound, at least one element must stay unpaired
100 // (with other elements from `self.iter`), so we round up.
101 let low
= low
.div_ceil(2) + low_buf
;
102 let high
= high
.and_then(|h
| h
.checked_add(high_buf
));
108 impl DecodeUtf16Error
{
109 /// Returns the unpaired surrogate which caused this error.
111 #[stable(feature = "decode_utf16", since = "1.9.0")]
112 pub fn unpaired_surrogate(&self) -> u16 {
117 #[stable(feature = "decode_utf16", since = "1.9.0")]
118 impl fmt
::Display
for DecodeUtf16Error
{
119 fn fmt(&self, f
: &mut fmt
::Formatter
<'_
>) -> fmt
::Result
{
120 write
!(f
, "unpaired surrogate found: {:x}", self.code
)
124 #[stable(feature = "decode_utf16", since = "1.9.0")]
125 impl Error
for DecodeUtf16Error
{
127 fn description(&self) -> &str {
128 "unpaired surrogate found"