Struct Jid

pub struct Jid<'a> { /* private fields */ }

A parsed JID.

Implementations

impl<'a> Jid<'a>

pub fn split(s: &'a str) -> Result<(Option<&'a str>, &'a str, Option<&'a str>)>

Splits a JID formatted as a string into its localpart, domainpart, and resourcepart. The localpart and resourcepart are optional, but the domainpart is always returned.

Errors

This function performs a “naive” string split and does not perform any validation of the individual parts other than to make sure that required parts exist. For example “@example.com” will return an error (EmptyLocal), but “%@example.com” will not (even though “%” is not a valid localpart). The length of localparts and resourceparts is also not checked (other than if they’re empty). This is because when creating an actual JID it is possible for certain Unicode characters to be canonicalized into a shorter length encoding, meaning that a part that was previously too long may suddenly fit in the maximum length. ShortDomain may be returned because we know that domains will never become longer after performing IDNA2008 operations, but LongDomain may not be returned for the same reasons as mentioned above.

Possible errors include:

• EmptyJid (eg. "")
• EmptyLocal ("@example.com")
• EmptyResource ("example.com/")
• ShortDomain ("a", "foo@/bar")

Examples

Basic usage:

let (lp, dp, rp) = Jid::split("feste@example.net")?;
assert_eq!(lp, Some("feste"));
assert_eq!(dp, "example.net");
assert_eq!(rp, None);

pub fn new<L, R>(local: L, domain: &'a str, resource: R) -> Result<Jid<'a>>

where L: Into<Option<&'a str>>, R: Into<Option<&'a str>>,

Constructs a JID from its constituent parts. The localpart is generally the username of a user on a particular server, the domainpart is a domain, hostname, or IP address where the user or entity resides, and the resourcepart identifies a specific client. Everything but the domain is optional.

Errors

If the localpart or resourcepart passed to this function is not valid, or the domainpart fails IDNA processing or is not a valid IPv6 address, this function returns an error variant.

Examples

Basic usage:

let j = Jid::new("feste", "example.net", None)?;
assert_eq!(j, "feste@example.net");

pub fn from_domain(domain: &'a str) -> Result<Jid<'a>>

Construct a JID containing only a domain part.

Errors

If domain fails the IDNA “to Unicode” operation, or is enclosed in square brackets (“[]”) but is not a valid IPv6 address, this function returns an error variant.

Examples

Basic usage:

let j = Jid::from_domain("example.net")?;
assert_eq!(j, "example.net");

pub fn bare(self) -> Jid<'a>

Consumes a JID to construct a bare JID (a JID without a resourcepart).

Examples

Basic usage:

let j = Jid::new("feste", "example.net", "res")?;
assert_eq!(j.bare(), "feste@example.net");

pub fn domain(self) -> Jid<'a>

Consumes a JID to construct a JID with only the domainpart.

Examples

Basic usage:

let j = Jid::new("feste", "example.net", "res")?;
assert_eq!(j.domain(), "example.net");

pub fn with_local<T: Into<Option<&'a str>>>(self, local: T) -> Result<Jid<'a>>

Consumes a JID to construct a new JID with the given localpart.

Errors

If the localpart is too long Error::LongLocal is returned.

Examples

Basic usage:

let j = Jid::from_str("example.net")?;
assert_eq!(j.with_local("feste")?, "feste@example.net");

let j = Jid::from_str("iago@example.net")?;
assert_eq!(j.with_local(None)?, "example.net");

let j = Jid::from_str("feste@example.net")?;
assert!(j.with_local("").is_err());

pub fn with_domain(self, domain: &'a str) -> Result<Jid<'a>>

Consumes a JID to construct a new JID with the given domainpart.

Errors

If the domain is too long, too short, or fails IDNA processing, an error variant is returned.

Examples

Basic usage:

let j = Jid::from_str("feste@example.net")?;
assert_eq!(j.with_domain("example.org")?, "feste@example.org");

pub fn with_resource<T: Into<Option<&'a str>>>( self, resource: T, ) -> Result<Jid<'a>>

Consumes a JID to construct a new JID with the given resourcepart.

Errors

If the resource is too long Error::LongResource is returned.

Examples

Basic usage:

let j = Jid::from_str("feste@example.net")?;
assert_eq!(j.with_resource("1234")?, "feste@example.net/1234");

let j = Jid::from_str("feste@example.net/1234")?;
assert_eq!(j.with_resource(None)?, "feste@example.net");

let j = Jid::from_str("feste@example.net")?;
assert!(j.with_resource("").is_err());

pub fn from_str(s: &'a str) -> Result<Jid<'a>>

Parse a string to create a Jid.

This does not implement the FromStr trait because the Jid type requires an explicit lifetime annotation and the from_str method of FromStr uses an implicit annotation which is not compatible with the Jid type.

Errors

If the entire string or any part of the JID is empty or not valid, or the domainpart fails IDNA processing or is not a valid IPv6 address, this function returns an error variant.

Examples

let j = Jid::from_str("juliet@example.net/balcony")?;
assert_eq!(j, "juliet@example.net/balcony");

pub fn localpart(&self) -> Option<&str>

Returns the localpart of the JID in canonical form.

Examples

let j = Jid::from_str("mercutio@example.net/rp")?;
assert_eq!(j.localpart(), Some("mercutio"));

let j = Jid::from_str("example.net/rp")?;
assert!(j.localpart().is_none());

pub fn domainpart(&self) -> &str

Returns the domainpart of the JID in canonical form.

Examples

let j = Jid::from_str("mercutio@example.net/rp")?;
assert_eq!(j.domainpart(), "example.net");

pub fn resourcepart(&self) -> Option<&str>

Returns the resourcepart of the JID in canonical form.

Examples

let j = Jid::from_str("example.net/rp")?;
assert_eq!(j.resourcepart(), Some("rp"));

let j = Jid::from_str("feste@example.net")?;
assert!(j.resourcepart().is_none());

pub unsafe fn new_unchecked<L, R>( local: L, domain: &'a str, resource: R, ) -> Jid<'a>

where L: Into<Option<&'a str>>, R: Into<Option<&'a str>>,

Constructs a JID from its constituent parts, bypassing safety checks. A None value for the localpart or resourcepart indicates that there is no localpart or resourcepart. A value of Some("") (although note that the Some() wrapper may be elided) indicates that the localpart or resourcepart is empty, which is invalid, but allowed by this unsafe function (eg. @example.com).

Examples

Constructing an invalid JID:

unsafe {
    let j = Jid::new_unchecked(r#"/o\"#, "[badip]", None);
    assert_eq!(j.localpart(), Some(r#"/o\"#));
    assert_eq!(j.domainpart(), "[badip]");
    assert_eq!(j.resourcepart(), None);

    // Note that comparisons you would expect to work may fail when creating unsafe JIDs.
    assert_ne!(j, r#"/o\@[badip]"#);

    let j = Jid::new_unchecked("", "example.com", "");
    assert_eq!(j, "@example.com/");
}

Trait Implementations

impl<'a> Clone for Jid<'a>

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

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<'a> Debug for Jid<'a>

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

Formats the value using the given formatter.

impl Display for Jid<'_>

Format the JID in its canonical string form.

Examples

Formatting and printing:

let j = Jid::from_str("viola@example.net")?;

assert_eq!(format!("{}", j), "viola@example.net");

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

Formats the value using the given formatter.

impl<'a> From<IpAddr> for Jid<'a>

Creates a JID from an IP address.

fn from(addr: IpAddr) -> Jid<'a>

Converts to this type from the input type.

impl<'a> From<Ipv4Addr> for Jid<'a>

Creates a JID from an IPv4 address.

fn from(addr: Ipv4Addr) -> Jid<'a>

Converts to this type from the input type.

impl<'a> From<Ipv6Addr> for Jid<'a>

Creates a JID from an IPv6 address.

fn from(addr: Ipv6Addr) -> Jid<'a>

Converts to this type from the input type.

impl<'a> Ord for Jid<'a>

fn cmp(&self, other: &Jid<'a>) -> 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.

impl<'a, 'b> PartialEq<&'b str> for Jid<'a>

Allows JIDs to be compared with strings.

This may be expensive. The string is first split using Jid::split and each part is compared with its corresponding part in the JID. If this comparison is successful, true is returned and the comparison is cheap. If this does not match, however, the string is then canonicalized (by converting it into a JID) and the parts are compared again; this may require expensive heap allocations. If constructing a JID from the string fails, the comparison always fails (even if the original JID is would match the invalid output). Comparisons involving unsafe JIDs constructed with Jid::new_unchecked should construct an unsafe JID from the string and manually compare the parts.

fn eq(&self, other: &&'b str) -> bool

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<'a, 'b> PartialEq<Cow<'b, str>> for Jid<'a>

Allows JIDs to be compared with strings.

This may be expensive. The string is first split using Jid::split and each part is compared with its corresponding part in the JID. If this comparison is successful, true is returned and the comparison is cheap. If this does not match, however, the string is then canonicalized (by converting it into a JID) and the parts are compared again; this may require expensive heap allocations. If constructing a JID from the string fails, the comparison always fails (even if the original JID is would match the invalid output). Comparisons involving unsafe JIDs constructed with Jid::new_unchecked should construct an unsafe JID from the string and manually compare the parts.

fn eq(&self, other: &Cow<'b, str>) -> bool

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq<Jid<'_>> for str

Allows JIDs to be compared with strings.

This may be expensive. The string is first split using Jid::split and each part is compared with its corresponding part in the JID. If this comparison is successful, true is returned and the comparison is cheap. If this does not match, however, the string is then canonicalized (by converting it into a JID) and the parts are compared again; this may require expensive heap allocations. If constructing a JID from the string fails, the comparison always fails (even if the original JID is would match the invalid output). Comparisons involving unsafe JIDs constructed with Jid::new_unchecked should construct an unsafe JID from the string and manually compare the parts.

Examples

let j = Jid::from_str("example.net/rp")?;
assert!("example.net/rp" == j);

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

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<'a, 'b> PartialEq<Jid<'a>> for &'b str

Allows JIDs to be compared with strings.

This may be expensive. The string is first split using Jid::split and each part is compared with its corresponding part in the JID. If this comparison is successful, true is returned and the comparison is cheap. If this does not match, however, the string is then canonicalized (by converting it into a JID) and the parts are compared again; this may require expensive heap allocations. If constructing a JID from the string fails, the comparison always fails (even if the original JID is would match the invalid output). Comparisons involving unsafe JIDs constructed with Jid::new_unchecked should construct an unsafe JID from the string and manually compare the parts.

fn eq(&self, other: &Jid<'a>) -> bool

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<'a, 'b> PartialEq<Jid<'a>> for Cow<'b, str>

Allows JIDs to be compared with strings.

This may be expensive. The string is first split using Jid::split and each part is compared with its corresponding part in the JID. If this comparison is successful, true is returned and the comparison is cheap. If this does not match, however, the string is then canonicalized (by converting it into a JID) and the parts are compared again; this may require expensive heap allocations. If constructing a JID from the string fails, the comparison always fails (even if the original JID is would match the invalid output). Comparisons involving unsafe JIDs constructed with Jid::new_unchecked should construct an unsafe JID from the string and manually compare the parts.

fn eq(&self, other: &Jid<'a>) -> bool

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<'a, 'b> PartialEq<Jid<'a>> for String

Allows JIDs to be compared with strings.

This may be expensive. The string is first split using Jid::split and each part is compared with its corresponding part in the JID. If this comparison is successful, true is returned and the comparison is cheap. If this does not match, however, the string is then canonicalized (by converting it into a JID) and the parts are compared again; this may require expensive heap allocations. If constructing a JID from the string fails, the comparison always fails (even if the original JID is would match the invalid output). Comparisons involving unsafe JIDs constructed with Jid::new_unchecked should construct an unsafe JID from the string and manually compare the parts.

fn eq(&self, other: &Jid<'a>) -> bool

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<'a, 'b> PartialEq<String> for Jid<'a>

Allows JIDs to be compared with strings.

This may be expensive. The string is first split using Jid::split and each part is compared with its corresponding part in the JID. If this comparison is successful, true is returned and the comparison is cheap. If this does not match, however, the string is then canonicalized (by converting it into a JID) and the parts are compared again; this may require expensive heap allocations. If constructing a JID from the string fails, the comparison always fails (even if the original JID is would match the invalid output). Comparisons involving unsafe JIDs constructed with Jid::new_unchecked should construct an unsafe JID from the string and manually compare the parts.

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

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq<str> for Jid<'_>

Allows JIDs to be compared with strings.

This may be expensive. The string is first split using Jid::split and each part is compared with its corresponding part in the JID. If this comparison is successful, true is returned and the comparison is cheap. If this does not match, however, the string is then canonicalized (by converting it into a JID) and the parts are compared again; this may require expensive heap allocations. If constructing a JID from the string fails, the comparison always fails (even if the original JID is would match the invalid output). Comparisons involving unsafe JIDs constructed with Jid::new_unchecked should construct an unsafe JID from the string and manually compare the parts.

Examples

let j = Jid::from_str("example.net/rp")?;
assert!(j == "example.net/rp");

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

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<'a> PartialEq for Jid<'a>

fn eq(&self, other: &Jid<'a>) -> bool

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<'a> PartialOrd for Jid<'a>

fn partial_cmp(&self, other: &Jid<'a>) -> 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.

impl<'a> Eq for Jid<'a>

impl<'a> StructuralPartialEq for Jid<'a>