Skip to main content

FileContent

Enum FileContent 

Source
#[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
Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.
§

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.

Fields

§len: u64

The file’s length in bytes.

§key: u64

The caller’s name for the file, handed back with the place its bytes go.

Implementations§

Source§

impl FileContent

Source

pub fn len(&self) -> u64

The file’s length in bytes, without reading it.

Source

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.

Source

pub fn is_empty(&self) -> bool

Whether the file is empty.

Source

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

Source§

fn clone(&self) -> FileContent

Returns a duplicate of the value. Read more
1.0.0 (const: unstable) · Source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more
Source§

impl Debug for FileContent

Source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more
Source§

impl Eq for FileContent

Source§

impl<const N: usize> From<&[u8; N]> for FileContent

Source§

fn from(bytes: &[u8; N]) -> Self

Converts to this type from the input type.
Source§

impl From<&[u8]> for FileContent

Source§

fn from(bytes: &[u8]) -> Self

Converts to this type from the input type.
Source§

impl From<&str> for FileContent

Source§

fn from(text: &str) -> Self

Converts to this type from the input type.
Source§

impl From<FileRange> for FileContent

Source§

fn from(range: FileRange) -> Self

Converts to this type from the input type.
Source§

impl From<ImageFile> for FileContent

Source§

fn from(file: ImageFile) -> Self

Converts to this type from the input type.
Source§

impl From<String> for FileContent

Source§

fn from(text: String) -> Self

Converts to this type from the input type.
Source§

impl From<Vec<u8>> for FileContent

Source§

fn from(bytes: Vec<u8>) -> Self

Converts to this type from the input type.
Source§

impl PartialEq for FileContent

Source§

fn eq(&self, other: &FileContent) -> bool

Equality operator ==. Read more
1.0.0 (const: unstable) · Source§

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=. Read more
Source§

impl StructuralPartialEq for FileContent

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = Infallible

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.