Struct rdftk_iri::IRI

pub struct IRI { /* fields omitted */ }

The IRI type comprised of Scheme, Authority, Path, Query, and Fragment components. Note that for most APIs the use of IRIRef is preferred over IRI directly.

Example

The following example creates a new IRI from a string, but also then uses that as a template to create an additional one. The normalize method in this example will convert the host name to lower case. The without_query method creates a new IRI with all components except the query copied over.

use rdftk_iri::{IRI, Normalize};
use std::str::FromStr;

let iri = IRI::from_str(
    "https://john.doe@www.EXAMPLE.com:123/forum/questions/?tag=networking&order=newest#top",
).unwrap();

let new_uri = iri.normalize().unwrap().without_query();

Definitions (from Wikipedia)

Each URI begins with a scheme name that refers to a specification for assigning identifiers within that scheme. As such, the URI syntax is a federated and extensible naming system wherein each scheme’s specification may further restrict the syntax and semantics of identifiers using that scheme. The URI generic syntax is a superset of the syntax of all URI schemes. It was first defined in RFC 2396, and finalized in RFC 3986.

The URI generic syntax consists of a hierarchical sequence of five components:[8]

URI = scheme:[//authority]path[?query][#fragment]

where the authority component divides into three subcomponents:

authority = [userinfo@]host[:port]

The URI comprises:

• A non-empty scheme component followed by a colon (:), consisting of a sequence of characters beginning with a letter and followed by any combination of letters, digits, plus (+), period (.), or hyphen (-). Although schemes are case-insensitive, the canonical form is lowercase and documents that specify schemes must do so with lowercase letters. Examples of popular schemes include http, https, ftp, mailto, file, data, and irc. URI schemes should be registered with the Internet Assigned Numbers Authority (IANA), although non-registered schemes are used in practice.
• An optional authority component preceded by two slashes (//), comprising:
  • An optional userinfo subcomponent that may consist of a user name and an optional password preceded by a colon (:), followed by an at symbol (@). Use of the format username:password in the userinfo subcomponent is deprecated for security reasons. Applications should not render as clear text any data after the first colon (:) found within a userinfo subcomponent unless the data after the colon is the empty string (indicating no password).
  • A host subcomponent, consisting of either a registered name (including but not limited to a hostname), or an IP address. IPv4 addresses must be in dot-decimal notation, and IPv6 addresses must be enclosed in brackets ([]).
  • An optional port subcomponent preceded by a colon (:).
• A path component, consisting of a sequence of path segments separated by a slash (/). A path is always defined for a URI, though the defined path may be empty (zero length). A segment may also be empty, resulting in two consecutive slashes (//) in the path component. A path component may resemble or map exactly to a file system path, but does not always imply a relation to one. If an authority component is present, then the path component must either be empty or begin with a slash (/). If an authority component is absent, then the path cannot begin with an empty segment, that is with two slashes (//), as the following characters would be interpreted as an authority component. The final segment of the path may be referred to as a ‘slug’.
• An optional query component preceded by a question mark (?), containing a query string of non-hierarchical data. Its syntax is not well defined, but by convention is most often a sequence of attribute–value pairs separated by a delimiter.
• An optional fragment component preceded by a hash (#). The fragment contains a fragment identifier providing direction to a secondary resource, such as a section heading in an article identified by the remainder of the URI. When the primary resource is an HTML document, the fragment is often an id attribute of a specific element, and web browsers will scroll this element into view.

Strings of data octets within a URI are represented as characters. Permitted characters within a URI are the ASCII characters[*] for the lowercase and uppercase letters of the modern English alphabet, the Arabic numerals, hyphen, period, underscore, and tilde. Octets represented by any other character must be percent-encoded.

Of the ASCII character set, the characters : / ? # [ ] @ are reserved for use as delimiters of the generic URI components and must be percent-encoded – for example, %3F for a question mark. The characters ! $ & ’ ( ) * + , ; = are permitted by generic URI syntax to be used unencoded in the user information, host, and path as delimiters. Additionally, : and @ may appear unencoded within the path, query, and fragment; and ? and / may appear unencoded as data within the query or fragment.

[*] While URIs are limited to a subset of the ASCII character set, IRIs may additionally contain most characters from the Universal Character Set (Unicode/ISO 10646), including Chinese, Japanese, Korean, and Cyrillic characters.

Implementations

impl IRI

pub fn new(path: &Path) -> Self

Create a new IRI with only the specified path, this is a valid relative value – see is_absolute.

This is also provided as an implementation of From<&Path> and From<Path> for IRI.

Example

use rdftk_iri::{IRI, Path};
use std::str::FromStr;

let iri = IRI::new(
    &Path::from_str("/forum/questions/").unwrap()
);

pub fn new_file(path: &Path) -> IriResult<Self>

Construct a new IRI with the “file” scheme and the provided file system path.

This is also provided as an implementation of TryFrom<&PathBuf> and TryFrom<PathBuf> for IRI if the “path_iri” feature has been enabled.

Example

use rdftk_iri::IRI;
use std::path::PathBuf;

let iri = IRI::new_file(&PathBuf::from("Documents/test-plan.md")).unwrap();

This results in the IRI file://Documents/test-plan.md.

pub fn new_name(
    namespace_identifier: &str,
    namespace_specific_string: &str
) -> IriResult<Self>

Construct a new URN IRI with the given namespace identifier and namespace-specific string.

Example

use rdftk_iri::IRI;

let iri = IRI::new_name("uuid", "f3b4958c-52a1-11e7-802a-010203040506").unwrap();

This results in the IRI urn:uuid:f3b4958c-52a1-11e7-802a-010203040506.

pub fn new_genid(base: &IRI) -> IriResult<Self>

Create a new well-known IRI using the "genid" form. This creates a new UUID value and replaces the path of the provided base IRI with the new path.

use rdftk_iri::{IRI, Path};
use std::str::FromStr;

let base_iri = IRI::from_str("http://example.org/").unwrap();
let gen_id = IRI::new_genid(&base_iri).unwrap();

// http://example.org/.well-known/genid/{uuid}
println!("{}", gen_id);

pub fn with_new_path(&self, path: Path) -> Self

Return a new IRI as a copy of self with the path component replaced by the provided path value.

pub fn without_path(&self) -> Self

Return a new IRI as a copy of self with the path component replaced with the value of Path::default().

pub fn with_new_query(&self, query: Query) -> Self

Return a new IRI as a copy of self with the query component replaced by the provided query value.

pub fn without_query(&self) -> Self

Return a new IRI as a copy of self with the query component removed.

pub fn with_new_fragment(&self, fragment: Fragment) -> Self

Return a new IRI as a copy of self with the fragment component replaced by the provided fragment value.

pub fn without_fragment(&self) -> Self

Return a new IRI as a copy of self with the fragment component removed.

pub fn resolve(&self, relative: &IRI) -> IriResult<Self>

Resolves the IRI value relative using self as the base.

If the given URI is already absolute, or if this URI is opaque, then the given URI is returned. Otherwise this method constructs a new hierarchical URI in a manner consistent with RFC 2396, §5.2;.

pub fn relativize(&self, _other: &IRIRef) -> IriResult<Self>

Relativizes the IRI other against this IRI.

The relativization of the IRI other against this IRI is computed as follows:

1. If either this IRI or the given IRI are opaque, or if the scheme and authority components of the two IRIs are not identical, or if the path of this IRI is not a prefix of the path of the given IRI, then the given IRI is returned.
2. Otherwise a new relative hierarchical IRI is constructed with query and fragment components taken from the given IRI and with a path component computed by removing this IRI’s path from the beginning of the given IRI’s path.

pub fn is_absolute(&self) -> bool

Returns true if this is an absolute IRI, else false. An IRI is absolute if, and only if, it has a scheme component and does not have a fragment component.

Examples

assert!(IRI::from_str("mailto:a@b.com").unwrap().is_absolute());
assert!(IRI::from_str("http://example.com").unwrap().is_absolute());
assert!(IRI::from_str("http://example.com/path").unwrap().is_absolute());
assert!(IRI::from_str("scheme://example.com").unwrap().is_absolute());
assert!(IRI::from_str("scheme:example.com").unwrap().is_absolute());
assert!(IRI::from_str("scheme:example.com/path").unwrap().is_absolute());

assert!(!IRI::from_str("//example.com/path#foo").unwrap().is_absolute());
assert!(!IRI::from_str("http://example.com/path#foo").unwrap().is_absolute());
assert!(!IRI::from_str("scheme:example.com#foo").unwrap().is_absolute());
assert!(!IRI::from_str("path").unwrap().is_absolute());
assert!(!IRI::from_str("/path").unwrap().is_absolute());

pub fn is_relative_reference(&self) -> bool

Returns true if this is a relative IRI reference, else false. An IRI is a relative reference if, and only if, it does not have a scheme component.

Examples

assert!(IRI::from_str("//example.com/path#foo").unwrap().is_relative_reference());
assert!(IRI::from_str("path").unwrap().is_relative_reference());
assert!(IRI::from_str("/path").unwrap().is_relative_reference());

assert!(!IRI::from_str("mailto:a@b.com").unwrap().is_relative_reference());
assert!(!IRI::from_str("http://example.com").unwrap().is_relative_reference());
assert!(!IRI::from_str("http://example.com/path").unwrap().is_relative_reference());
assert!(!IRI::from_str("scheme://example.com").unwrap().is_relative_reference());
assert!(!IRI::from_str("scheme:example.com").unwrap().is_relative_reference());
assert!(!IRI::from_str("scheme:example.com/path").unwrap().is_relative_reference());
assert!(!IRI::from_str("http://example.com/path#foo").unwrap().is_relative_reference());
assert!(!IRI::from_str("scheme:example.com#foo").unwrap().is_relative_reference());

pub fn is_opaque(&self) -> bool

Returns true if this is an opaque IRI, else false. An IRI is opaque if, and only if, it is absolute and its scheme-specific part does not begin with a slash character (‘/’). An opaque IRI has a scheme, a scheme-specific part, and possibly a fragment; all other components are undefined.

Examples

assert!(IRI::from_str("mailto:a@b.com").unwrap().is_opaque());
assert!(IRI::from_str("scheme:example.com").unwrap().is_opaque());
assert!(IRI::from_str("scheme:example.com/path").unwrap().is_opaque());

assert!(!IRI::from_str("http://example.com").unwrap().is_opaque());
assert!(!IRI::from_str("http://example.com/path").unwrap().is_opaque());
assert!(!IRI::from_str("scheme://example.com").unwrap().is_opaque());
assert!(!IRI::from_str("path").unwrap().is_opaque());
assert!(!IRI::from_str("/path").unwrap().is_opaque());

pub fn is_well_known(&self) -> bool

Returns true if this IRI’s path starts with the well-known prefix defined in RFC-8615: Well-Known Uniform Resource Identifiers (URIs).

Examples

assert!(
    IRI::from_str("http://example.com/.well-known/genid/d26a2d0e98334696f4ad70a677abc1f6")
        .unwrap()
        .is_well_known()
);

pub fn has_scheme(&self) -> bool

Return true if this IRI include a scheme, else false.

pub fn scheme(&self) -> &Option<Scheme>

Return the current value of the scheme component.

pub fn scheme_specific_part(&self) -> String

Return the scheme-specific part of the IRI, basically any part of the IRI that isn’t the scheme itself.

pub fn has_authority(&self) -> bool

Return true if this IRI include a authority, else false.

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

Return the current value of the authority component.

pub fn has_path(&self) -> bool

Return true if this IRI include a path, else false.

pub fn path(&self) -> &Path

Return the current value of the path component.

pub fn has_query(&self) -> bool

Return true if this IRI include a query, else false.

pub fn query(&self) -> &Option<Query>

Return the current value of the query component.

pub fn has_fragment(&self) -> bool

Return true if this IRI include a fragment, else false.

pub fn fragment(&self) -> &Option<Fragment>

Return the current value of the fragment component.

pub fn set_scheme(&mut self, scheme: Option<Scheme>)

Set the value of the scheme component.

pub fn set_authority(&mut self, authority: Option<Authority>)

Set the value of the authority component.

pub fn set_path(&mut self, path: Path)

Set the value of the path component.

pub fn set_query(&mut self, query: Option<Query>)

Set the value of the query component.

pub fn set_fragment(&mut self, fragment: Option<Fragment>)

Set the value of the fragment component.

Trait Implementations

impl Clone for IRI

fn clone(&self) -> IRI

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for IRI

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

Formats the value using the given formatter.

impl Default for IRI

fn default() -> Self

Returns the “default value” for a type.

impl Display for IRI

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

Formats the value using the given formatter.

impl From<&'_ Path> for IRI

fn from(path: &Path) -> Self

Performs the conversion.

impl From<Path> for IRI

fn from(path: Path) -> Self

Performs the conversion.

impl FromStr for IRI

type Err = IriError

The associated error which can be returned from parsing.

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

Parses a string s to return a value of this type.

impl Hash for IRI

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 Normalize for IRI

fn normalize(self) -> IriResult<Self>

Return a normalized version of self. The default for normalization is to do nothing and return self unchanged.

impl Ord for IRI

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

This method returns an Ordering between self and other.

#[must_use]

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

Compares and returns the maximum of two values.

#[must_use]

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

Compares and returns the minimum of two values.

#[must_use]

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

Restrict a value to a certain interval.

impl PartialEq<IRI> for IRI

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

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

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

This method tests for !=.

impl PartialOrd<IRI> for IRI

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

This method returns an ordering between self and other values if one exists.

#[must_use]

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

This method tests less than (for self and other) and is used by the < operator.

#[must_use]

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

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

#[must_use]

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

This method tests greater than (for self and other) and is used by the > operator.

#[must_use]

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

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

impl PercentEncoding for IRI

fn encode(&self, for_uri: bool) -> Self where
    Self: Sized, 

Construct a new value that has been percent encoded. If for_uri is true this method will also encode all non-ascii characters as a sequence of UTF-8 octets in percent encoded form.

impl TryFrom<&'_ PathBuf> for IRI

type Error = IriError

The type returned in the event of a conversion error.

fn try_from(path: &PathBuf) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<&'_ Uuid> for IRI

type Error = IriError

The type returned in the event of a conversion error.

fn try_from(path: &Uuid) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<&'_ mut IriBuilder> for IRI

type Error = IriError

The type returned in the event of a conversion error.

fn try_from(builder: &mut IriBuilder) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<PathBuf> for IRI

type Error = IriError

The type returned in the event of a conversion error.

fn try_from(path: PathBuf) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<Uuid> for IRI

type Error = IriError

The type returned in the event of a conversion error.

fn try_from(path: Uuid) -> Result<Self, Self::Error>

Performs the conversion.

impl Eq for IRI

impl StructuralEq for IRI

impl StructuralPartialEq for IRI