Skip to main content

Graph

Struct Graph 

Source
pub struct Graph { /* private fields */ }
Expand description

An in-memory registry of formats and directed conversion edges.

Registration validates metadata, not adapter availability or file contents. Search is read-only; no adapter or external process is executed.

Implementations§

Source§

impl Graph

Source

pub fn new() -> Graph

Create an empty format graph.

Source

pub fn add_format(&mut self, format: Format) -> Result<(), PlanError>

Register a lowercase ASCII ID of 1..=64 bytes using letters, digits, -, _, ., or +. Extensions follow the same rules after normalization. Duplicate IDs merge sorted, unique extensions and keep the lexicographically smallest name. Conflicting media categories are rejected without changes. The first registration’s decode_only flag is retained for duplicate IDs.

§Errors

Returns PlanError::Invalid for invalid IDs or aliases, or a conflicting media category. The graph is unchanged on error.

Source

pub fn add_conversion( &mut self, conversion: Conversion, ) -> Result<(), PlanError>

Register an edge between existing IDs. * is allowed only as the input of a Reinterpret or Package edge and matches every registered format. Identical edges are idempotent; distinct parallel edges are retained.

Endpoint IDs are exact and case-sensitive, not extension aliases. Content requirements and produced kinds (Conversion::requires, Conversion::produces) are normalized and must use lowercase codec tags that satisfy the same character rules as format IDs. This method does not verify that the named backend implements the operation.

§Errors

Returns PlanError::Invalid for zero cost, blank backend or operation, an unsupported wildcard kind, or an invalid content codec tag. Returns PlanError::UnknownFormat for unregistered endpoints. The graph is unchanged on error.

Source

pub fn formats(&self) -> impl Iterator<Item = &Format>

Iterate in ascending format ID order.

Source

pub fn conversions(&self) -> impl Iterator<Item = &Conversion>

Iterate every registered edge, sorted by source ID then edge order.

Source

pub fn format(&self, id: &str) -> Option<&Format>

Look up an exact, case-sensitive registered ID.

Source

pub fn resolve(&self, value: &str) -> Option<&Format>

Resolve a trimmed, case-insensitive ID, extension, or MIME type, optionally dot-prefixed.

Exact IDs take precedence, then extension aliases, then MIME types that contain a slash. Ambiguous values select the smallest format ID. This does not interpret paths.

Source

pub fn routes( &self, from: &str, to: &str, policy: &Policy, ) -> Result<Vec<Plan>, PlanError>

Enumerate cheapest loopless routes using policy-filtered A* search. Inputs are resolved as IDs or extension aliases. Equal formats yield one empty, zero-cost plan unless Policy::reencode_same_format is set, in which case a nonempty route returning to the source format is searched. Policy limits above their hard caps are clamped.

Each path retains its own visited formats, so parallel edges and alternative prefixes remain eligible. At most max_expansions candidate edges are examined, with shared prefixes rather than copied plans. Equal estimated costs favor higher spent cost, then deterministic insertion order (specific edges before wildcard edges, each ordered by the fields of Conversion).

Policy::backends and Policy::retain prune edges inside the search, in both the reverse distance pass and the forward expansion, rather than filtering the returned plans. Policy::require is enforced through the target format’s declared Format::payloads and each edge’s Conversion::produces claim.

Reaching the expansion limit returns routes already found, even if fewer than requested. If none have been found, it returns SearchLimit. Exhausting the search without a route returns NoRoute, including the step-limit case. Identity routes do not apply edge or decode-only gates. A successful plan is a metadata route, not proof that execution will succeed.

§Errors

Returns PlanError::UnknownFormat for an unresolved endpoint, PlanError::Invalid for zero max_routes, PlanError::NoRoute when no permitted route exists within the step budget, or PlanError::SearchLimit when the edge budget is exhausted before a route is found. Partial results carry no separate truncation indicator.

Source

pub fn routes_with_profile( &self, from: &str, to: &str, policy: &Policy, profile: Option<&ContentProfile>, ) -> Result<Vec<Plan>, PlanError>

Enumerate routes with an observed ContentProfile for the source file.

Behaves exactly like Self::routes, except that edges leaving the profiled source format are also gated on their Conversion::requires content: each requirement must be satisfied by some stream in profile (matched through ContentKind::matches), instead of trusted against the source format’s declared Format::payloads. An edge whose source is not profile.format is unaffected. With no profile available, edges that declare requirements fall back to the source format’s payloads unless Policy::require_content is set, in which case any edge with source content requirements is pruned because its claims are unverified. Policy::require matches the target’s observed profile when profile.format equals the resolved target, otherwise the target’s declared payloads and edge Conversion::produces claims.

The graph never opens files; callers obtain profile from an engine inspection (for example convert_rs::Converter::profile) that reads stream metadata through adapters.

§Errors

As Self::routes.

Trait Implementations§

Source§

impl Clone for Graph

Source§

fn clone(&self) -> Graph

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 Graph

Source§

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

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

impl Default for Graph

Source§

fn default() -> Graph

Returns the “default value” for a type. Read more

Auto Trait Implementations§

§

impl Forget for Graph

§

impl Freeze for Graph

§

impl RefUnwindSafe for Graph

§

impl Send for Graph

§

impl Sync for Graph

§

impl Unpin for Graph

§

impl UnsafeUnpin for Graph

§

impl UnwindSafe for Graph

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<ST, DT> CastableFrom<ST, Initialized, Initialized> for DT
where ST: ?Sized, DT: ?Sized,

Source§

impl<ST, DT> CastableFrom<ST, Uninit, Uninit> for DT
where ST: ?Sized, DT: ?Sized,

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<F, T> IntoSample<T> for F
where T: FromSample<F>,

Source§

fn into_sample(self) -> T

Source§

impl<T> Read<Exclusive, BecauseExclusive> for T
where T: ?Sized,

Source§

impl<R, P> ReadPrimitive<R> for P
where R: Read + ReadEndian<P>, P: Default,

Source§

fn read_from_little_endian(read: &mut R) -> Result<Self, Error>

Read this value from the supplied reader. Same as ReadEndian::read_from_little_endian().
Source§

fn read_from_big_endian(read: &mut R) -> Result<Self, Error>

Read this value from the supplied reader. Same as ReadEndian::read_from_big_endian().
Source§

fn read_from_native_endian(read: &mut R) -> Result<Self, Error>

Read this value from the supplied reader. Same as ReadEndian::read_from_native_endian().
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 = !

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

fn try_from(value: U) -> Result<T, !>

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.