Struct Id 

pub struct Id { /* private fields */ }

Identifier.

Identifiers are structured string-based representations which are used to uniquely identify artifacts as they move through streams and stores. They use a compact, yet human-readable format that is easy to generate and parse, and consists of the following six components:

• provider, e.g., file or git.
• resource, e.g., volume, branch or tag.
• variant, e.g., language, version or format.
• context, e.g., source or output directory.
• location, e.g., file or folder.
• fragment, e.g., line number or anchor.

Identifiers implement Eq, PartialEq and Hash, as well as Ord and PartialOrd, so they can be stored in ordered and unordered storages, as well as efficiently compared with each other. The structured string-based representation is defined as follows:

zri:<provider>:<resource>:<variant>:<context>:<location>:<fragment>

This ensures blazing fast cloning and editing. Additionally, identifiers are guaranteed to not contain backslashes or path traversals in components. An empty component, for those that are allowed to remain empty, is equal to the default in the context set by the given provider.

Examples

Create an identifier:

use zrx_id::Id;

// Create identifier builder
let builder = Id::builder()
    .provider("file")
    .context("docs")
    .location("index.md");

// Create identifier from builder
let id = builder.build()?;
assert_eq!(id.as_str(), "zri:file:::docs:index.md:");

Create an identifier from a string:

use zrx_id::Id;

// Create identifier from string
let id: Id = "zri:file:::docs:index.md:".parse()?;

Implementations

impl Id

pub fn builder<'a>() -> Builder<'a>

Creates an identifier builder.

Examples

use zrx_id::Id;

// Create identifier builder
let builder = Id::builder();

pub fn to_builder(&self) -> Builder<'_>

Creates a builder from the identifier.

This method creates a builder from the current identifier, which allows to modify components and build a new identifier from an existing one.

Examples

use zrx_id::Id;

// Create identifier from string
let id: Id = "zri:file:::docs:index.md:".parse()?;

// Create identifier builder
let builder = id.to_builder().location("README.md");

// Create identifier from builder
let id = builder.build()?;
assert_eq!(id.as_str(), "zri:file:::docs:README.md:");

impl Id

pub fn to_path(&self) -> PathBuf

Converts the identifier to a relative file system path.

This method creates a relative PathBuf from both, the context and location components of the identifier, using platform-dependent path separators. The resulting path is always relative, and never absolute, since both, context and location, are always relative.

In order to resolve the path, the Id::resource needs to be taken into account, which is of course provider-specific. Note that for use of paths in URLs, Id::as_uri must be used, which guarantees that all path separators are forward slashes.

Examples

use std::path::Path;
use zrx_id::Id;

// Create identifier from string
let id: Id = "zri:file:::docs:index.md:".parse()?;

// Create path from identifier
let path = id.to_path();
assert_eq!(path, Path::new("docs/index.md"));

pub fn as_str(&self) -> &str

Returns the string representation.

Examples

use zrx_id::Id;

// Create identifier from string
let id: Id = "zri:file:::docs:index.md:".parse()?;

// Obtain string representation
assert_eq!(id.as_str(), "zri:file:::docs:index.md:");

pub fn as_uri(&self) -> Uri<'_>

Returns the URI representation.

This method creates a URI from Id::location, which is necessary for using the identifier in URLs, e.g., to construct relative links.

Examples

use zrx_id::uri::Uri;
use zrx_id::Id;

// Create identifier from string
let id: Id = "zri:file:::docs:index.md:".parse()?;

// Obtain URI representation
assert_eq!(id.as_uri(), Uri::from("index.md"));

impl Id

pub fn provider(&self) -> Cow<'_, str>

Returns the provider component.

pub fn resource(&self) -> Option<Cow<'_, str>>

Returns the resource component, if any.

pub fn variant(&self) -> Option<Cow<'_, str>>

Returns the variant component, if any.

pub fn context(&self) -> Cow<'_, str>

Returns the context component.

pub fn location(&self) -> Cow<'_, str>

Returns the location component.

pub fn fragment(&self) -> Option<Cow<'_, str>>

Returns the fragment component, if any.

Trait Implementations

impl AsRef<Format<7>> for Id

fn as_ref(&self) -> &Format<7>

Returns the formatted string.

Note that it’s normally not necessary to access the formatted string directly, as all components can be accessed via the respective methods. We need to access the underlying formatted string in our internal APIs, e.g., to compute the Specificity for the given Id.

impl Clone for Id

fn clone(&self) -> Id

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Id

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

Formats the identifier for debugging.

impl Display for Id

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

Formats the identifier for display.

impl From<Id> for Term

fn from(id: Id) -> Self

Creates a term from an identifier.

impl FromStr for Id

fn from_str(value: &str) -> Result<Self>

Attempts to create an identifier from a string.

The string must adhere to the following format and include exactly six : separators, even in case some components are omitted. The optional components are resource, variant and fragment, and can be left empty, which is represented as empty strings internally.

zri:<provider>:<resource>:<variant>:<context>:<location>:<fragment>

Errors

Returns Error::Component if any of the provider, context or location components are not set, and Error::Prefix if the prefix isn’t zri. On low-level format errors, Error::Format is returned.

Examples

use zrx_id::Id;

// Create identifier from string
let id: Id = "zri:file:::docs:index.md:".parse()?;

type Err = Error

The associated error which can be returned from parsing.

impl Hash for Id

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

where H: Hasher,

Hashes the identifier.

Since identifiers are immutable, we can use a precomputed hash for fast hashing. This is especially useful when identifiers are used as keys in hash maps or hash sets, where hashing is a frequent operation, as the performance gains are significant with constant time.

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

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Ord for Id

fn cmp(&self, other: &Self) -> Ordering

Orders two identifiers.

Examples

use zrx_id::Id;

// Create and compare identifiers
let a: Id = "zri:file:::docs:index.md:".parse()?;
let b: Id = "zri:file:::docs:about.md:".parse()?;
assert!(a > b);

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl PartialEq for Id

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

Compares two identifiers for equality.

Examples

use zrx_id::Id;

// Create and compare identifiers
let a: Id = "zri:file:::docs:index.md:".parse()?;
let b: Id = "zri:file:::docs:index.md:".parse()?;
assert_eq!(a, b);

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

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

impl PartialOrd for Id

fn partial_cmp(&self, other: &Self) -> Option<Ordering>

Orders two identifiers.

Examples

use zrx_id::Id;

// Create and compare identifiers
let a: Id = "zri:file:::docs:index.md:".parse()?;
let b: Id = "zri:file:::docs:about.md:".parse()?;
assert!(a > b);

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

Tests less than (for self and other) and is used by the < operator.

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

Tests less than or equal to (for self and other) and is used by the <= operator.

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

Tests greater than (for self and other) and is used by the > operator.

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

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl ToSpecificity for Id

fn to_specificity(&self) -> Specificity

Computes the specificity of the identifier.

Examples

use zrx_id::id;
use zrx_id::specificity::ToSpecificity;

// Create identifier and compute specificity
let id = id!(provider = "file", context = ".", location = "index.md")?;
assert_eq!(id.to_specificity(), (3, 0, 0, 13).into());

impl TryFrom<Id> for Selector

fn try_from(id: Id) -> Result<Self>

Attempts to create a selector from an identifier.

An Id can be converted into a Selector because all identifiers are also valid selectors, as they represent exact matches. However, the reverse is not true, as selectors can contain wildcards, as well as optional components, which identifiers cannot.

Examples

use zrx_id::{Id, Selector};

// Create selector from identifier
let id: Id = "zri:file:::docs:index.md:".parse()?;
let selector: Selector = id.try_into()?;

type Error = Error

The type returned in the event of a conversion error.

impl TryToId for Id

fn try_to_id(&self) -> Result<Cow<'_, Id>>

Attempts to convert to an identifier.

impl TryToSelector for Id

fn try_to_selector(&self) -> Result<Cow<'_, Selector>>

Attempts to convert to a selector.

Since all identifiers are also valid selectors, implementing this trait ensures we can also pass identifier references to Builder::add.

Examples

use zrx_id::{Id, Selector, TryToSelector};

// Create selector from identifier
let id: Id = "zri:file:::docs:index.md:".parse()?;
let selector = (&id).try_to_selector()?;

impl Eq for Id

impl Value for Id