Std Traits and the Rust API Guidelines

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord, Default)]
pub struct Version {
    pub major: u16,
    pub minor: u16,
    pub patch: u16,
}

impl std::fmt::Display for Version {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "{}.{}.{}", self.major, self.minor, self.patch)
    }
}

fn main() {
    let v = Version { major: 1, minor: 86, patch: 0 };
    assert!(v > Version { major: 1, minor: 75, patch: 9 }); // derived Ord compares fields in order
    assert_eq!(v.to_string(), "1.86.0");
}

use std::fmt;

pub struct ApiKey(String);

impl fmt::Debug for ApiKey {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        let tail = self.0.get(self.0.len().saturating_sub(4)..).unwrap_or("");
        write!(f, "ApiKey(****{tail})")
    }
}

pub struct Client {
    key: ApiKey,
    base_url: String,
    pool: Vec<u8>, // imagine a connection pool without Debug
}

impl fmt::Debug for Client {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("Client")
            .field("key", &self.key)
            .field("base_url", &self.base_url)
            .finish_non_exhaustive() // prints `..` for omitted fields (1.53)
    }
}

fn main() {
    let c = Client { key: ApiKey("sk-123456".into()), base_url: "https://api".into(), pool: vec![] };
    assert_eq!(format!("{c:?}"), r#"Client { key: ApiKey(****3456), base_url: "https://api", .. }"#);
    let _ = &c.pool;
}

use std::hash::{Hash, Hasher};

#[derive(Debug, Clone)]
pub struct CacheKey {
    pub tenant: String,
    pub query: String,
    pub computed_at_ms: u64, // not part of identity
}

impl PartialEq for CacheKey {
    fn eq(&self, other: &Self) -> bool {
        self.tenant == other.tenant && self.query == other.query
    }
}
impl Eq for CacheKey {}

impl Hash for CacheKey {
    fn hash<H: Hasher>(&self, state: &mut H) {
        self.tenant.hash(state);
        self.query.hash(state);
    }
}

[features]
serde = ["dep:serde"]          # `dep:` syntax: Cargo 1.60

[dependencies]
serde = { version = "1", optional = true, features = ["derive"] }

#[derive(Debug, Clone, PartialEq)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
#[cfg_attr(feature = "serde", serde(rename_all = "snake_case"))]
pub struct Config {
    pub max_retries: u32,
    #[cfg_attr(feature = "serde", serde(default))]
    pub verbose: bool,
}

use std::str::FromStr;

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct Port(u16);

#[derive(Debug, Clone, PartialEq, Eq)]
pub enum PortError {
    Zero,
    Parse(std::num::ParseIntError),
}

impl std::fmt::Display for PortError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            PortError::Zero => f.write_str("port 0 is reserved"),
            PortError::Parse(_) => f.write_str("port is not a number"),
        }
    }
}

impl std::error::Error for PortError {
    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
        match self {
            PortError::Parse(e) => Some(e),
            PortError::Zero => None,
        }
    }
}

impl TryFrom<u16> for Port {
    type Error = PortError;
    fn try_from(v: u16) -> Result<Self, Self::Error> {
        if v == 0 { Err(PortError::Zero) } else { Ok(Port(v)) }
    }
}

impl From<Port> for u16 {
    fn from(p: Port) -> u16 {
        p.0
    }
}

impl FromStr for Port {
    type Err = PortError;
    fn from_str(s: &str) -> Result<Self, Self::Err> {
        let n: u16 = s.trim().parse().map_err(PortError::Parse)?;
        Port::try_from(n)
    }
}

fn main() {
    let p: Port = "8080".parse().unwrap();
    let raw: u16 = p.into(); // Into via the blanket impl
    assert_eq!(raw, 8080);
    assert_eq!(Port::try_from(0), Err(PortError::Zero));
}

// Cargo.toml: thiserror = "2"
#[derive(Debug, thiserror::Error)]
#[non_exhaustive]
pub enum FetchError {
    #[error("request to {url} timed out after {secs}s")]
    Timeout { url: String, secs: u64 },
    #[error("server returned status {0}")]
    Status(u16),
    #[error("i/o error")]
    Io(#[from] std::io::Error), // From impl + source() generated
}

pub struct Playlist {
    songs: Vec<String>,
}

pub struct Iter<'a> {
    inner: std::slice::Iter<'a, String>,
}

impl<'a> Iterator for Iter<'a> {
    type Item = &'a str;

    fn next(&mut self) -> Option<&'a str> {
        self.inner.next().map(String::as_str)
    }

    fn size_hint(&self) -> (usize, Option<usize>) {
        self.inner.size_hint()
    }
}

impl ExactSizeIterator for Iter<'_> {}
impl std::iter::FusedIterator for Iter<'_> {}

impl DoubleEndedIterator for Iter<'_> {
    fn next_back(&mut self) -> Option<Self::Item> {
        self.inner.next_back().map(String::as_str)
    }
}

impl Playlist {
    pub fn iter(&self) -> Iter<'_> {
        Iter { inner: self.songs.iter() }
    }
}

impl<'a> IntoIterator for &'a Playlist {
    type Item = &'a str;
    type IntoIter = Iter<'a>;
    fn into_iter(self) -> Iter<'a> {
        self.iter()
    }
}

impl IntoIterator for Playlist {
    type Item = String;
    type IntoIter = std::vec::IntoIter<String>;
    fn into_iter(self) -> Self::IntoIter {
        self.songs.into_iter()
    }
}

impl FromIterator<String> for Playlist {
    fn from_iter<I: IntoIterator<Item = String>>(iter: I) -> Self {
        Playlist { songs: iter.into_iter().collect() }
    }
}

impl Extend<String> for Playlist {
    fn extend<I: IntoIterator<Item = String>>(&mut self, iter: I) {
        self.songs.extend(iter);
    }
}

fn main() {
    let mut p: Playlist = ["a", "b"].into_iter().map(String::from).collect();
    p.extend(["c".to_string()]);
    let mut seen = Vec::new();
    for s in &p {
        seen.push(s);
    }
    assert_eq!(seen, ["a", "b", "c"]);
    assert_eq!(p.iter().rev().next(), Some("c"));
    assert_eq!(p.iter().len(), 3);
}

use std::ops::{Add, AddAssign, Mul, Neg};

#[derive(Debug, Clone, Copy, PartialEq, Default)]
pub struct Vec2 {
    pub x: f64,
    pub y: f64,
}

impl Add for Vec2 {
    type Output = Vec2;
    fn add(self, o: Vec2) -> Vec2 {
        Vec2 { x: self.x + o.x, y: self.y + o.y }
    }
}

impl AddAssign for Vec2 {
    fn add_assign(&mut self, o: Vec2) {
        *self = *self + o;
    }
}

impl Mul<f64> for Vec2 {
    type Output = Vec2;
    fn mul(self, k: f64) -> Vec2 {
        Vec2 { x: self.x * k, y: self.y * k }
    }
}

// Orphan rule allows this: the local type appears as the trait parameter.
impl Mul<Vec2> for f64 {
    type Output = Vec2;
    fn mul(self, v: Vec2) -> Vec2 {
        v * self
    }
}

impl Neg for Vec2 {
    type Output = Vec2;
    fn neg(self) -> Vec2 {
        Vec2 { x: -self.x, y: -self.y }
    }
}

impl std::iter::Sum for Vec2 {
    fn sum<I: Iterator<Item = Vec2>>(iter: I) -> Vec2 {
        iter.fold(Vec2::default(), Add::add)
    }
}

fn main() {
    let a = Vec2 { x: 1.0, y: 2.0 };
    let mut b = 2.0_f64 * a;
    b += -a;
    assert_eq!(b, a);
    assert_eq!([a, a].into_iter().sum::<Vec2>(), a * 2.0);
}

use std::time::Duration;

#[derive(Debug, Clone, PartialEq)]
pub struct Client {
    pub base_url: String,
    pub timeout: Duration,
    pub retries: u32,
}

#[derive(Debug, Clone)]
#[must_use = "builders do nothing until .build() is called"]
pub struct ClientBuilder {
    base_url: String,
    timeout: Duration,
    retries: u32,
}

impl Client {
    pub fn builder(base_url: impl Into<String>) -> ClientBuilder {
        ClientBuilder { base_url: base_url.into(), timeout: Duration::from_secs(30), retries: 3 }
    }
}

impl ClientBuilder {
    pub fn timeout(mut self, timeout: Duration) -> Self {
        self.timeout = timeout;
        self
    }

    pub fn retries(mut self, retries: u32) -> Self {
        self.retries = retries;
        self
    }

    pub fn build(self) -> Client {
        Client { base_url: self.base_url, timeout: self.timeout, retries: self.retries }
    }
}

fn main() {
    let c = Client::builder("https://api.example.com").retries(5).build();
    assert_eq!(c.retries, 5);
}

use std::marker::PhantomData;

#[derive(Debug)]
pub struct Open;
#[derive(Debug)]
pub struct Closed;

#[derive(Debug)]
pub struct Connection<S> {
    addr: String,
    _state: PhantomData<S>,
}

impl Connection<Closed> {
    pub fn new(addr: &str) -> Self {
        Connection { addr: addr.to_owned(), _state: PhantomData }
    }
    pub fn open(self) -> Connection<Open> {
        Connection { addr: self.addr, _state: PhantomData }
    }
}

impl Connection<Open> {
    pub fn send(&mut self, msg: &str) -> usize {
        msg.len()
    }
    pub fn close(self) -> Connection<Closed> {
        Connection { addr: self.addr, _state: PhantomData }
    }
}

impl<S> Connection<S> {
    pub fn addr(&self) -> &str {
        &self.addr
    }
}

fn main() {
    let mut c = Connection::new("db:5432").open();
    assert_eq!(c.send("ping"), 4);
    let c = c.close();
    assert_eq!(c.addr(), "db:5432");
    // c.send("x"); // error[E0599]: no method named `send` found for struct `Connection<Closed>`
}