Struct xmpp_addr::Jid

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

A parsed JID.

Methods

impl<'a> Jid<'a>

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);

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");

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");

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");

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");

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());

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");

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());

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");

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());

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");

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());

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

fn fmt(&self, __arg_0: &mut Formatter) -> Result

Formats the value using the given formatter.

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

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

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

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

This method tests for !=.

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

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

fn cmp(&self, __arg_0: &Jid<'a>) -> Ordering

This method returns an Ordering between self and other.

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

fn partial_cmp(&self, __arg_0: &Jid<'a>) -> Option<Ordering>

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

fn lt(&self, __arg_0: &Jid<'a>) -> bool

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

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

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

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

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

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

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

impl<'a> Display for Jid<'a>

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<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> PartialEq<str> for Jid<'a>

Allows JIDs to be compared with strings.

This is expensive. The JID is first converted into its canonical string representation and compared for bit-string identity with the provided string (byte-wise compare). If the string does not match, it is then canonicalized itself (by converting it into a JID) and compared again. If constructing a JID from the string fails, the comparison always fails (even if the original JID is would match the invalid output). Unsafe comparisons should convert the JID to a string and compare strings themselves.

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 ==.

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 is expensive. The JID is first converted into its canonical string representation and compared for bit-string identity with the provided string (byte-wise compare). If the string does not match, it is then canonicalized itself (by converting it into a JID) and compared again. If constructing a JID from the string fails, the comparison always fails (even if the original JID is would match the invalid output). Unsafe comparisons should convert the JID to a string and compare strings themselves.

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

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

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 is expensive. The JID is first converted into its canonical string representation and compared for bit-string identity with the provided string (byte-wise compare). If the string does not match, it is then canonicalized itself (by converting it into a JID) and compared again. If constructing a JID from the string fails, the comparison always fails (even if the original JID is would match the invalid output). Unsafe comparisons should convert the JID to a string and compare strings themselves.

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

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

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 is expensive. The JID is first converted into its canonical string representation and compared for bit-string identity with the provided string (byte-wise compare). If the string does not match, it is then canonicalized itself (by converting it into a JID) and compared again. If constructing a JID from the string fails, the comparison always fails (even if the original JID is would match the invalid output). Unsafe comparisons should convert the JID to a string and compare strings themselves.

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

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

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

This method tests for !=.