Module iri_string::types

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.

RiStr and RiString + String types for IRI and URI rules.
RiAbsoluteStr and RiAbsoluteString + String types for absolute-IRI and absolute-URI rules.
RiReferenceStr and RiReferenceString + String types for IRI-reference and URI-reference rules.
RiRelativeStr and RiRelativeString + String types for irelative-ref and relative-ref rules.
RiFragmentStr and RiFragmentString + String types for ifragment and fragment rules. + Note that these types represents a substring of an IRI / URI references. They are not intended to used directly as an IRI / URI references.

“Ri” stands for “Resource Identifier”.

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.