#[non_exhaustive]pub enum FileContent {
Owned(Vec<u8>),
Range(FileRange),
Image(ImageFile),
Declared {
len: u64,
key: u64,
},
}Expand description
A regular file’s contents: bytes in memory, a range of a file on the host read at the moment it is placed, a file in an image this crate reads, read the same way, or a length alone, whose bytes a caller writing the image supplies.
The first two coexist in one entry list, deliberately. A source that maps an on-host archive
yields handles; a caller that computes an entry’s bytes — rewriting one file of a tree
it is otherwise passing through — supplies them owned, in the same Vec<SourceEntry>.
§Why this is not just Vec<u8>
A format’s peak memory is otherwise the sum of every file it writes, because every file’s bytes are built before the first block is placed. A handle defers the bytes until the file is written, and a writer places a handle’s bytes a window at a time, so what a file costs in memory while it is placed is one window rather than its length.
The len is known without reading, which is what lets the model check a
file against the large_file feature — and name the offending path — before any bytes
are read.
Variants (Non-exhaustive)§
This enum is marked as non-exhaustive
Owned(Vec<u8>)
Bytes held in memory.
Range(FileRange)
A range of a file on the host, read when the content is placed.
Image(ImageFile)
A file in an image this crate reads, read from the image when the content is placed:
what an ImageSource gives a regular file.
Declared
A file declared by its length alone. The source holds none of its bytes: a caller
that writes the image itself puts them where the plan places the file, and knows the
file by key, which it chose.
Only a plan that hands its writes back to the caller can place one, which is the exFAT
family’s FormatPlan::stages. Every other family’s writer reads a file’s bytes itself,
and refuses a declared one when the plan is made.
Implementations§
Source§impl FileContent
impl FileContent
Sourcepub fn read_at(&self, at: u64, buf: &mut [u8]) -> Result<()>
pub fn read_at(&self, at: u64, buf: &mut [u8]) -> Result<()>
Fill buf with the file’s bytes from offset at onward.
The read names its own position, so a caller copying a large file through a buffer of its choosing holds that buffer and nothing else.
§Errors
std::io::ErrorKind::InvalidInput if at plus the buffer’s length runs past the
end of the file, and otherwise what FileRange::read_at reports for a range and
ImageFile::read_at for a file in an image. An owned
entry fails only on the bound. A declared one is std::io::ErrorKind::Unsupported,
since it has no bytes to read.
Sourcepub fn read(&self) -> Result<Cow<'_, [u8]>>
pub fn read(&self) -> Result<Cow<'_, [u8]>>
The file’s bytes, reading them from the host if they are not already in memory.
Bytes already held are borrowed, not copied: reading an Owned
entry costs nothing, so a caller that reads every entry in turn never holds two
copies of one file. Only a Range and an Image
allocate, and only for as long as the caller keeps what it returned — the whole file
at once, which read_at is the bounded alternative to.
§Errors
std::io::Error if the backing file cannot be read — including the case where
it is shorter than the range claims, which means the file changed after the source
that named it was built. An owned entry cannot fail.
Trait Implementations§
Source§impl Clone for FileContent
impl Clone for FileContent
Source§fn clone(&self) -> FileContent
fn clone(&self) -> FileContent
1.0.0 (const: unstable) · Source§fn clone_from(&mut self, source: &Self)
fn clone_from(&mut self, source: &Self)
source. Read more