Enum HostRef 

#[non_exhaustive]
pub enum HostRef<'a> {
    Name(DomainRef<'a>),
    Address(IpAddr),
    Uninterpreted(UninterpretedHostRef<'a>),
}

Available on crate feature net only.

Borrowed view of a Host.

Either a DomainRef borrowing into the source buffer or an IpAddr (which is Copy and so always carried by value).

Useful anywhere a borrowed host view makes sense — URI host components, header-parse temporaries, DNS lookups against a non-owning buffer.

Equality, hashing, ordering

RFC 3986 §6.2.2 syntactic equivalence applies across variants. A non-bracketed HostRef::Uninterpreted whose bytes pct-decode (and IDN-normalize) to a typed Domain compares, hashes, and orders equal to the corresponding HostRef::Name; same for a pct-encoded reg-name that decodes to an IpAddr vs HostRef::Address. Bracketed Uninterpreted (IPvFuture) keeps its own equality class — there’s no typed counterpart to bridge to. #[non_exhaustive] for the same reason as Host — bridging Uninterpreted to typed variants is what callers usually want; pattern-matching on the tag misses the bridged forms.

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

Name(DomainRef<'a>)

A DNS-style name.

Address(IpAddr)

A literal IPv4 or IPv6 address.

Uninterpreted(UninterpretedHostRef<'a>)

Borrowed view of an UninterpretedHost — reg-name bytes preserved verbatim or a bracketed IP-literal.

Implementations

impl<'a> HostRef<'a>

pub fn canonicalize(self) -> Host

Return an owned RFC 3986 canonical presentation of this host.

pub fn to_str(self) -> Cow<'a, str>

Returns this host as a string. Domain names and non-bracketed reg-names return Cow::Borrowed (no allocation); IP addresses and bracketed IP-literals are formatted into a fresh String.

pub fn is_empty(self) -> bool

Returns true when this host has an empty textual representation.

Typed domain names and IP addresses are never empty. An uninterpreted host is empty only when it has no bytes and is not an IP-literal enclosed by brackets. This method does not format or allocate.

pub fn as_unicode(self) -> Cow<'a, str>

Available on crate feature idna only.

Returns the Unicode (display) form of this host. See Host::as_unicode for the full contract.

pub fn is_loopback(self) -> bool

Returns true if this host designates the local machine via loopback — either a loopback IP address (127.0.0.0/8 or ::1, per IpAddr::is_loopback) or the RFC 6761 §6.3 localhost name (localhost itself or any *.localhost subdomain, case-insensitively).

The Uninterpreted variant is bridged through its pct-decoded form: bytes that decode to a loopback IP or the localhost name also return true. Bracketed IPvFuture literals have no typed counterpart and are never loopback.

IPv4-mapped IPv6 addresses are canonicalized before this check, so ::ffff:127.0.0.1 is recognized as loopback. This is not browser-style normalization: alternate IPv4 spellings that parse as a Name (0177.0.0.1, 2130706433, …) report as non-loopback — see the Host type docs (SSRF awareness).

pub fn into_owned(self) -> Host

Returns an owned Host containing a copy of the underlying bytes (or, for the IP variants, a copy of the address value). Named into_owned (matching crate::std::borrow::Cow::into_owned) so it doesn’t shadow the std ToOwned trait method.

pub fn try_as_domain(self) -> Result<Domain, Box<dyn Error + Send + Sync>>

Bridging accessor. Returns an owned Domain — unlike the Host::try_as_domain Cow-returning variant, the borrowed view has no Domain to lend (it carries a DomainRef), so this always materializes an owned value.

pub fn try_as_ip(self) -> Result<IpAddr, Box<dyn Error + Send + Sync>>

Bridging accessor. See Host::try_as_ip.

Trait Implementations

impl<'a> Clone for HostRef<'a>

fn clone(&self) -> HostRef<'a>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<'a> Copy for HostRef<'a>

impl<'a> Debug for HostRef<'a>

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

Formats the value using the given formatter.

impl Display for HostRef<'_>

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

Renders the host in its canonical wire form — matching Host’s Display for the same value. Useful for one-liner log/format calls (format!("{}", host_ref)) without first promoting to an owned Host.

impl Eq for HostRef<'_>

impl<'a> From<&'a Host> for HostRef<'a>

fn from(h: &'a Host) -> HostRef<'a>

Converts to this type from the input type.

impl Hash for HostRef<'_>

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

where H: Hasher,

Feeds this value into the given Hasher.

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

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Ord for HostRef<'_>

fn cmp(&self, other: &HostRef<'_>) -> Ordering

This method returns an Ordering between self and other.

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

where Self: Sized,

Compares and returns the maximum of two values.

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

where Self: Sized,

Compares and returns the minimum of two values.

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

where Self: Sized,

Restrict a value to a certain interval.

fn clamp_to<R>(self, range: R) -> Self

where Self: Sized, R: ClampBounds<Self>,

🔬This is a nightly-only experimental API. (clamp_to)

Restrict a value to a certain range.

impl PartialEq for HostRef<'_>

fn eq(&self, other: &HostRef<'_>) -> bool

Equality operator ==.

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

Inequality operator !=.

impl PartialOrd for HostRef<'_>

fn partial_cmp(&self, other: &HostRef<'_>) -> Option<Ordering>

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

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

Tests less than (for self and other) and is used by the < operator.

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

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

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

Tests greater than (for self and other) and is used by the > operator.

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

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