Module iri_string::types

source ·
Expand description

URI and IRI types.

§URI and IRI

IRIs (Internationalized Resource Identifiers) are defined in RFC 3987, and URIs (Uniform Resource Identifiers) are defined in RFC 3986.

URI consists of only ASCII characters, and is a subset of IRI.

IRIs are defined as below:

IRI           = scheme ":" ihier-part [ "?" iquery ] [ "#" ifragment ]
IRI-reference = IRI / irelative-ref
absolute-IRI  = scheme ":" ihier-part [ "?" iquery ]
irelative-ref = irelative-part [ "?" iquery ] [ "#" ifragment ]
    (`irelative-part` is roughly same as `ihier-part`.)

Definitions for URIs are almost same, but they cannot have non-ASCII characters.

§Types

Types can be categorized by:

  • syntax,
  • spec, and
  • ownership.

§Syntax

Since URIs and IRIs have almost same syntax and share algorithms, they are implemented by generic types.

“Ri” stands for “Resource Identifier”.

§Spec

These types have a type parameter, which represents RFC specification. IriSpec represents RFC 3987 spec, and UriSpec represents RFC 3986 spec. For example, RiAbsoluteStr<IriSpec> can have absolute-IRI string value, and RiReferenceStr<UriSpec> can have URI-reference string value.

§Ownership

String-like types have usually two variations, borrowed and owned.

Borrowed types (such as str, Path, OsStr) are unsized, and used by reference style. Owned types (such as String, PathBuf, OsString) are sized, and requires heap allocation. Owned types can be coerced to a borrowed type (for example, &String is automatically coerced to &str in many context).

IRI / URI types have same variations, RiFooStr and RiFooString (Foo part represents syntax). They are very similar to &str and String. Deref is implemented, RiFooStr::len() is available, &RiFooString can be coerced to &RiFooStr, Cow<'_, RiFooStr> and Box<RiFooStr> is available, and so on.

§Hierarchy and safe conversion

IRI syntaxes have the hierarchy below.

RiReferenceStr
|-- RiStr
|   `-- RiAbsoluteStr
`-- RiRelativeStr

Therefore, the conversions below are safe and cheap:

  • RiStr -> RiReferenceStr
  • RiAbsoluteStr -> RiStr
  • RiAbsoluteStr -> RiReferenceStr
  • RiRelativeStr -> RiReferenceStr

For safely convertible types (consider FooStr -> BarStr is safe), traits below are implemented:

  • AsRef<BarStr> for FooStr
  • AsRef<BarStr> for FooString
  • From<FooString> for BarString
  • PartialEq<FooStr> for BarStr, and lots of impls like that
    • PartialEq and ParitalOrd.
    • Slice, owned, Cow, reference, etc…

§Fallible conversions

Fallible conversions are implemented from plain string into IRI strings.

  • TryFrom<&str> for &FooStr
  • TryFrom<&str> for FooString
  • TryFrom<String> for FooString
  • FromStr for FooString

Some IRI string types provide more convenient methods to convert between IRI types. For example, RiReferenceString::into_iri() tries to convert an IRI reference into an IRI, and returns Result<IriString, IriRelativeString>. This is because an IRI reference is valid as an IRI or a relative IRI reference. Such methods are usually more efficient than using TryFrom for plain strings, because they prevents you from losing ownership of a string, and does a conversion without extra memory allocation.

§Aliases

This module contains type aliases for RFC 3986 URI types and RFC 3987 IRI types.

IriFooStr{,ing} are aliases of RiFooStr{,ing}<IriSpec>, and UriFooStr{,ing} are aliases of RiFooStr{,ing}<UriSpec>.

§Wrapped string types

Similar to string types in std (such as str, std::path::Path, and std::ffi::OsStr), IRI string types in this crate provides convenient conversions to:

  • std::box::Box,
  • std::borrow::Cow,
  • std::rc::Rc, and
  • std::sync::Arc.
use std::borrow::Cow;
use std::rc::Rc;
use std::sync::Arc;

use iri_string::types::IriStr;

let iri = IriStr::new("http://example.com/")?;
let iri_owned = iri.to_owned();

// From slice.
let cow_1_1: Cow<'_, IriStr> = iri.into();
let cow_1_2 = Cow::<'_, IriStr>::from(iri);
assert!(matches!(cow_1_1, Cow::Borrowed(_)));
assert!(matches!(cow_1_2, Cow::Borrowed(_)));
// From owned.
let cow_2_1: Cow<'_, IriStr> = iri_owned.clone().into();
let cow_2_2 = Cow::<'_, IriStr>::from(iri_owned.clone());
assert!(matches!(cow_2_1, Cow::Owned(_)));
assert!(matches!(cow_2_2, Cow::Owned(_)));

// From slice.
let box_1_1: Box<IriStr> = iri.into();
let box_1_2 = Box::<IriStr>::from(iri);
// From owned.
let box_2_1: Box<IriStr> = iri_owned.clone().into();
let box_2_2 = Box::<IriStr>::from(iri_owned.clone());

// From slice.
let rc_1_1: Rc<IriStr> = iri.into();
let rc_1_2 = Rc::<IriStr>::from(iri);
// From owned.
// Note that `From<owned> for Rc<borrowed>` is not implemented for now.
// Get borrowed string by `.as_slice()` and convert it.
let rc_2_1: Rc<IriStr> = iri_owned.clone().as_slice().into();
let rc_2_2 = Rc::<IriStr>::from(iri_owned.clone().as_slice());

// From slice.
let arc_1_1: Arc<IriStr> = iri.into();
let arc_1_2 = Arc::<IriStr>::from(iri);
// From owned.
// Note that `From<owned> for Arc<borrowed>` is not implemented for now.
// Get borrowed string by `.as_slice()` and convert it.
let arc_2_1: Arc<IriStr> = iri_owned.clone().as_slice().into();
let arc_2_2 = Arc::<IriStr>::from(iri_owned.clone().as_slice());

Structs§

  • CreationErroralloc
    Error on conversion into an IRI type.
  • RiAbsoluteStr
    A borrowed slice of an absolute IRI without fragment part.
  • RiAbsoluteStringalloc
    An owned string of an absolute IRI without fragment part.
  • RiFragmentStr
    A borrowed slice of an IRI fragment (i.e. after the first # character).
  • RiFragmentStringalloc
    An owned string of an IRI fragment (i.e. after the first # character).
  • RiQueryStr
    A borrowed slice of an IRI query (i.e. after the first ? and before the first #).
  • RiQueryStringalloc
    An owned string of an IRI fragment (i.e. after the first # character).
  • RiReferenceStr
    A borrowed string of an absolute IRI possibly with fragment part.
  • RiReferenceStringalloc
    An owned string of an absolute IRI possibly with fragment part.
  • RiRelativeStr
    A borrowed slice of a relative IRI reference.
  • RiRelativeStringalloc
    An owned string of a relative IRI reference.
  • RiStr
    A borrowed string of an absolute IRI possibly with fragment part.
  • RiStringalloc
    An owned string of an absolute IRI possibly with fragment part.

Type Aliases§