Struct `RiReferenceStr`

struct RiReferenceStr<S> { ... }

A borrowed string of an absolute IRI possibly with fragment part.

This corresponds to IRI-reference rule in RFC 3987 (and URI-reference rule in RFC 3986). The rule for IRI-reference is IRI / irelative-ref. In other words, this is union of RiStr and RiRelativeStr.

Valid values

This type can have an IRI reference (which can be absolute or relative).

# use iri_string::types::IriReferenceStr;
assert!(IriReferenceStr::new("https://user:pass@example.com:8080").is_ok());
assert!(IriReferenceStr::new("https://example.com/").is_ok());
assert!(IriReferenceStr::new("https://example.com/foo?bar=baz").is_ok());
assert!(IriReferenceStr::new("https://example.com/foo?bar=baz#qux").is_ok());
assert!(IriReferenceStr::new("foo:bar").is_ok());
assert!(IriReferenceStr::new("foo:").is_ok());
// `foo://.../` below are all allowed. See the crate documentation for detail.
assert!(IriReferenceStr::new("foo:/").is_ok());
assert!(IriReferenceStr::new("foo://").is_ok());
assert!(IriReferenceStr::new("foo:///").is_ok());
assert!(IriReferenceStr::new("foo:////").is_ok());
assert!(IriReferenceStr::new("foo://///").is_ok());
assert!(IriReferenceStr::new("foo/bar").is_ok());
assert!(IriReferenceStr::new("/foo/bar").is_ok());
assert!(IriReferenceStr::new("//foo/bar").is_ok());
assert!(IriReferenceStr::new("#foo").is_ok());

Some characters and sequences cannot used in an IRI reference.

# use iri_string::types::IriReferenceStr;
// `<` and `>` cannot directly appear in an IRI reference.
assert!(IriReferenceStr::new("<not allowed>").is_err());
// Broken percent encoding cannot appear in an IRI reference.
assert!(IriReferenceStr::new("%").is_err());
assert!(IriReferenceStr::new("%GG").is_err());

Implementations

`impl RiReferenceStr<IriSpec>`

fn encode_to_uri(self: &Self) -> MappedToUri<'_, Self>

Percent-encodes the IRI into a valid URI that identifies the equivalent resource.

If you need more precise control over memory allocation and buffer handling, use [MappedToUri]crate::convert::MappedToUri type.

Examples

# use iri_string::validate::Error;
# #[cfg(feature = "alloc")] {
use iri_string::format::ToDedicatedString;
use iri_string::types::{IriReferenceStr, UriReferenceString};

let iri = IriReferenceStr::new("http://example.com/?alpha=\u{03B1}")?;
// Type annotation here is not necessary.
let uri: UriReferenceString = iri.encode_to_uri().to_dedicated_string();
assert_eq!(uri, "http://example.com/?alpha=%CE%B1");
# }
# Ok::<_, Error>(())

fn as_uri(self: &Self) -> Option<&UriReferenceStr>

Converts an IRI into a URI without modification, if possible.

This is semantically equivalent to UriReferenceStr::new(self.as_str()).ok().

Examples

# use iri_string::validate::Error;
use iri_string::types::{IriReferenceStr, UriReferenceStr};

let ascii_iri = IriReferenceStr::new("http://example.com/?alpha=%CE%B1")?;
assert_eq!(
    ascii_iri.as_uri().map(AsRef::as_ref),
    Some("http://example.com/?alpha=%CE%B1")
);

let nonascii_iri = IriReferenceStr::new("http://example.com/?alpha=\u{03B1}")?;
assert_eq!(nonascii_iri.as_uri(), None);
# Ok::<_, Error>(())

`impl<S: Spec> RiReferenceStr<S>`

fn scheme_str(self: &Self) -> Option<&str>

Returns the scheme.

The following colon is truncated.

Examples

# use iri_string::validate::Error;
use iri_string::types::IriReferenceStr;

let iri = IriReferenceStr::new("http://example.com/pathpath?queryquery#fragfrag")?;
assert_eq!(iri.scheme_str(), Some("http"));
# Ok::<_, Error>(())

# use iri_string::validate::Error;
use iri_string::types::IriReferenceStr;

let iri = IriReferenceStr::new("foo/bar:baz")?;
assert_eq!(iri.scheme_str(), None);
# Ok::<_, Error>(())

fn authority_str(self: &Self) -> Option<&str>

Returns the authority.

The leading // is truncated.

Examples

# use iri_string::validate::Error;
use iri_string::types::IriReferenceStr;

let iri = IriReferenceStr::new("http://example.com/pathpath?queryquery#fragfrag")?;
assert_eq!(iri.authority_str(), Some("example.com"));
# Ok::<_, Error>(())

# use iri_string::validate::Error;
use iri_string::types::IriReferenceStr;

let iri = IriReferenceStr::new("urn:uuid:10db315b-fcd1-4428-aca8-15babc9a2da2")?;
assert_eq!(iri.authority_str(), None);
# Ok::<_, Error>(())

# use iri_string::validate::Error;
use iri_string::types::IriReferenceStr;

let iri = IriReferenceStr::new("foo/bar:baz")?;
assert_eq!(iri.authority_str(), None);
# Ok::<_, Error>(())

fn path_str(self: &Self) -> &str

Returns the path.

Examples

# use iri_string::validate::Error;
use iri_string::types::IriReferenceStr;

let iri = IriReferenceStr::new("http://example.com/pathpath?queryquery#fragfrag")?;
assert_eq!(iri.path_str(), "/pathpath");
# Ok::<_, Error>(())

# use iri_string::validate::Error;
use iri_string::types::IriReferenceStr;

let iri = IriReferenceStr::new("urn:uuid:10db315b-fcd1-4428-aca8-15babc9a2da2")?;
assert_eq!(iri.path_str(), "uuid:10db315b-fcd1-4428-aca8-15babc9a2da2");
# Ok::<_, Error>(())

# use iri_string::validate::Error;
use iri_string::types::IriReferenceStr;

let iri = IriReferenceStr::new("foo/bar:baz")?;
assert_eq!(iri.path_str(), "foo/bar:baz");
# Ok::<_, Error>(())

fn query(self: &Self) -> Option<&RiQueryStr<S>>

Returns the query.

The leading question mark (?) is truncated.

Examples

# use iri_string::validate::Error;
use iri_string::types::{IriQueryStr, IriReferenceStr};

let iri = IriReferenceStr::new("http://example.com/pathpath?queryquery#fragfrag")?;
let query = IriQueryStr::new("queryquery")?;
assert_eq!(iri.query(), Some(query));
# Ok::<_, Error>(())

# use iri_string::validate::Error;
use iri_string::types::IriReferenceStr;

let iri = IriReferenceStr::new("urn:uuid:10db315b-fcd1-4428-aca8-15babc9a2da2")?;
assert_eq!(iri.query(), None);
# Ok::<_, Error>(())

# use iri_string::validate::Error;
use iri_string::types::{IriQueryStr, IriReferenceStr};

let iri = IriReferenceStr::new("foo/bar:baz?")?;
let query = IriQueryStr::new("")?;
assert_eq!(iri.query(), Some(query));
# Ok::<_, Error>(())

fn query_str(self: &Self) -> Option<&str>

Returns the query as a raw string slice.

The leading question mark (?) is truncated.

Examples

# use iri_string::validate::Error;
use iri_string::types::IriReferenceStr;

let iri = IriReferenceStr::new("http://example.com/pathpath?queryquery#fragfrag")?;
assert_eq!(iri.query_str(), Some("queryquery"));
# Ok::<_, Error>(())

# use iri_string::validate::Error;
use iri_string::types::IriReferenceStr;

let iri = IriReferenceStr::new("urn:uuid:10db315b-fcd1-4428-aca8-15babc9a2da2")?;
assert_eq!(iri.query_str(), None);
# Ok::<_, Error>(())

# use iri_string::validate::Error;
use iri_string::types::IriReferenceStr;

let iri = IriReferenceStr::new("foo/bar:baz?")?;
assert_eq!(iri.query_str(), Some(""));
# Ok::<_, Error>(())

fn fragment(self: &Self) -> Option<&RiFragmentStr<S>>

Returns the fragment part if exists.

A leading # character is truncated if the fragment part exists.

Examples

If the IRI has a fragment part, Some(_) is returned.

# use iri_string::{spec::IriSpec, types::{IriFragmentStr, IriReferenceStr}, validate::Error};
let iri = IriReferenceStr::new("foo://bar/baz?qux=quux#corge")?;
let fragment = IriFragmentStr::new("corge")?;
assert_eq!(iri.fragment(), Some(fragment));
# Ok::<_, Error>(())

# use iri_string::{spec::IriSpec, types::{IriFragmentStr, IriReferenceStr}, validate::Error};
let iri = IriReferenceStr::new("#foo")?;
let fragment = IriFragmentStr::new("foo")?;
assert_eq!(iri.fragment(), Some(fragment));
# Ok::<_, Error>(())

When the fragment part exists but is empty string, Some(_) is returned.

# use iri_string::{spec::IriSpec, types::{IriFragmentStr, IriReferenceStr}, validate::Error};
let iri = IriReferenceStr::new("foo://bar/baz?qux=quux#")?;
let fragment = IriFragmentStr::new("")?;
assert_eq!(iri.fragment(), Some(fragment));
# Ok::<_, Error>(())

# use iri_string::{spec::IriSpec, types::{IriFragmentStr, IriReferenceStr}, validate::Error};
let iri = IriReferenceStr::new("#")?;
let fragment = IriFragmentStr::new("")?;
assert_eq!(iri.fragment(), Some(fragment));
# Ok::<_, Error>(())

If the IRI has no fragment, None is returned.

# use iri_string::{spec::IriSpec, types::IriReferenceStr, validate::Error};
let iri = IriReferenceStr::new("foo://bar/baz?qux=quux")?;
assert_eq!(iri.fragment(), None);
# Ok::<_, Error>(())

# use iri_string::{spec::IriSpec, types::IriReferenceStr, validate::Error};
let iri = IriReferenceStr::new("")?;
assert_eq!(iri.fragment(), None);
# Ok::<_, Error>(())

fn fragment_str(self: &Self) -> Option<&str>

Returns the fragment part as a raw string slice if exists.

A leading # character is truncated if the fragment part exists.

Examples

If the IRI has a fragment part, Some(_) is returned.

# use iri_string::{spec::IriSpec, types::IriReferenceStr, validate::Error};
let iri = IriReferenceStr::new("foo://bar/baz?qux=quux#corge")?;
assert_eq!(iri.fragment_str(), Some("corge"));
# Ok::<_, Error>(())

# use iri_string::{spec::IriSpec, types::IriReferenceStr, validate::Error};
let iri = IriReferenceStr::new("#foo")?;
assert_eq!(iri.fragment_str(), Some("foo"));
# Ok::<_, Error>(())

When the fragment part exists but is empty string, Some(_) is returned.

# use iri_string::{spec::IriSpec, types::IriReferenceStr, validate::Error};
let iri = IriReferenceStr::new("foo://bar/baz?qux=quux#")?;
assert_eq!(iri.fragment_str(), Some(""));
# Ok::<_, Error>(())

# use iri_string::{spec::IriSpec, types::IriReferenceStr, validate::Error};
let iri = IriReferenceStr::new("#")?;
assert_eq!(iri.fragment_str(), Some(""));
# Ok::<_, Error>(())

If the IRI has no fragment, None is returned.

# use iri_string::{spec::IriSpec, types::IriReferenceStr, validate::Error};
let iri = IriReferenceStr::new("foo://bar/baz?qux=quux")?;
assert_eq!(iri.fragment(), None);
# Ok::<_, Error>(())

# use iri_string::{spec::IriSpec, types::IriReferenceStr, validate::Error};
let iri = IriReferenceStr::new("")?;
assert_eq!(iri.fragment(), None);
# Ok::<_, Error>(())

fn authority_components(self: &Self) -> Option<AuthorityComponents<'_>>

Returns the authority components.

Examples

# use iri_string::validate::Error;
use iri_string::types::IriReferenceStr;

let iri = IriReferenceStr::new("http://user:pass@example.com:8080/pathpath?queryquery")?;
let authority = iri.authority_components()
    .expect("authority is available");
assert_eq!(authority.userinfo(), Some("user:pass"));
assert_eq!(authority.host(), "example.com");
assert_eq!(authority.port(), Some("8080"));
# Ok::<_, Error>(())

# use iri_string::validate::Error;
use iri_string::types::IriReferenceStr;

let iri = IriReferenceStr::new("foo//bar:baz")?;
assert_eq!(iri.authority_str(), None);
# Ok::<_, Error>(())

`impl<S: Spec> RiReferenceStr<S>`

fn to_iri(self: &Self) -> Result<&RiStr<S>, &RiRelativeStr<S>>

Returns the string as &RiStr, if it is valid as an IRI.

If it is not an IRI, then &RiRelativeStr is returned as Err(_).

fn to_relative_iri(self: &Self) -> Result<&RiRelativeStr<S>, &RiStr<S>>

Returns the string as &RiRelativeStr, if it is valid as an IRI.

If it is not an IRI, then &RiStr is returned as Err(_).

fn resolve_against<'a>(self: &'a Self, base: &'a RiAbsoluteStr<S>) -> Normalized<'a, RiStr<S>>

Returns resolved IRI against the given base IRI.

For IRI reference resolution output examples, see RFC 3986 section 5.4.

If you are going to resolve multiple references against the common base, consider using FixedBaseResolver.

Strictness

The IRI parsers provided by this crate is strict (e.g. http:g is always interpreted as a composition of the scheme http and the path g), so backward compatible parsing and resolution are not provided. About parser and resolver strictness, see RFC 3986 section 5.4.2:

Some parsers allow the scheme name to be present in a relative reference if it is the same as the base URI scheme. This is considered to be a loophole in prior specifications of partial URI RFC1630. Its use should be avoided but is allowed for backward compatibility.

--- https://tools.ietf.org/html/rfc3986#section-5.4.2

Failures

This method itself does not fail, but IRI resolution without WHATWG URL Standard serialization can fail in some minor cases.

To see examples of such unresolvable IRIs, visit the documentation for [normalize]crate::normalize module.

fn mask_password(self: &Self) -> PasswordMasked<'_, Self>

Returns the proxy to the IRI with password masking feature.

Examples

# use iri_string::validate::Error;
# #[cfg(feature = "alloc")] {
use iri_string::format::ToDedicatedString;
use iri_string::types::IriReferenceStr;

let iri = IriReferenceStr::new("http://user:password@example.com/path?query")?;
let masked = iri.mask_password();
assert_eq!(masked.to_dedicated_string(), "http://user:@example.com/path?query");

assert_eq!(
    masked.replace_password("${password}").to_string(),
    "http://user:${password}@example.com/path?query"
);
# }
# Ok::<_, Error>(())

`impl<S: crate::spec::Spec> RiReferenceStr<S>`

fn new(s: &str) -> Result<&Self, Error>

Creates a new string.

unsafe fn new_unchecked(s: &str) -> &Self

Creates a new string without validation.

This does not validate the given string, so it is caller's responsibility to ensure the given string is valid.

Safety

The given string must be syntactically valid as Self type. If not, any use of the returned value or the call of this function itself may result in undefined behavior.

fn as_str(self: &Self) -> &str

Returns &str.

fn len(self: &Self) -> usize

Returns the string length.

fn is_empty(self: &Self) -> bool

Returns whether the string is empty.

`impl<S> Freeze for RiReferenceStr<S>`

`impl<S> RefUnwindSafe for RiReferenceStr<S>`

`impl<S> Send for RiReferenceStr<S>`

`impl<S> Sized for RiReferenceStr<S>`

`impl<S> Sync for RiReferenceStr<S>`

`impl<S> Unpin for RiReferenceStr<S>`

`impl<S> UnsafeUnpin for RiReferenceStr<S>`

`impl<S> UnwindSafe for RiReferenceStr<S>`

`impl<S: Spec> Buildable for RiReferenceStr<S>`

`impl<S: crate::spec::Spec> AsRef for RiReferenceStr<S>`

fn as_ref(self: &Self) -> &RiReferenceStr<S>

`impl<S: crate::spec::Spec> AsRef for RiReferenceStr<S>`

fn as_ref(self: &Self) -> &str

`impl<S: crate::spec::Spec> Debug for RiReferenceStr<S>`

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

`impl<S: crate::spec::Spec> Display for RiReferenceStr<S>`

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

`impl<S: crate::spec::Spec> Eq for RiReferenceStr<S>`

`impl<S: crate::spec::Spec> Hash for RiReferenceStr<S>`

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

`impl<S: crate::spec::Spec> Ord for RiReferenceStr<S>`

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

`impl<S: crate::spec::Spec> PartialEq for RiReferenceStr<S>`

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

`impl<S: crate::spec::Spec> PartialEq for RiReferenceStr<S>`

fn eq(self: &Self, o: &Cow<'_, str>) -> bool

`impl<S: crate::spec::Spec> PartialEq for RiReferenceStr<S>`

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

`impl<S: crate::spec::Spec> PartialEq for RiReferenceStr<S>`

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

`impl<S: crate::spec::Spec> PartialOrd for RiReferenceStr<S>`

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

`impl<S: crate::spec::Spec> PartialOrd for RiReferenceStr<S>`

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

`impl<S: crate::spec::Spec> PartialOrd for RiReferenceStr<S>`

fn partial_cmp(self: &Self, o: &Cow<'_, str>) -> Option<Ordering>

`impl<S: crate::spec::Spec> PartialOrd for RiReferenceStr<S>`

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

`impl<S: crate::spec::Spec> ToOwned for RiReferenceStr<S>`

fn to_owned(self: &Self) -> <Self as >::Owned

`impl<S: crate::spec::Spec, T: crate::spec::Spec> PartialEq for RiReferenceStr<S>`

fn eq(self: &Self, o: &RiReferenceString<T>) -> bool

`impl<S: crate::spec::Spec, T: crate::spec::Spec> PartialEq for RiReferenceStr<T>`

fn eq(self: &Self, o: &RiRelativeString<S>) -> bool

`impl<S: crate::spec::Spec, T: crate::spec::Spec> PartialEq for RiReferenceStr<T>`

fn eq(self: &Self, o: &Cow<'_, RiStr<S>>) -> bool

`impl<S: crate::spec::Spec, T: crate::spec::Spec> PartialEq for RiReferenceStr<T>`

fn eq(self: &Self, o: &&RiAbsoluteStr<S>) -> bool

`impl<S: crate::spec::Spec, T: crate::spec::Spec> PartialEq for RiReferenceStr<T>`

fn eq(self: &Self, o: &&RiStr<S>) -> bool

`impl<S: crate::spec::Spec, T: crate::spec::Spec> PartialEq for RiReferenceStr<T>`

fn eq(self: &Self, o: &Cow<'_, RiRelativeStr<S>>) -> bool

`impl<S: crate::spec::Spec, T: crate::spec::Spec> PartialEq for RiReferenceStr<T>`

fn eq(self: &Self, o: &RiAbsoluteStr<S>) -> bool

`impl<S: crate::spec::Spec, T: crate::spec::Spec> PartialEq for RiReferenceStr<T>`

fn eq(self: &Self, o: &RiStr<S>) -> bool

`impl<S: crate::spec::Spec, T: crate::spec::Spec> PartialEq for RiReferenceStr<T>`

fn eq(self: &Self, o: &Cow<'_, RiAbsoluteStr<S>>) -> bool

`impl<S: crate::spec::Spec, T: crate::spec::Spec> PartialEq for RiReferenceStr<T>`

fn eq(self: &Self, o: &&RiRelativeStr<S>) -> bool

`impl<S: crate::spec::Spec, T: crate::spec::Spec> PartialEq for RiReferenceStr<T>`

fn eq(self: &Self, o: &RiRelativeStr<S>) -> bool

`impl<S: crate::spec::Spec, T: crate::spec::Spec> PartialEq for RiReferenceStr<T>`

fn eq(self: &Self, o: &&RiReferenceStr<S>) -> bool

`impl<S: crate::spec::Spec, T: crate::spec::Spec> PartialEq for RiReferenceStr<T>`

fn eq(self: &Self, o: &RiString<S>) -> bool

`impl<S: crate::spec::Spec, T: crate::spec::Spec> PartialEq for RiReferenceStr<T>`

fn eq(self: &Self, o: &RiAbsoluteString<S>) -> bool

`impl<S: crate::spec::Spec, T: crate::spec::Spec> PartialOrd for RiReferenceStr<S>`

fn partial_cmp(self: &Self, o: &RiReferenceString<T>) -> Option<Ordering>

`impl<S: crate::spec::Spec, T: crate::spec::Spec> PartialOrd for RiReferenceStr<T>`

fn partial_cmp(self: &Self, o: &RiString<S>) -> Option<Ordering>

`impl<S: crate::spec::Spec, T: crate::spec::Spec> PartialOrd for RiReferenceStr<T>`

fn partial_cmp(self: &Self, o: &RiAbsoluteString<S>) -> Option<Ordering>

`impl<S: crate::spec::Spec, T: crate::spec::Spec> PartialOrd for RiReferenceStr<T>`

fn partial_cmp(self: &Self, o: &RiRelativeString<S>) -> Option<Ordering>

`impl<S: crate::spec::Spec, T: crate::spec::Spec> PartialOrd for RiReferenceStr<T>`

fn partial_cmp(self: &Self, o: &Cow<'_, RiStr<S>>) -> Option<Ordering>

`impl<S: crate::spec::Spec, T: crate::spec::Spec> PartialOrd for RiReferenceStr<T>`

fn partial_cmp(self: &Self, o: &&RiAbsoluteStr<S>) -> Option<Ordering>

`impl<S: crate::spec::Spec, T: crate::spec::Spec> PartialOrd for RiReferenceStr<T>`

fn partial_cmp(self: &Self, o: &&RiStr<S>) -> Option<Ordering>

`impl<S: crate::spec::Spec, T: crate::spec::Spec> PartialOrd for RiReferenceStr<T>`

fn partial_cmp(self: &Self, o: &Cow<'_, RiRelativeStr<S>>) -> Option<Ordering>

`impl<S: crate::spec::Spec, T: crate::spec::Spec> PartialOrd for RiReferenceStr<T>`

fn partial_cmp(self: &Self, o: &RiAbsoluteStr<S>) -> Option<Ordering>

`impl<S: crate::spec::Spec, T: crate::spec::Spec> PartialOrd for RiReferenceStr<T>`

fn partial_cmp(self: &Self, o: &RiStr<S>) -> Option<Ordering>

`impl<S: crate::spec::Spec, T: crate::spec::Spec> PartialOrd for RiReferenceStr<T>`

fn partial_cmp(self: &Self, o: &Cow<'_, RiAbsoluteStr<S>>) -> Option<Ordering>

`impl<S: crate::spec::Spec, T: crate::spec::Spec> PartialOrd for RiReferenceStr<T>`

fn partial_cmp(self: &Self, o: &&RiRelativeStr<S>) -> Option<Ordering>

`impl<S: crate::spec::Spec, T: crate::spec::Spec> PartialOrd for RiReferenceStr<T>`

fn partial_cmp(self: &Self, o: &RiRelativeStr<S>) -> Option<Ordering>

`impl<S: crate::spec::Spec, T: crate::spec::Spec> PartialOrd for RiReferenceStr<T>`

fn partial_cmp(self: &Self, o: &&RiReferenceStr<S>) -> Option<Ordering>

`impl<T> Any for RiReferenceStr<S>`

fn type_id(self: &Self) -> TypeId

`impl<T> Borrow for RiReferenceStr<S>`

fn borrow(self: &Self) -> &T

`impl<T> BorrowMut for RiReferenceStr<S>`

fn borrow_mut(self: &mut Self) -> &mut T

`impl<T> ToString for RiReferenceStr<S>`

fn to_string(self: &Self) -> String