Struct xmpp_addr::Jid
[−]
[src]
pub struct Jid<'a> { /* fields omitted */ }
A parsed JID.
Methods
impl<'a> Jid<'a>
[src]
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>>,
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>>,
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>
[src]
impl<'a> Clone for Jid<'a>
[src]
fn clone(&self) -> Jid<'a>
Returns a copy of the value. Read more
fn clone_from(&mut self, source: &Self)
1.0.0
Performs copy-assignment from source
. Read more
impl<'a> PartialEq for Jid<'a>
[src]
fn eq(&self, __arg_0: &Jid<'a>) -> bool
This method tests for self
and other
values to be equal, and is used by ==
. Read more
fn ne(&self, __arg_0: &Jid<'a>) -> bool
This method tests for !=
.
impl<'a> Eq for Jid<'a>
[src]
impl<'a> Ord for Jid<'a>
[src]
fn cmp(&self, __arg_0: &Jid<'a>) -> Ordering
This method returns an Ordering
between self
and other
. Read more
impl<'a> PartialOrd for Jid<'a>
[src]
fn partial_cmp(&self, __arg_0: &Jid<'a>) -> Option<Ordering>
This method returns an ordering between self
and other
values if one exists. Read more
fn lt(&self, __arg_0: &Jid<'a>) -> bool
This method tests less than (for self
and other
) and is used by the <
operator. Read more
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. Read more
fn gt(&self, __arg_0: &Jid<'a>) -> bool
This method tests greater than (for self
and other
) and is used by the >
operator. Read more
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. Read more
impl<'a> Display for Jid<'a>
[src]
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");
impl<'a> From<Ipv4Addr> for Jid<'a>
[src]
Creates a JID from an IPv4 address.
impl<'a> From<Ipv6Addr> for Jid<'a>
[src]
Creates a JID from an IPv6 address.
impl<'a> From<IpAddr> for Jid<'a>
[src]
Creates a JID from an IP address.
impl<'a> PartialEq<str> for Jid<'a>
[src]
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 ==
. Read more
fn ne(&self, other: &Rhs) -> bool
1.0.0
This method tests for !=
.
impl<'a, 'b> PartialEq<Cow<'b, str>> for Jid<'a>
[src]
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 ==
. Read more
fn ne(&self, other: &Rhs) -> bool
1.0.0
This method tests for !=
.
impl<'a, 'b> PartialEq<&'b str> for Jid<'a>
[src]
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 ==
. Read more
fn ne(&self, other: &Rhs) -> bool
1.0.0
This method tests for !=
.
impl<'a, 'b> PartialEq<String> for Jid<'a>
[src]
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.