qubit-fs 0.2.2

Provider-neutral synchronous and asynchronous filesystem abstraction for Rust
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104

// =============================================================================
//    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(())
/// # }
/// ```
#[derive(Debug)]
pub struct PrefixReadOutcome {
    bytes: Vec<u8>,
    info: OpenedFileInfo,
    options: ReadOptions,
    max_bytes: usize,
    termination: PrefixReadTermination,
}

impl PrefixReadOutcome {
    /// Creates a prefix result inside the facade.
    #[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.
    #[inline]
    #[must_use]
    pub fn bytes(&self) -> &[u8] {
        &self.bytes
    }

    /// Returns the information captured when the reader was opened.
    #[inline]
    #[must_use]
    pub const fn info(&self) -> &OpenedFileInfo {
        &self.info
    }

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

    /// Returns the requested prefix limit.
    #[inline]
    #[must_use]
    pub const fn max_bytes(&self) -> usize {
        self.max_bytes
    }

    /// Returns the reason the read stopped.
    #[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
    }
}