qubit_text_io/traits/
text_write.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 ******************************************************************************/
10use crate::LineEnding;
11
12/// Writes Unicode text to a text sink.
13///
14/// `TextWrite` accepts Rust Unicode text and delegates byte encoding, storage,
15/// logging, or other sink-specific behavior to the concrete implementation.
16pub trait TextWrite {
17    /// Error returned by this text sink.
18    type Error;
19
20    /// Returns the configured line ending for [`TextWrite::write_line`].
21    ///
22    /// # Returns
23    /// The configured line ending. Implementations default to [`LineEnding::Lf`].
24    #[must_use]
25    fn line_ending(&self) -> LineEnding {
26        LineEnding::Lf
27    }
28
29    /// Writes one Unicode scalar value.
30    ///
31    /// # Parameters
32    /// - `ch`: Character to write.
33    ///
34    /// # Errors
35    /// Returns an implementation-specific error when the character cannot be
36    /// accepted by the sink.
37    fn write_char(&mut self, ch: char) -> Result<(), Self::Error>;
38
39    /// Writes a slice of Unicode scalar values.
40    ///
41    /// # Parameters
42    /// - `chars`: Characters to write in order.
43    ///
44    /// # Errors
45    /// Returns an implementation-specific error when any character cannot be
46    /// accepted by the sink.
47    fn write_chars(&mut self, chars: &[char]) -> Result<(), Self::Error>;
48
49    /// Writes a string slice.
50    ///
51    /// # Parameters
52    /// - `text`: Text to write.
53    ///
54    /// # Errors
55    /// Returns an implementation-specific error when the text cannot be accepted
56    /// by the sink.
57    fn write_str(&mut self, text: &str) -> Result<(), Self::Error>;
58
59    /// Writes a line followed by the configured line ending.
60    ///
61    /// # Parameters
62    /// - `line`: Line content to write. The configured line ending is appended.
63    ///
64    /// # Errors
65    /// Returns an implementation-specific error when the line or line ending
66    /// cannot be accepted by the sink.
67    fn write_line(&mut self, line: &str) -> Result<(), Self::Error>;
68
69    /// Flushes buffered text to the underlying sink.
70    ///
71    /// # Errors
72    /// Returns an implementation-specific error when flushing fails.
73    fn flush(&mut self) -> Result<(), Self::Error>;
74}
qubit_text_io/traits/text_write.rs

qubit_text_io/traits/
text_write.rs
