index.nct

//! Buffered file I/O.
//!
//! Fallible flushes are always explicit. Dropping a writer discards an
//! unflushed buffer instead of hiding an I/O failure in destruction.

use /io.{File, Reader, Writer}
use /string.String
see ./buffering.nct

/// An owning buffered reader with explicit line state.
pub struct BufReader

construct BufReader {
    /// Wraps `source` with the default positive buffer capacity.
    pub func new(source: File): Self

    /// Wraps `source`, normalizing a zero requested capacity to one byte.
    pub func with_capacity(source: File, requested_capacity: usize): Self
}

instance BufReader {
    /// Returns one owned line without its LF or immediately preceding CR.
    pub method &+self.read_line(): String?!

    /// Replaces `destination` with one line and reports false only at clean end of stream.
    pub method &+self.read_line_into(destination: &+String): bool!

    /// Closes the source and makes every later read observe end of stream.
    pub method &+self.close(): void

    impl Reader
}

/// An owning buffered writer whose fallible flush remains explicit.
pub struct BufWriter

construct BufWriter {
    /// Wraps `destination` with the default positive buffer capacity.
    pub func new(destination: File): Self

    /// Wraps `destination`, normalizing a zero requested capacity to one byte.
    pub func with_capacity(destination: File, requested_capacity: usize): Self
}

instance BufWriter {
    /// Flushes pending bytes, closes the destination, and makes this writer terminal.
    pub method &+self.close(): void!
    impl Writer
}