pep/xmpp-rs-mirror
1
0
Fork 0
mirror of https://gitlab.com/xmpp-rs/xmpp-rs.git synced 2024-07-12 22:21:53 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Better docs for JID types

Browse source
This commit is contained in:
xmppftw 2023-06-20 20:07:26 +02:00
parent e6e73b2fdf
commit cbf3001c7d
1 changed files with 44 additions and 40 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

84
jid/src/lib.rs
View file

@ -10,9 +10,18 @@
#![deny(missing_docs)]
//! Provides a type for Jabber IDs.
//! Represents XMPP addresses, also known as JabberIDs (JIDs) for the [XMPP](https://xmpp.org/) protocol. A [`Jid`] can have between one and three parts in the form `node@domain/resource`:
//! - the (optional) node part designates a specific account/service on a server, for example `username@server.com`
//! - the domain part designates a server, for example `irc.jabberfr.org`
//! - the (optional) resource part designates a more specific client, such as a participant in a groupchat (`jabberfr@chat.jabberfr.org/user`) or a specific client device associated with an account (`user@example.com/dino`)
//!
//! For usage, check the documentation on the `Jid` struct.
//! The [`Jid`] enum can be one of two variants, containing a more specific type:
//! - [`BareJid`] (`Jid::Bare` variant): a JID without a resource
//! - [`FullJid`] (`Jid::Full` variant): a JID with a resource
//!
//! Jids as per the XMPP protocol only ever contain valid UTF-8. However, creating any form of Jid can fail in one of the following cases:
//! - wrong syntax: creating a Jid with an empty (yet declared) node or resource part, such as `@example.com` or `user@example.com/`
//! - stringprep error: some characters were invalid according to the stringprep algorithm, such as mixing left-to-write and right-to-left characters
use core::num::NonZeroU16;
use std::convert::TryFrom;
@ -34,10 +43,10 @@ use inner::InnerJid;
#[cfg_attr(feature = "serde", serde(untagged))]
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub enum Jid {
/// Bare Jid
/// Contains a [`BareJid`], without a resource part
Bare(BareJid),
/// Full Jid
/// Contains a [`FullJid`], with a resource part
Full(FullJid),
}
@ -71,9 +80,8 @@ impl fmt::Display for Jid {
}
impl Jid {
/// Constructs a Jabber ID from a string.
///
/// This is of the form `node`@`domain`/`resource`.
/// Constructs a Jabber ID from a string. This is of the form
/// `node`@`domain`/`resource`, where node and resource parts are optional.
///
/// # Examples
///
@ -99,28 +107,28 @@ impl Jid {
}
}
/// The node part of the Jabber ID, if it exists, else None.
/// The optional node part of the JID.
pub fn node(&self) -> Option<&str> {
match self {
Jid::Bare(BareJid { inner }) | Jid::Full(FullJid { inner }) => inner.node(),
}
}
/// The domain of the Jabber ID.
/// The domain part of the JID.
pub fn domain(&self) -> &str {
match self {
Jid::Bare(BareJid { inner }) | Jid::Full(FullJid { inner }) => inner.domain(),
}
}
/// The resource of the Jabber ID.
/// The optional resource part of the JID.
pub fn resource(&self) -> Option<&str> {
match self {
Jid::Bare(BareJid { inner }) | Jid::Full(FullJid { inner }) => inner.resource(),
}
}
/// Extract a bare JID from this JID, throwing away the resource.
/// Allocate a new [`BareJid`] from this JID, discarding the resource.
pub fn to_bare(&self) -> BareJid {
match self {
Jid::Full(jid) => jid.to_bare(),
@ -128,7 +136,7 @@ impl Jid {
}
}
/// Transforms this JID into a bare JID, throwing away the resource.
/// Transforms this JID into a [`BareJid`], throwing away the resource.
pub fn into_bare(self) -> BareJid {
match self {
Jid::Full(jid) => jid.into_bare(),
@ -184,30 +192,29 @@ impl PartialEq<BareJid> for Jid {
}
}
/// A struct representing a full Jabber ID.
/// A struct representing a full Jabber ID, with a resource part.
///
/// A full Jabber ID is composed of 3 components, of which one is optional:
/// A full JID is composed of 3 components, of which only the node is optional:
///
/// - A node/name, `node`, which is the optional part before the @.
/// - A domain, `domain`, which is the mandatory part after the @ but before the /.
/// - A resource, `resource`, which is the part after the /.
/// - the (optional) node part is the part before the (optional) `@`.
/// - the domain part is the mandatory part between the (optional) `@` and before the `/`.
/// - the resource part after the `/`.
///
/// Unlike a `BareJid`, it always contains a resource, and should only be used when you are certain
/// there is no case where a resource can be missing. Otherwise, use a `Jid` enum.
/// Unlike a [`BareJid`], it always contains a resource, and should only be used when you are certain
/// there is no case where a resource can be missing. Otherwise, use a [`Jid`] or [`BareJid`].
#[derive(Clone, PartialEq, Eq, Hash)]
pub struct FullJid {
inner: InnerJid,
}
/// A struct representing a bare Jabber ID.
/// A struct representing a bare Jabber ID, without a resource part.
///
/// A bare Jabber ID is composed of 2 components, of which one is optional:
/// A bare JID is composed of 2 components, of which only the node is optional:
/// - the (optional) node part is the part before the (optional) `@`.
/// - the domain part is the mandatory part between the (optional) `@` and before the `/`.
///
/// - A node/name, `node`, which is the optional part before the @.
/// - A domain, `domain`, which is the mandatory part after the @.
///
/// Unlike a `FullJid`, it can’t contain a resource, and should only be used when you are certain
/// there is no case where a resource can be set. Otherwise, use a `Jid` enum.
/// Unlike a [`FullJid`], it can’t contain a resource, and should only be used when you are certain
/// there is no case where a resource can be set. Otherwise, use a [`Jid`] or [`FullJid`].
#[derive(Clone, PartialEq, Eq, Hash)]
pub struct BareJid {
inner: InnerJid,
@ -288,9 +295,8 @@ impl<'de> Deserialize<'de> for BareJid {
}
impl FullJid {
/// Constructs a full Jabber ID containing all three components.
///
/// This is of the form `node`@`domain`/`resource`.
/// Constructs a full Jabber ID containing all three components. This is of the form `node@domain/resource`,
/// where node part is optional.
///
/// # Examples
///
@ -316,22 +322,22 @@ impl FullJid {
}
}
/// The node part of the Jabber ID, if it exists, else None.
/// The optional node part of the JID.
pub fn node(&self) -> Option<&str> {
self.inner.node()
}
/// The domain part of the Jabber ID.
/// The domain part of the JID.
pub fn domain(&self) -> &str {
self.inner.domain()
}
/// The resource of the Jabber ID. Since this is a full JID it is always present.
/// The optional resource of the Jabber ID. Since this is a full JID it is always present.
pub fn resource(&self) -> &str {
self.inner.resource().unwrap()
}
/// Extract a bare JID from this full JID, throwing away the resource.
/// Allocate a new [`BareJid`] from this full JID, discarding the resource.
pub fn to_bare(&self) -> BareJid {
let slash = self.inner.slash.unwrap().get() as usize;
let normalized = self.inner.normalized[..slash].to_string();
@ -343,7 +349,7 @@ impl FullJid {
BareJid { inner }
}
/// Transforms this full JID into a bare JID, throwing away the resource.
/// Transforms this full JID into a [`BareJid`], discarding the resource.
pub fn into_bare(mut self) -> BareJid {
let slash = self.inner.slash.unwrap().get() as usize;
self.inner.normalized.truncate(slash);
@ -362,9 +368,7 @@ impl FromStr for BareJid {
}
impl BareJid {
/// Constructs a bare Jabber ID, containing two components.
///
/// This is of the form `node`@`domain`.
/// Constructs a bare Jabber ID, containing two components. This is of the form `node`@`domain`, where node part is optional.
///
/// # Examples
///
@ -389,17 +393,17 @@ impl BareJid {
}
}
/// The node part of the Jabber ID, if it exists, else None.
/// The optional node part of the JID.
pub fn node(&self) -> Option<&str> {
self.inner.node()
}
/// The domain part of the Jabber ID.
/// The domain part of the JID.
pub fn domain(&self) -> &str {
self.inner.domain()
}
/// Constructs a full Jabber ID from a bare Jabber ID, specifying a `resource`.
/// Constructs a [`FullJid`] from the bare JID, by specifying a `resource`.
///
/// # Examples
///