]>
Commit | Line | Data |
---|---|---|
1b1a35ee XL |
1 | //! Defines utf8 error type. |
2 | ||
3 | use crate::fmt; | |
4 | ||
5 | /// Errors which can occur when attempting to interpret a sequence of [`u8`] | |
6 | /// as a string. | |
7 | /// | |
8 | /// As such, the `from_utf8` family of functions and methods for both [`String`]s | |
9 | /// and [`&str`]s make use of this error, for example. | |
10 | /// | |
11 | /// [`String`]: ../../std/string/struct.String.html#method.from_utf8 | |
12 | /// [`&str`]: super::from_utf8 | |
13 | /// | |
14 | /// # Examples | |
15 | /// | |
16 | /// This error type’s methods can be used to create functionality | |
17 | /// similar to `String::from_utf8_lossy` without allocating heap memory: | |
18 | /// | |
19 | /// ``` | |
20 | /// fn from_utf8_lossy<F>(mut input: &[u8], mut push: F) where F: FnMut(&str) { | |
21 | /// loop { | |
22 | /// match std::str::from_utf8(input) { | |
23 | /// Ok(valid) => { | |
24 | /// push(valid); | |
25 | /// break | |
26 | /// } | |
27 | /// Err(error) => { | |
28 | /// let (valid, after_valid) = input.split_at(error.valid_up_to()); | |
29 | /// unsafe { | |
30 | /// push(std::str::from_utf8_unchecked(valid)) | |
31 | /// } | |
32 | /// push("\u{FFFD}"); | |
33 | /// | |
34 | /// if let Some(invalid_sequence_length) = error.error_len() { | |
35 | /// input = &after_valid[invalid_sequence_length..] | |
36 | /// } else { | |
37 | /// break | |
38 | /// } | |
39 | /// } | |
40 | /// } | |
41 | /// } | |
42 | /// } | |
43 | /// ``` | |
44 | #[derive(Copy, Eq, PartialEq, Clone, Debug)] | |
45 | #[stable(feature = "rust1", since = "1.0.0")] | |
46 | pub struct Utf8Error { | |
47 | pub(super) valid_up_to: usize, | |
48 | pub(super) error_len: Option<u8>, | |
49 | } | |
50 | ||
51 | impl Utf8Error { | |
52 | /// Returns the index in the given string up to which valid UTF-8 was | |
53 | /// verified. | |
54 | /// | |
55 | /// It is the maximum index such that `from_utf8(&input[..index])` | |
56 | /// would return `Ok(_)`. | |
57 | /// | |
58 | /// # Examples | |
59 | /// | |
60 | /// Basic usage: | |
61 | /// | |
62 | /// ``` | |
63 | /// use std::str; | |
64 | /// | |
65 | /// // some invalid bytes, in a vector | |
66 | /// let sparkle_heart = vec![0, 159, 146, 150]; | |
67 | /// | |
68 | /// // std::str::from_utf8 returns a Utf8Error | |
69 | /// let error = str::from_utf8(&sparkle_heart).unwrap_err(); | |
70 | /// | |
71 | /// // the second byte is invalid here | |
72 | /// assert_eq!(1, error.valid_up_to()); | |
73 | /// ``` | |
74 | #[stable(feature = "utf8_error", since = "1.5.0")] | |
29967ef6 | 75 | #[inline] |
1b1a35ee XL |
76 | pub fn valid_up_to(&self) -> usize { |
77 | self.valid_up_to | |
78 | } | |
79 | ||
80 | /// Provides more information about the failure: | |
81 | /// | |
82 | /// * `None`: the end of the input was reached unexpectedly. | |
83 | /// `self.valid_up_to()` is 1 to 3 bytes from the end of the input. | |
84 | /// If a byte stream (such as a file or a network socket) is being decoded incrementally, | |
85 | /// this could be a valid `char` whose UTF-8 byte sequence is spanning multiple chunks. | |
86 | /// | |
87 | /// * `Some(len)`: an unexpected byte was encountered. | |
88 | /// The length provided is that of the invalid byte sequence | |
89 | /// that starts at the index given by `valid_up_to()`. | |
90 | /// Decoding should resume after that sequence | |
91 | /// (after inserting a [`U+FFFD REPLACEMENT CHARACTER`][U+FFFD]) in case of | |
92 | /// lossy decoding. | |
93 | /// | |
94 | /// [U+FFFD]: ../../std/char/constant.REPLACEMENT_CHARACTER.html | |
95 | #[stable(feature = "utf8_error_error_len", since = "1.20.0")] | |
29967ef6 | 96 | #[inline] |
1b1a35ee XL |
97 | pub fn error_len(&self) -> Option<usize> { |
98 | self.error_len.map(|len| len as usize) | |
99 | } | |
100 | } | |
101 | ||
102 | #[stable(feature = "rust1", since = "1.0.0")] | |
103 | impl fmt::Display for Utf8Error { | |
104 | fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { | |
105 | if let Some(error_len) = self.error_len { | |
106 | write!( | |
107 | f, | |
108 | "invalid utf-8 sequence of {} bytes from index {}", | |
109 | error_len, self.valid_up_to | |
110 | ) | |
111 | } else { | |
112 | write!(f, "incomplete utf-8 byte sequence from index {}", self.valid_up_to) | |
113 | } | |
114 | } | |
115 | } | |
116 | ||
117 | /// An error returned when parsing a `bool` using [`from_str`] fails | |
118 | /// | |
119 | /// [`from_str`]: super::FromStr::from_str | |
120 | #[derive(Debug, Clone, PartialEq, Eq)] | |
121 | #[stable(feature = "rust1", since = "1.0.0")] | |
122 | pub struct ParseBoolError { | |
123 | pub(super) _priv: (), | |
124 | } | |
125 | ||
126 | #[stable(feature = "rust1", since = "1.0.0")] | |
127 | impl fmt::Display for ParseBoolError { | |
128 | fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { | |
129 | "provided string was not `true` or `false`".fmt(f) | |
130 | } | |
131 | } |