Struct sophia_term::iri::Iri

pub struct Iri<TD: TermData> { /* fields omitted */ }

Representation of an IRI.

May be encountered when pattern-matching on Terms of the Iri variant. For that purpose, note that Iri

• can be directly compared to a &str with the == operator;
• can be directly compared to a Term with the == operator;
• provides some identical methods to what &str provides (see below);
• can otherwise be converted to a String with to_string;

Contract

Each Iri represents a valid IRI reference according to the RFC3987 either relative or absolute. For building static IRIs an unsafe API is exposed. These do not do anything actual unsafe. Instead, they do not perform validity checks. It is the obligation of the user to ensure that invocations of *_unchecked() methods produce valid output. Note that the creation of invalid IRIs may lead to unexpected errors in other places.

Methods

impl<TD> Iri<TD> where
    TD: TermData, 

pub fn new<U>(iri: U) -> Result<Self> where
    U: AsRef<str>,
    TD: From<U>, 

Return a new IRI-term from a given IRI.

It is checked if the input is either an absolute or relative IRI. If it is none of them an error is returned.

pub fn new_suffixed<U, V>(ns: U, suffix: V) -> Result<Self> where
    U: AsRef<str>,
    V: AsRef<str>,
    TD: From<U> + From<V>, 

Return a new IRI-term from a given namespace and suffix.

It is checked if the input is either an absolute or relative IRI. If it is none of them an error is returned.

Performance

In order to check if the concatenation of namespace and suffix results in a valid IRI a new String is allocated and namespace and suffix are copied into it.

pub fn new_unchecked<U>(iri: U, absolute: bool) -> Self where
    TD: From<U>, 

Create a new IRI-term from a given IRI without checking its validity.

As it is not checked if absolute or relative this property must be entered as well.

Pre-condition

This function conducts no checks if the resulting IRI is valid. This is a contract that is generally assumed. Breaking it could result in unexpected behavior.

However, in debug builds assertions that perform checks are enabled.

pub fn new_suffixed_unchecked<U, V>(ns: U, suffix: V, absolute: bool) -> Self where
    TD: From<U> + From<V>, 

Create a new IRI-term from a given namespace and suffix.

As it is not checked if absolute or relative this property must be entered as well.

Pre-conditions

It is expected that

• the resulting IRI is valid per RFC3987,
• suffix is not the empty string (otherwise, new_unchecked should be used instead).

This is a contract that is generally assumed. Breaking it could result in unexpected behavior. However in debug mode, assertions that perform checks are enabled.

pub fn ns(&self) -> &TD

The namespace of the IRI.

If the IRI has no suffix this is the whole IRI.

pub fn suffix(&self) -> &Option<TD>

The suffix of the IRI.

pub fn as_ref(&self) -> Iri<&TD>

Borrow the inner contents of the IRI.

pub fn as_ref_str(&self) -> Iri<&str>

Borrow the inner contents of the IRI as &str.

pub fn map<F, TD2>(self, f: F) -> Iri<TD2> where
    F: FnMut(TD) -> TD2,
    TD2: TermData, 

Create a new IRI by applying f to the TermData of self.

pub fn map_into<TD2>(self) -> Iri<TD2> where
    TD: Into<TD2>,
    TD2: TermData, 

Maps the IRI using the Into trait.

pub fn clone_map<'a, U, F>(&'a self, factory: F) -> Iri<U> where
    U: TermData,
    F: FnMut(&'a str) -> U, 

Clone self while transforming the inner TermData with the given factory.

This is done in one step in contrast to calling clone().map(factory).

pub fn clone_into<'src, U>(&'src self) -> Iri<U> where
    U: TermData + From<&'src str>, 

Apply clone_map() using the Into trait.

pub fn len(&self) -> usize

The length of this IRI.

pub fn is_empty(&self) -> bool

Deprecated:

An empty IRI is not a valid one

Checks if the IRI is empty

pub fn bytes(&self) -> impl '_ + Iterator<Item = u8>

Iterate over the bytes representing this IRI.

pub fn chars(&self) -> impl '_ + Iterator<Item = char>

Iterate over the characters representing this IRI.

pub fn is_absolute(&self) -> bool

Whether this IRI is absolute or relative.

pub fn has_suffix(&self) -> bool

Whether this IRI is is composed of a whole IRI (false) or a namespace and a suffix (true).

pub fn normalized(&self, policy: Normalization) -> Iri<MownStr>

Return an IRI equivalent to this one, internally represented with all its data in ns, and an empty suffix.

Performances

The returned IRI will borrow data from this one as much as possible, but strings may be allocated in case a concatenation is required.

pub fn normalized_no_suffix(&self) -> Iri<MownStr>

Return an IRI equivalent to this one, internally represented with all its data in ns, and an empty suffix.

Performances

If this IRI has an empty suffix, the returned IRI simply borrows its ns. Otherwise, a new string is allocated for the returned IRI.

pub fn normalized_suffixed_at_last_gen_delim(&self) -> Iri<MownStr>

Return an IRI equivalent to this one, internally represented with ns extending to the last gen-delims characters (i.e. ":" / "/" / "?" / "#" / "[" / "]" / "@"). and suffix` containing the rest.

Performances

The returned IRI will borrow data from this one as much as possible, but strings may be allocated in case a concatenation is required.

pub fn match_ns<'s, U>(
    &'s self,
    ns: &Iri<U>
) -> Option<impl 's + Iterator<Item = char>> where
    U: TermData, 

Checks if the IRI matches a namespace.

If it does the remaining suffix is returned as iterator of chars. This prevents an additional allocation.

In case the ns and the IRI are the same, the function succeeds but returns an empty Iterator.

pub fn parse_components<'s>(&'s self, buffer: &'s mut String) -> IriParsed<'s>

Parses the components of the IRI.

This is necessary to use the IRI as a base to resolve other IRIs.

Auxiliary buffer

The buffer parameter is only required in the situation where the internal representation of this Iri makes it unsuitable for building an IriParsed (typically because it is split in an ns and a suffix part). In those situations, the buffer will be used to store the full IRI, and will be borrowed by the returned IriParsed.

Otherwise, the buffer will not be used, the data will be borrowed directly from self.

Implementation detail

Currently, the buffer is used whenever the IRI is internally stored in two parts (ns and suffix), i.e. when it was created with new_suffixed.

Technically a suffixed IRI could parsed successfully when the suffix is separating the IRI at a component. However, detecting this requires more effort. Maybe this feature will be implemented (by you?) in a future release of sophia.

pub fn write_fmt<W>(&self, w: &mut W) -> Result where
    W: Write, 

Writes the IRI to the fmt::Write using the NTriples syntax.

This means the IRI is in angled brackets and no prefix is used.

pub fn write_io<W>(&self, w: &mut W) -> Result<()> where
    W: Write, 

Writes the blank node to the io::Write using the N3 syntax.

pub fn value(&self) -> MownStr

Return this IRI as text.

impl Iri<&'static str>

pub const fn from_raw_parts_unchecked(
    ns: &'static str,
    suffix: Option<&'static str>,
    absolute: bool
) -> Self

Build an IRI from its raw components.

This constructor is used by the namespace! macro, but should not be used directly.

Pre-condition

The resulting IRI may be invalid.

Trait Implementations

impl<TD: Clone + TermData> Clone for Iri<TD>

fn clone(&self) -> Iri<TD>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<TD: Copy + TermData> Copy for Iri<TD>

impl<TD: Debug + TermData> Debug for Iri<TD>

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

Formats the value using the given formatter.

impl<TD> Display for Iri<TD> where
    TD: TermData, 

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

Formats the value using the given formatter.

impl<TD: Eq + TermData> Eq for Iri<TD>

impl<TD> From<Iri<TD>> for Term<TD> where
    TD: TermData, 

fn from(iri: Iri<TD>) -> Self

Performs the conversion.

impl<TD> From<Namespace<TD>> for Iri<TD> where
    TD: TermData, 

fn from(ns: Namespace<TD>) -> Self

Performs the conversion.

impl<TD> Hash for Iri<TD> where
    TD: TermData, 

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

Feeds this value into the given [Hasher].

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

Feeds a slice of this type into the given [Hasher].

impl<T, U> PartialEq<Iri<U>> for Iri<T> where
    T: TermData,
    U: TermData, 

fn eq(&self, other: &Iri<U>) -> bool

This method tests for self and other values to be equal, and is used by ==.

#[must_use]fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<T, U> PartialEq<Iri<U>> for Term<T> where
    T: TermData,
    U: TermData, 

fn eq(&self, other: &Iri<U>) -> bool

This method tests for self and other values to be equal, and is used by ==.

#[must_use]fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<T, U> PartialEq<Term<U>> for Iri<T> where
    T: TermData,
    U: TermData, 

fn eq(&self, other: &Term<U>) -> bool

This method tests for self and other values to be equal, and is used by ==.

#[must_use]fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<TD> PartialEq<str> for Iri<TD> where
    TD: TermData, 

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

This method tests for self and other values to be equal, and is used by ==.

#[must_use]fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<'a, 'b, TD> Resolve<&'a Iri<TD>, Iri<MownStr<'a>>> for IriParsed<'b> where
    TD: TermData, 

fn resolve(&self, other: &'a Iri<TD>) -> Iri<MownStr<'a>>

Resolve the given IRI.

Performance

May allocate an intermediate IRI if other is suffixed.

impl<'a, 'b> Resolve<Iri<&'a str>, Iri<MownStr<'a>>> for IriParsed<'b>

fn resolve(&self, other: Iri<&'a str>) -> Iri<MownStr<'a>>

Resolve the given IRI.

Performance

May allocate an intermediate IRI if other is suffixed.

impl<TD: TermData> StructuralEq for Iri<TD>

impl<'a, T, U> TryFrom<&'a Term<U>> for Iri<T> where
    T: TermData + From<&'a str>,
    U: TermData, 

type Error = TermError

The type returned in the event of a conversion error.

fn try_from(term: &'a Term<U>) -> Result<Self, Self::Error>

Performs the conversion.

impl<TD> TryFrom<Iri<TD>> for Namespace<TD> where
    TD: TermData, 

type Error = TermError

The type returned in the event of a conversion error.

fn try_from(iri: Iri<TD>) -> Result<Self, Self::Error>

Requires that the given Iri has no suffix. This can be enforced with the clone_no_suffix() method.

impl<TD> TryFrom<Term<TD>> for Iri<TD> where
    TD: TermData, 

type Error = TermError

The type returned in the event of a conversion error.

fn try_from(term: Term<TD>) -> Result<Self, Self::Error>

Performs the conversion.