qubit_fs/read/
prefix_read_outcome.rs

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

qubit_fs/read/
prefix_read_outcome.rs
