pub struct PBO { /* private fields */ }Expand description
PBO file
§Examples
let pbo = PBO::from_directory(Path::new("src"), &PackOptions::pack(), None, &mut Warnings::new()).expect("Failed to create PBO");
assert!(pbo.entry_names().any(|name| name == "lib.rs"));
let mut cursor = pbo.to_cursor().unwrap();
let reread = PBO::read(&mut cursor).unwrap();
assert!(reread.checksum().is_some());Implementations§
Source§impl PBO
impl PBO
Sourcepub fn entries(&self) -> impl Iterator<Item = (&str, &[u8])>
pub fn entries(&self) -> impl Iterator<Item = (&str, &[u8])>
The entries in the order the PBO has them: header order for a PBO that was read and not
modified, the order PBO::write uses (sorted by name) for any other. Data is as stored, so
compressed entries stay compressed; see PBO::file_data.
Sourcepub fn entry_names(&self) -> impl Iterator<Item = &str>
pub fn entry_names(&self) -> impl Iterator<Item = &str>
The entry names, in the order of PBO::entries.
Sourcepub fn insert_entry(
&mut self,
name: impl Into<String>,
data: Vec<u8>,
) -> Result<(), Error>
pub fn insert_entry( &mut self, name: impl Into<String>, data: Vec<u8>, ) -> Result<(), Error>
Adds an entry, or replaces the data of the entry with the same name. Replacing an existing entry also replaces its stored name bytes with the new name’s.
§Errors
/ in the name is stored as \. Returns an error if the name has an empty component
(leading, trailing or doubled separator, or no name at all) or is one
safe_relative_path rejects (drive letter, .. component and so on). Modifying a PBO
that was read drops its stored checksum: it is signed as the PBO that would be written.
Sourcepub fn remove_entry(&mut self, name: &str) -> Option<Vec<u8>>
pub fn remove_entry(&mut self, name: &str) -> Option<Vec<u8>>
Removes an entry and returns its stored data.
Sourcepub fn header_extensions(&self) -> impl Iterator<Item = (&str, &str)>
pub fn header_extensions(&self) -> impl Iterator<Item = (&str, &str)>
The header extensions (key=value) in file order, including the prefix.
Sourcepub fn header_extension(&self, key: &str) -> Option<&str>
pub fn header_extension(&self, key: &str) -> Option<&str>
The value of a header extension.
Sourcepub fn set_header_extension(
&mut self,
key: impl Into<String>,
value: impl Into<String>,
)
pub fn set_header_extension( &mut self, key: impl Into<String>, value: impl Into<String>, )
Sets a header extension; a repeated key keeps its position and takes the new value.
Sourcepub fn checksum(&self) -> Option<&[u8]>
pub fn checksum(&self) -> Option<&[u8]>
The SHA-1 trailer of a PBO that was read and not modified; None otherwise.
Sourcepub fn computed_checksum(&self) -> Option<&[u8]>
pub fn computed_checksum(&self) -> Option<&[u8]>
The SHA-1 of the bytes of a PBO that was read and not modified (header block and entry
data, everything before the trailer); None otherwise. A PBO whose stored
checksum differs from it is corrupt or was tampered with.
Sourcepub fn entry_headers(&self) -> Vec<EntryHeader>
pub fn entry_headers(&self) -> Vec<EntryHeader>
The entry headers of a PBO that was read, in header order (empty for one made by
PBO::from_directory).
Sourcepub fn name_bytes(&self, name: &str) -> Vec<u8> ⓘ
pub fn name_bytes(&self, name: &str) -> Vec<u8> ⓘ
Returns the bytes an entry name is stored as in the PBO header.
Sourcepub fn header_extensions_bytes(&self) -> Vec<(Vec<u8>, Vec<u8>)>
pub fn header_extensions_bytes(&self) -> Vec<(Vec<u8>, Vec<u8>)>
The header extensions as (key, value) bytes, in the order of PBO::header_extensions:
what the PBO header stores for a PBO that was read (a value set since is its UTF-8 bytes),
the UTF-8 bytes of the strings otherwise. A repeated key has the bytes of its
first key and its last value.
Sourcepub fn read_headers<I: Read>(input: &mut I) -> Result<HeaderSummary, Error>
pub fn read_headers<I: Read>(input: &mut I) -> Result<HeaderSummary, Error>
Reads only the header block of a PBO: the header extensions and the entry names, in file order. The entry data is never read, so this is cheap for PBOs of any size. Pass a buffered reader.
The input is untrusted: every name is limited to MAX_HEADER_STRING bytes, the number of entries
and extensions are limited, and nothing is allocated from a size in the file.
§Errors
Returns an error if the header block is truncated, malformed or exceeds the limits.
The extensions are (key, value) pairs in file order.
Sourcepub fn read_entries<I: Read + Seek>(
input: &mut I,
wanted: impl Fn(&str) -> bool,
) -> Result<PboSelection, Error>
pub fn read_entries<I: Read + Seek>( input: &mut I, wanted: impl Fn(&str) -> bool, ) -> Result<PboSelection, Error>
Reads the header block of a seekable PBO and only the entries wanted accepts, by seeking to their
data. Memory use is bounded by the selected entries, not by the size of the PBO, which can be many
hundred MB.
The input is untrusted: the header block is bounded like read_headers, and an entry whose data
selected for reading does not lie inside the file is an error (nothing is allocated from a size before it is checked
against the file length).
§Errors
Returns an error if the header block is malformed or exceeds the limits, or the data of a selected entry is truncated.
Sourcepub fn read_entries_tolerant<I: Read + Seek>(
input: &mut I,
wanted: impl Fn(&str) -> bool,
options: &TolerantRead,
) -> Result<PboSelection, Error>
pub fn read_entries_tolerant<I: Read + Seek>( input: &mut I, wanted: impl Fn(&str) -> bool, options: &TolerantRead, ) -> Result<PboSelection, Error>
Like PBO::read_entries, but a damaged entry does not fail the whole selection, and the
selection is bounded.
A selected entry whose data is truncated or cannot be decompressed is an error of its own
(SelectedEntry::data). The decompressed sizes of the selected entries are added up in file
order; the first entry that would take the total past TolerantRead::max_bytes is not read, and neither is any
selected entry after it (a smaller later one included); each reports SelectedEntry::is_over_limit. A malformed header
block is still an error.
§Errors
Returns an error if the header block is malformed or exceeds the limits, or the entry sizes overflow.
Sourcepub fn from_directory(
directory: &Path,
options: &PackOptions,
binarizer: Option<&mut Binarizer>,
warnings: &mut dyn WarningSink,
) -> Result<PBO, Error>
pub fn from_directory( directory: &Path, options: &PackOptions, binarizer: Option<&mut Binarizer>, warnings: &mut dyn WarningSink, ) -> Result<PBO, Error>
Constructs a PBO from a directory, binarizing and rapifying where options.build is set.
options.exclude contains glob patterns to exclude from the PBO, options.include_folders
the paths to search recursively for absolute includes and options.direct_include_folders the paths
checked only directly (generally the current working directory). options.header_extensions are applied after $PBOPREFIX$; for the same key
the option wins. A $NOBIN$ file in the directory turns build off. Models are only
binarized when a binarizer is given; without one they are copied as-is with a warning.
§Errors
Returns an error if the directory cannot be read or a file cannot be processed.
Sourcepub fn write<O: Write>(&self, output: &mut O) -> Result<(), Error>
pub fn write<O: Write>(&self, output: &mut O) -> Result<(), Error>
Writes PBO to output.
§Errors
Returns an error on I/O failure, if an entry is too large, or if a header extension key or value contains a NUL byte.
Trait Implementations§
Auto Trait Implementations§
impl Freeze for PBO
impl RefUnwindSafe for PBO
impl Send for PBO
impl Sync for PBO
impl Unpin for PBO
impl UnsafeUnpin for PBO
impl UnwindSafe for PBO
Blanket Implementations§
Source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
Source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
impl<ST, DT> CastableFrom<ST, Initialized, Initialized> for DT
impl<ST, DT> CastableFrom<ST, Uninit, Uninit> for DT
Source§impl<T> IntoEither for T
impl<T> IntoEither for T
Source§fn into_either(self, into_left: bool) -> Either<Self, Self> ⓘ
fn into_either(self, into_left: bool) -> Either<Self, Self> ⓘ
self into a Left variant of Either<Self, Self>
if into_left is true.
Converts self into a Right variant of Either<Self, Self>
otherwise. Read moreSource§fn into_either_with<F>(self, into_left: F) -> Either<Self, Self> ⓘ
fn into_either_with<F>(self, into_left: F) -> Either<Self, Self> ⓘ
self into a Left variant of Either<Self, Self>
if into_left(&self) returns true.
Converts self into a Right variant of Either<Self, Self>
otherwise. Read more§impl<T> Pointable for T
impl<T> Pointable for T
impl<T> Read<Exclusive, BecauseExclusive> for Twhere
T: ?Sized,
Source§impl<R, P> ReadPrimitive<R> for P
impl<R, P> ReadPrimitive<R> for P
Source§fn read_from_little_endian(read: &mut R) -> Result<Self, Error>
fn read_from_little_endian(read: &mut R) -> Result<Self, Error>
ReadEndian::read_from_little_endian().