qubit_fs/read/
prefix_read_outcome.rs

1// =============================================================================
2//    Copyright (c) 2026 Haixing Hu.
3//
4//    SPDX-License-Identifier: Apache-2.0
5// =============================================================================
6
7//! Result of a bounded prefix read.
8
9use crate::metadata::OpenedFileInfo;
10use crate::read::PrefixReadTermination;
11use crate::read::ReadOptions;
12
13/// Bytes read from one opened resource together with bounded-read facts.
14///
15/// `LimitReached` means the requested bound was consumed without probing for
16/// another byte; it does not prove that the stream has ended.
17///
18/// # Examples
19///
20/// ```rust
21/// # fn main() -> Result<(), qubit_fs::FsError> {
22/// use qubit_fs::Path;
23/// use qubit_fs::read::PrefixReadTermination;
24/// use qubit_fs::read::ReadOptions;
25/// # mod support { include!(concat!(env!("CARGO_MANIFEST_DIR"), "/tests/common/rustdoc_support.rs")); }
26/// let fs = support::rustdoc_provider::filesystem();
27/// let outcome = fs.read_prefix(&Path::parse("/report")?, ReadOptions::default(), 3)?;
28/// assert_eq!(outcome.bytes(), b"rep");
29/// assert_eq!(outcome.termination(), PrefixReadTermination::LimitReached);
30/// # Ok(())
31/// # }
32/// ```
33#[derive(Debug)]
34pub struct PrefixReadOutcome {
35    bytes: Vec<u8>,
36    info: OpenedFileInfo,
37    options: ReadOptions,
38    max_bytes: usize,
39    termination: PrefixReadTermination,
40}
41
42impl PrefixReadOutcome {
43    /// Creates a prefix result inside the facade.
44    #[inline]
45    pub(crate) fn new(
46        bytes: Vec<u8>,
47        info: OpenedFileInfo,
48        options: ReadOptions,
49        max_bytes: usize,
50        termination: PrefixReadTermination,
51    ) -> Self {
52        Self {
53            bytes,
54            info,
55            options,
56            max_bytes,
57            termination,
58        }
59    }
60
61    /// Returns the bytes without transferring ownership.
62    #[inline]
63    #[must_use]
64    pub fn bytes(&self) -> &[u8] {
65        &self.bytes
66    }
67
68    /// Returns the information captured when the reader was opened.
69    #[inline]
70    #[must_use]
71    pub const fn info(&self) -> &OpenedFileInfo {
72        &self.info
73    }
74
75    /// Returns the caller options retained for this read.
76    #[inline]
77    #[must_use]
78    pub const fn options(&self) -> &ReadOptions {
79        &self.options
80    }
81
82    /// Returns the requested prefix limit.
83    #[inline]
84    #[must_use]
85    pub const fn max_bytes(&self) -> usize {
86        self.max_bytes
87    }
88
89    /// Returns the reason the read stopped.
90    #[inline]
91    #[must_use]
92    pub const fn termination(&self) -> PrefixReadTermination {
93        self.termination
94    }
95
96    /// Transfers the accumulated bytes without another allocation.
97    #[inline]
98    #[must_use]
99    pub fn into_bytes(self) -> Vec<u8> {
100        self.bytes
101    }
102}
qubit_fs/read/prefix_read_outcome.rs

qubit_fs/read/
prefix_read_outcome.rs
