Struct FileUri

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

Version-one filesystem URI with a normalized scheme, optional authority, and path.

Paths use /, collapse repeated separators, and always start with /. This is deliberately a small VFS syntax rather than a complete RFC URI implementation: queries/fragments are unsupported, dot segments are not resolved, and only % and spaces are encoded/decoded by path helpers. Constructor methods establish these invariants, but derived deserialization stores the three fields verbatim and can therefore produce an unnormalized or otherwise invalid value. Only deserialize data from a trusted compatible producer when later code relies on normalized paths.

§Examples

use ailloli_ui_fs::FileUri;
let uri = FileUri::parse("SFTP://host//srv/project")?;
assert_eq!(uri.to_string(), "sftp://host/srv/project");

Implementations§

Source§

impl FileUri

Source

pub fn parse(input: impl AsRef<str>) -> Result<Self, FileError>

Parses and normalizes a version-one filesystem URI.

Outer whitespace is trimmed and the scheme is lowercased. The input must contain ://, a non-empty target, and no literal ? or #. Backslashes in the path become / and repeated slashes collapse. Authority text and existing percent escapes are otherwise retained verbatim.

§Errors

Returns FileError::InvalidUri for empty input, a missing/invalid scheme or path, a missing path after an authority, or a query/fragment.

§Examples
use ailloli_ui_fs::FileUri;
let uri = FileUri::parse(" file:///tmp/a%20b ")?;
assert_eq!(uri.path(), "/tmp/a%20b");
assert!(FileUri::parse("file:///tmp/a?raw=1").is_err());
Source

pub fn local(path: impl Into<PathBuf>) -> Result<Self, FileError>

Converts an absolute local path into an authority-free file URI.

The path must be valid UTF-8. Percent signs are encoded as %25, spaces as %20, and platform separators normalize to /; other URI-reserved characters are left verbatim. Relative paths are rejected.

§Errors

Returns FileError::InvalidUri for a relative or non-UTF-8 path.

§Examples
use ailloli_ui_fs::FileUri;
let uri = FileUri::local("/tmp/a b")?;
assert_eq!(uri.to_string(), "file:///tmp/a%20b");
assert!(FileUri::local("relative/path").is_err());
Source

pub fn new( scheme: impl Into<String>, authority: Option<impl Into<String>>, path: impl Into<String>, ) -> Result<Self, FileError>

Builds a URI from components using the crate’s normalization rules.

An empty authority becomes None. Relative path text is accepted and receives a leading /; backslashes and repeated separators normalize. Existing percent escapes, dot segments, ?, and # are not validated.

§Errors

Returns FileError::InvalidUri only when the normalized scheme is empty or contains a character outside ASCII alphanumeric, +, -, ..

§Examples
use ailloli_ui_fs::FileUri;
let uri = FileUri::new("SFTP", Some("host"), "srv\\project")?;
assert_eq!(uri.to_string(), "sftp://host/srv/project");
Source

pub fn scheme(&self) -> &str

Returns the normalized lowercase scheme.

§Examples
use ailloli_ui_fs::FileUri;
assert_eq!(FileUri::parse("FILE:///")?.scheme(), "file");
Source

pub fn authority(&self) -> Option<&str>

Returns the authority, or None for authority-free URIs.

Authority comparison is case-sensitive and no host normalization occurs.

§Examples
use ailloli_ui_fs::FileUri;
assert_eq!(FileUri::parse("sftp://host/home")?.authority(), Some("host"));
assert_eq!(FileUri::parse("file:///tmp")?.authority(), None);
Source

pub fn path(&self) -> &str

Returns the normalized, absolute, still-percent-encoded path.

§Examples
use ailloli_ui_fs::FileUri;
assert_eq!(FileUri::parse("file:////tmp//a")?.path(), "/tmp/a");
Source

pub fn file_name(&self) -> Option<&str>

Returns the final non-empty encoded path segment.

Root returns None; a trailing slash is ignored. No allocation or percent decoding occurs.

§Examples
use ailloli_ui_fs::FileUri;
assert_eq!(FileUri::parse("file:///tmp/a%20b/")?.file_name(), Some("a%20b"));
assert_eq!(FileUri::parse("file:///")?.file_name(), None);
Source

pub fn file_name_decoded(&self) -> Option<String>

Returns an allocated, partially percent-decoded final segment.

Decoding replaces uppercase %20 with spaces and %25 with %, in that order. Other escapes, lowercase forms, and malformed escapes remain unchanged. Root returns None.

§Examples
use ailloli_ui_fs::FileUri;
assert_eq!(FileUri::parse("file:///a%20b")?.file_name_decoded().as_deref(), Some("a b"));
Source

pub fn parent(&self) -> Option<Self>

Returns the normalized lexical parent while preserving scheme/authority.

Files directly below root return the root URI; root itself returns None. Dot segments are ordinary text and are not resolved.

§Examples
use ailloli_ui_fs::FileUri;
let uri = FileUri::parse("file:///tmp/a")?;
assert_eq!(uri.parent().unwrap().to_string(), "file:///tmp");
Source

pub fn join_child(&self, name: impl AsRef<str>) -> Result<Self, FileError>

Appends one trimmed child name and encodes percent signs and spaces.

Empty names and names containing / or \ are rejected. Other URI delimiters and dot names are accepted verbatim, so a child containing ? or # may not round-trip through Self::parse.

§Errors

Returns FileError::InvalidUri for an empty or multi-segment name, or if rebuilding the URI fails.

§Examples
use ailloli_ui_fs::FileUri;
let root = FileUri::parse("file:///tmp")?;
assert_eq!(root.join_child(" a b ")?.to_string(), "file:///tmp/a%20b");
assert!(root.join_child("a/b").is_err());
Source

pub fn with_file_name(&self, name: impl AsRef<str>) -> Result<Self, FileError>

Replaces the final segment using Self::join_child name rules.

§Errors

Returns FileError::InvalidUri when this URI is root or the new name is empty or contains a path separator.

§Examples
use ailloli_ui_fs::FileUri;
let uri = FileUri::parse("file:///tmp/a")?;
assert_eq!(uri.with_file_name("b")?.to_string(), "file:///tmp/b");
assert!(FileUri::parse("file:///")?.with_file_name("b").is_err());
Source

pub fn relative_path_from(&self, root: &Self) -> Option<String>

Returns a decoded lexical path relative to root when compatible.

Scheme and authority must match exactly, and self must equal or be below the root on a path-segment boundary. Equal non-root paths return "."; equal root or trailing-slash paths return an empty string due to normalization semantics. The result uses the same limited decoding as Self::file_name_decoded.

§Examples
use ailloli_ui_fs::FileUri;
let root = FileUri::parse("file:///tmp/work")?;
let child = FileUri::parse("file:///tmp/work/a%20b")?;
assert_eq!(child.relative_path_from(&root).as_deref(), Some("a b"));
assert_eq!(root.relative_path_from(&root).as_deref(), Some("."));
Source

pub fn to_local_path(&self) -> Result<PathBuf, FileError>

Converts an authority-free or localhost file URI to a local path.

Authority matching is case-sensitive. Percent decoding is intentionally limited to uppercase %20 and %25; no existence check is performed.

§Errors

Returns FileError::UnsupportedScheme for non-file schemes or a non-empty authority other than exact localhost.

§Examples
use ailloli_ui_fs::FileUri;
use std::path::PathBuf;
assert_eq!(FileUri::parse("file://localhost/tmp/a%20b")?.to_local_path()?, PathBuf::from("/tmp/a b"));
assert!(FileUri::parse("sftp://host/tmp")?.to_local_path().is_err());

Trait Implementations§

Source§

impl Clone for FileUri

Source§

fn clone(&self) -> FileUri

Returns a copy of the value. Read more
1.0.0 · Source§

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

Performs copy-assignment from source. Read more
Source§

impl Debug for FileUri

Source§

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

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

impl<'de> Deserialize<'de> for FileUri

Source§

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>
where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer. Read more
Source§

impl Display for FileUri

Source§

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

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

impl FromStr for FileUri

Source§

type Err = FileError

The associated error which can be returned from parsing.
Source§

fn from_str(s: &str) -> Result<Self, Self::Err>

Parses a string s to return a value of this type. Read more
Source§

impl Hash for FileUri

Source§

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher. Read more
1.3.0 · Source§

fn hash_slice<H>(data: &[Self], state: &mut H)
where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher. Read more
Source§

impl PartialEq for FileUri

Source§

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

Tests for self and other values to be equal, and is used by ==.
1.0.0 · Source§

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.
Source§

impl Serialize for FileUri

Source§

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>
where __S: Serializer,

Serialize this value into the given Serde serializer. Read more
Source§

impl Eq for FileUri

Source§

impl StructuralPartialEq for FileUri

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> ToString for T
where T: Display + ?Sized,

Source§

fn to_string(&self) -> String

Converts the given value to a String. 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.
Source§

impl<T> DeserializeOwned for T
where T: for<'de> Deserialize<'de>,