Struct ExternalFiles 

pub struct ExternalFiles { /* private fields */ }

How a file name in an array pointer becomes a path on a disk.

Implementations

impl ExternalFiles

pub fn with_root(root: impl Into<PathBuf>) -> Self

Resolve relative names against this folder.

pub fn set( &mut self, name: impl Into<String>, path: impl Into<PathBuf>, ) -> &mut Self

Pin one name to a path, overriding whatever the package says.

For the packages whose HDF5 file was renamed, or moved, or never had the name the object claims - all of which happen.

pub fn offer(&mut self, path: impl Into<PathBuf>) -> &mut Self

Offer a file without saying what it is called.

The difference from set is the whole reason this exists. Pinning requires knowing the name the document uses, which is exactly what a person handed a renamed .h5 does not know and should not have to find out by opening the .rels in a text editor. Offering says only “the numbers might be in here”; the search opens it and looks.

Offers are tried in the order given, so a caller who knows which is likeliest can say so by putting it first.

pub fn offered(&self) -> &[PathBuf]

The files offered without a name, in order.

pub fn declare_present(&mut self, name: impl Into<String>) -> &mut Self

State that a file of this name is available, without saying where.

For a store that has no filesystem, which in practice means a browser. Everything else here answers “which path”, and every candidate is filtered on the path existing - which is false for all of them when there are no paths. Without this, the search yields nothing in a browser and no array is ever read, whatever backend is plugged in: the resolution would collapse silently one layer above the thing that was supposed to do the work.

So a declared name is a candidate whose path is the name itself. It goes nowhere on disk, and it is not meant to: a backend that lives outside this process - h5wasm behind ArrayBackend, holding the bytes in its own memory - receives that name and resolves it its own way.

The bytes deliberately do not come through here. Whoever decodes the format is who should hold them, and for HDF5 in a browser that is the JavaScript side; copying nineteen megabytes into this process so that it can hand them straight back out would buy nothing.

Named rather than offered, because a caller who has the file also knows what it is called - it is a file they picked or were given. A name that matches nothing in the package still gets its turn, under Origin::Offered, in the order declared.

pub fn present(&self) -> &[String]

The names declared present, in order.

pub fn is_virtual(&self) -> bool

Whether any name was declared present - the shape a store takes when it has no filesystem to resolve against.

pub fn candidates( &self, declared: &str, package: Option<&Path>, ) -> Vec<Candidate>

Every place worth looking for a dataset that the document says is in declared, most authoritative first.

Existence is filtered here; content is not. Whether a candidate actually holds the dataset is a question only a backend can answer, and asking it is the caller’s half of the job - see Origin for why the division matters.

package is the .epc itself when there is one on disk, which is what Origin::Companion is derived from and what is excluded from Origin::Neighbour.

pub fn root(&self) -> Option<&Path>

The folder relative names resolve against.

pub fn set_root(&mut self, root: impl Into<PathBuf>) -> &mut Self

Set the folder relative names resolve against.

pub fn resolve(&self, name: &str) -> Result<PathBuf>

Turn the name an array pointer carries into a path that exists.

pub fn destination_for(&self, name: &str) -> Result<PathBuf>

Where a file of this name would go, whether or not it is there yet.

ExternalFiles::resolve answers “where is it”, and every branch of it requires the file to exist - which is right for reading and useless for writing. This answers “where should it be written”, using the same precedence so that a file created here is found by resolve afterwards.

Errors when there is nowhere to put it: no override, not absolute, and no root. Inventing the working directory would scatter data files next to whatever the process happened to be run from.

Trait Implementations

impl Clone for ExternalFiles

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for ExternalFiles

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

Formats the value using the given formatter.

impl Default for ExternalFiles

fn default() -> Self

Returns the “default value” for a type.