qubit-fs 0.3.2

Provider-neutral synchronous and asynchronous filesystem abstraction for Rust
Documentation
// =============================================================================
//    Copyright (c) 2026 Haixing Hu.
//
//    SPDX-License-Identifier: Apache-2.0
//
//    Licensed under the Apache License, Version 2.0.
// =============================================================================

//! Result of a bounded prefix read.

use crate::metadata::OpenedFileInfo;
use crate::read::PrefixReadTermination;
use crate::read::ReadOptions;

/// Bytes read from one opened resource together with bounded-read facts.
///
/// `LimitReached` means the requested bound was consumed without probing for
/// another byte; it does not prove that the stream has ended.
///
/// # Examples
///
/// ```rust
/// # fn main() -> Result<(), qubit_fs::FsError> {
/// use qubit_fs::Path;
/// use qubit_fs::read::PrefixReadTermination;
/// use qubit_fs::read::ReadOptions;
/// # mod support { include!(concat!(env!("CARGO_MANIFEST_DIR"), "/tests/common/rustdoc_support.rs")); }
/// let fs = support::rustdoc_provider::filesystem();
/// let outcome = fs.read_prefix(&Path::parse("/report")?, ReadOptions::default(), 3)?;
/// assert_eq!(outcome.bytes(), b"rep");
/// assert_eq!(outcome.termination(), PrefixReadTermination::LimitReached);
/// # Ok(())
/// # }
/// ```
#[must_use]
#[derive(Debug)]
pub struct PrefixReadOutcome {
    /// Bytes accumulated before the stream ended or the limit was reached.
    bytes: Vec<u8>,
    /// File identity and metadata captured when the reader was opened.
    info: OpenedFileInfo,
    /// Original options used to configure the read.
    options: ReadOptions,
    /// Maximum byte count requested for this prefix.
    max_bytes: usize,
    /// Whether the stream ended or the requested limit was consumed.
    termination: PrefixReadTermination,
}

impl PrefixReadOutcome {
    /// Creates a prefix result inside the facade.
    ///
    /// # Parameters
    /// - `bytes`: Bytes accumulated before the read stopped.
    /// - `info`: Resource identity and metadata captured when the reader
    ///   opened.
    /// - `options`: Read options retained for the operation.
    /// - `max_bytes`: Maximum number of bytes requested for the prefix.
    /// - `termination`: Reason the bounded read stopped.
    ///
    /// # Returns
    /// A prefix outcome containing the supplied read facts.
    #[inline]
    pub(crate) fn new(
        bytes: Vec<u8>,
        info: OpenedFileInfo,
        options: ReadOptions,
        max_bytes: usize,
        termination: PrefixReadTermination,
    ) -> Self {
        Self {
            bytes,
            info,
            options,
            max_bytes,
            termination,
        }
    }

    /// Returns the bytes without transferring ownership.
    ///
    /// # Returns
    /// The accumulated prefix bytes borrowed from this outcome.
    #[inline]
    #[must_use]
    pub fn bytes(&self) -> &[u8] {
        &self.bytes
    }

    /// Returns the information captured when the reader was opened.
    ///
    /// # Returns
    /// The resource identity and metadata snapshot captured at open time.
    #[inline]
    #[must_use]
    pub const fn info(&self) -> &OpenedFileInfo {
        &self.info
    }

    /// Returns the caller options retained for this read.
    ///
    /// # Returns
    /// The options used to configure this read.
    #[inline]
    #[must_use]
    pub const fn options(&self) -> &ReadOptions {
        &self.options
    }

    /// Returns the requested prefix limit.
    ///
    /// # Returns
    /// The maximum number of bytes requested for this prefix.
    #[inline]
    #[must_use]
    pub const fn max_bytes(&self) -> usize {
        self.max_bytes
    }

    /// Returns the reason the read stopped.
    ///
    /// # Returns
    /// The termination state recorded by the bounded read.
    #[inline]
    #[must_use]
    pub const fn termination(&self) -> PrefixReadTermination {
        self.termination
    }

    /// Transfers the accumulated bytes without another allocation.
    #[inline]
    #[must_use]
    pub fn into_bytes(self) -> Vec<u8> {
        self.bytes
    }
}