Struct xmpp_addr::Jid

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

A parsed JID.

Methods

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> From<Ipv4Addr> for Jid<'a>

Creates a JID from an IPv4 address.

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

Performs the conversion.

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

Creates a JID from an IPv6 address.

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

Performs the conversion.

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

Creates a JID from an IP address.

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

Performs the conversion.

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

impl<'a> PartialOrd<Jid<'a>> 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: &Jid<'a>) -> bool

This method tests less than (for self and other) and is used by the < operator.

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

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

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

This method tests greater than (for self and other) and is used by the > operator.

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

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

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

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

This method tests for self and other values to be equal, and is used by ==.

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

This method tests for !=.

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

This method tests for self and other values to be equal, and is used by ==.

#[must_use] fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

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

This method tests for self and other values to be equal, and is used by ==.

#[must_use] fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

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

This method tests for self and other values to be equal, and is used by ==.

#[must_use] fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

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

This method tests for self and other values to be equal, and is used by ==.

#[must_use] fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

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

This method tests for self and other values to be equal, and is used by ==.

#[must_use] fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

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

This method tests for self and other values to be equal, and is used by ==.

#[must_use] fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

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

This method tests for self and other values to be equal, and is used by ==.

#[must_use] fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

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

This method tests for self and other values to be equal, and is used by ==.

#[must_use] fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

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

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

Returns a copy of the value.

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

Performs copy-assignment from source.

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

Compares and returns the maximum of two values.

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

Compares and returns the minimum of two values.

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.