qubit_fs/temp/
temp_file.rs

1/*******************************************************************************
2 *
3 *    Copyright (c) 2026 Haixing Hu.
4 *
5 *    SPDX-License-Identifier: Apache-2.0
6 *
7 *    Licensed under the Apache License, Version 2.0.
8 *
9 ******************************************************************************/
10//! Temporary file handle trait.
11
12use crate::{
13    FileReader,
14    FileSystemExt,
15    FileWriter,
16    FsPath,
17    FsResult,
18    PersistOptions,
19    ReadOptions,
20    TempResource,
21    WriteOptions,
22    WriteOutcome,
23};
24
25/// Temporary file handle with cleanup responsibility.
26pub trait TempFile: TempResource {
27    /// Opens the temporary file for reading.
28    ///
29    /// # Parameters
30    /// - `options`: Read options.
31    ///
32    /// # Returns
33    /// Reader handle opened by the owning filesystem.
34    ///
35    /// # Errors
36    /// Returns [`crate::FsError`] when the owning filesystem cannot open the
37    /// temporary file for reading.
38    fn open_reader(&self, options: &ReadOptions) -> FsResult<Box<dyn FileReader>> {
39        self.fs().as_ref().open_reader(self.path(), options)
40    }
41
42    /// Opens the temporary file for writing.
43    ///
44    /// # Parameters
45    /// - `options`: Write options.
46    ///
47    /// # Returns
48    /// Writer handle opened by the owning filesystem.
49    ///
50    /// # Errors
51    /// Returns [`crate::FsError`] when the owning filesystem cannot open the
52    /// temporary file for writing.
53    fn open_writer(&self, options: &WriteOptions) -> FsResult<Box<dyn FileWriter>> {
54        self.fs().as_ref().open_writer(self.path(), options)
55    }
56
57    /// Reads the whole temporary file into memory.
58    ///
59    /// # Returns
60    /// Complete temporary file bytes.
61    ///
62    /// # Errors
63    /// Returns [`crate::FsError`] when opening or reading fails.
64    fn read_all(&self) -> FsResult<Vec<u8>> {
65        self.fs().as_ref().read_all(self.path())
66    }
67
68    /// Writes all bytes to the temporary file and commits the writer.
69    ///
70    /// # Parameters
71    /// - `bytes`: Bytes to write.
72    ///
73    /// # Returns
74    /// Write outcome reported by the owning filesystem.
75    ///
76    /// # Errors
77    /// Returns [`crate::FsError`] when opening, writing, aborting, or committing
78    /// fails.
79    fn write_all(&self, bytes: &[u8]) -> FsResult<WriteOutcome> {
80        self.fs().as_ref().write_all(self.path(), bytes)
81    }
82
83    /// Persists the temporary file to a target path.
84    ///
85    /// # Parameters
86    /// - `target`: Final target path.
87    /// - `options`: Persistence options.
88    ///
89    /// # Returns
90    /// Write outcome for the persisted resource.
91    ///
92    /// # Errors
93    /// Returns [`crate::FsError`] when persistence fails.
94    fn persist(self: Box<Self>, target: &FsPath, options: &PersistOptions) -> FsResult<WriteOutcome>;
95}
qubit_fs/temp/temp_file.rs

qubit_fs/temp/
temp_file.rs
