qubit_text_io/traits/
text_read.rs

1/*******************************************************************************
2 *
3 *    Copyright (c) 2026 Haixing Hu.
4 *
5 *    SPDX-License-Identifier: Apache-2.0
6 *
7 *    Licensed under the Apache License, Version 2.0.
8 *
9 ******************************************************************************/
10/// Reads Unicode scalar values and strings from a text source.
11///
12/// `TextRead` operates on Rust [`char`] and [`str`] values. Implementations are
13/// responsible for decoding any external byte encoding before exposing text to
14/// callers.
15pub trait TextRead {
16    /// Error returned by this text source.
17    type Error;
18
19    /// Reads the next Unicode scalar value.
20    ///
21    /// # Returns
22    /// `Ok(Some(ch))` when a scalar value was read, or `Ok(None)` at EOF.
23    ///
24    /// # Errors
25    /// Returns an implementation-specific error when the source cannot be read
26    /// or cannot be decoded as text according to its policy.
27    fn read_char(&mut self) -> Result<Option<char>, Self::Error>;
28
29    /// Reads up to `max` Unicode scalar values into `output`.
30    ///
31    /// # Parameters
32    /// - `output`: Destination vector. Read characters are appended.
33    /// - `max`: Maximum number of characters to read.
34    ///
35    /// # Returns
36    /// The number of characters appended to `output`.
37    ///
38    /// # Errors
39    /// Returns an implementation-specific error when reading a character fails.
40    fn read_chars(&mut self, output: &mut Vec<char>, max: usize) -> Result<usize, Self::Error>;
41
42    /// Reads all remaining text into `output`.
43    ///
44    /// # Parameters
45    /// - `output`: Destination string. Text is appended to the existing content.
46    ///
47    /// # Returns
48    /// The number of Unicode scalar values appended to `output`.
49    ///
50    /// # Errors
51    /// Returns an implementation-specific error when the source cannot be read
52    /// or decoded.
53    fn read_to_string(&mut self, output: &mut String) -> Result<usize, Self::Error>;
54}
qubit_text_io/traits/text_read.rs

qubit_text_io/traits/
text_read.rs
