utf8_read/
types.rs

1//a Imports
2use crate::StreamPosition;
3
4//a Character result and error
5//tp Char
6/// [Char] represents a unicode character, insufficient data, or an EOF marker
7///
8/// It is returned, for example, by the [next_char](crate::Reader::next_char) method.
9#[derive(Debug, Copy, Clone, PartialEq, Eq)]
10pub enum Char {
11    /// [Eof](Char::Eof) indicates end of stream/file reached; once a reader
12    /// returns Eof, it should continue to do so
13    Eof,
14    /// [NoData](Char::NoData) indicates that the stream/file did not supply data,
15    /// but this is configured to not be EOF.
16    ///
17    /// This can only be returned
18    /// by the reader if [crate::Reader::set_eof_on_no_data] has been used
19    NoData,
20    /// [Char](Char::Char) indicates a char of a valid Unicode codepoint decoded
21    /// from the stream with UTF8
22    Char(char)
23}
24
25//ip std::fmt::Display for Char
26impl std::fmt::Display for Char {
27    //mp fmt - format a character for display
28    /// Display the character as either the character itself, or '<EOF>'
29    fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
30        use std::fmt::Write; // for f.write_char
31        match self {
32            Char::Eof      => write!(f, "<EOF>"),
33            Char::NoData   => write!(f, "<NoData>"),
34            Char::Char(ch) => f.write_char(*ch),
35        }
36    }
37}
38
39//a Result
40//tp Result
41/// The [Result] type is a result with an error type of [crate::Error]
42pub type Result<T> = std::result::Result<T, Error>;
43
44//a Error
45//tp Error
46/// [Error] represents an error from the UTF-8 character reader,
47/// either an IO error from the reader or a malformed UTF-8 encoded
48/// set of bytes.
49#[derive(Debug)]
50pub enum Error {
51    /// An [IoError](std::io::Error) is passed through from the underlying read object.
52    IoError(std::io::Error),
53    /// A [MalformedUtf8](Error::MalformedUtf8) error occurs when a byte stream contains
54    /// invalid UTF-8; the position within the stream of the Unicode decoding error is
55    /// recorded, and the number of bytes that form the invalid UTF-8
56    /// encoding (which will be from 1 to 3).
57    MalformedUtf8(StreamPosition, usize),
58}
59
60//ip Error
61impl Error {
62    //mp malformedutf8
63    /// Create an error for a malformed UTF8 decoding within a stream
64    pub fn malformed_utf8<T>(stream_pos:StreamPosition, num_bytes:usize) -> Result<T> {
65        Err(Self::MalformedUtf8(stream_pos, num_bytes))
66    }
67}
68
69//ip From<std::io::Error> for Error
70/// Provides an implicit conversion from a std::io::Error to a Error
71impl From<std::io::Error> for Error {
72    fn from(e: std::io::Error) -> Self {
73        Error::IoError(e)
74    }
75}
76
77//ip std::fmt::Display for Error
78impl std::fmt::Display for Error {
79    //mp fmt - format a `Error` for display
80    /// Display the `Error` in a human-readable form
81    fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
82        match self {
83            Error::MalformedUtf8(pos, n) => write!(f, "malformed UTF-8 of {} bytes at {}", n, pos),
84            Error::IoError(e) => write!(f, "IO error: {}", e),
85        }
86    }
87}
88
89//ip std::error::Error for Error
90impl std::error::Error for Error {
91    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
92        match self {
93            Error::IoError(e) => Some(e),
94            _ => None,
95        }
96    }
97}
utf8_read/types.rs

utf8_read/
types.rs
