Generics

fn largest_i32(list: &[i32]) -> i32 {
    let mut max = list[0];
    for &x in list {
        if x > max { max = x; }
    }
    max
}

fn largest_char(list: &[char]) -> char {
    let mut max = list[0];
    for &x in list {
        if x > max { max = x; }
    }
    max
}

fn largest<T: PartialOrd + Copy>(list: &[T]) -> T {
    let mut max = list[0];
    for &x in list {
        if x > max { max = x; }
    }
    max
}

let a = largest(&[3, 7, 2]);       // T = i32
let b = largest(&['a', 'z']);      // T = char

fn identity<T>(x: T) -> T {
    x
}

fn pair<A, B>(a: A, b: B) -> (A, B) {
    (a, b)
}

fn first<T>(v: &[T]) -> Option<&T> {
    v.first()
}

Without a bound, you can do almost nothing with a T: move it, return it, store it. Not print it, compare it or copy it.

let a = identity(5);                  // inferred: i32
let b = identity::<u8>(5);            // turbofish
let c: u64 = identity(5);             // inferred from the expected type

let v = Vec::<String>::new();         // turbofish on a type
let n = "42".parse::<i32>();

The turbofish (::<T>) is used when nothing lets the compiler guess the type.

use std::fmt::Display;

fn show<T: Display>(x: T) {
    println!("{x}");              // allowed thanks to Display
}

fn show_twice<T: Display + Clone>(x: T) {
    let copy = x.clone();         // allowed thanks to Clone
    println!("{x} {copy}");
}

use std::fmt::{Debug, Display};

// 1. Inline
fn summary_v1<T: Display + Clone, U: Debug>(a: T, b: U) -> String {
    format!("{a} / {b:?}")
}

// 2. where clause: more readable when the bounds are long
fn summary_v2<T, U>(a: T, b: U) -> String
where
    T: Display + Clone,
    U: Debug,
{
    format!("{a} / {b:?}")
}

// 3. impl Trait as an argument: without naming the type
fn summary_v3(a: impl Display + Clone, b: impl Debug) -> String {
    format!("{a} / {b:?}")
}

use std::collections::HashMap;
use std::hash::Hash;

fn count<T>(items: &[T]) -> HashMap<&T, usize>
where
    T: Hash + Eq,
{
    let mut m = HashMap::new();
    for e in items {
        *m.entry(e).or_insert(0) += 1;
    }
    m
}

fn show_all<I>(it: I)
where
    I: IntoIterator,
    I::Item: std::fmt::Display,       // bound on the type of the elements
{
    for x in it {
        println!("{x}");
    }
}

fn evens(limit: u32) -> impl Iterator<Item = u32> {
    (0..limit).filter(|x| x % 2 == 0)
}

As a return type, impl Trait means "one precise type, which I do not name". It is not a generic chosen by the caller: the function chooses, and it must always return the same type.

struct Point<T> {
    x: T,
    y: T,
}

let integers = Point { x: 5, y: 10 };
let floats = Point { x: 1.0, y: 4.0 };
// let mixed = Point { x: 5, y: 4.0 };   // ERROR: x and y must have the same T

struct Point2<T, U> {
    x: T,
    y: U,
}
let mixed = Point2 { x: 5, y: 4.0 };     // OK

// 1. On the struct: every use of SortedVec1<T> requires Ord, even those that do not sort
struct SortedVec1<T: Ord> { v: Vec<T> }

// 2. On the impl block only (recommended): the struct stays freely usable
struct SortedVec2<T> { v: Vec<T> }

impl<T: Ord> SortedVec2<T> {
    fn insert(&mut self, x: T) {
        let pos = self.v.binary_search(&x).unwrap_or_else(|p| p);
        self.v.insert(pos, x);
    }
}

Putting the bound on the struct forces you to repeat it everywhere the type appears (every impl, every function that receives it). Put it on the struct only if the type makes no sense without it.

impl<T> Point<T> {
    fn x(&self) -> &T {
        &self.x
    }
}

impl<T> declares T, Point<T> uses it. Without the <T> after impl, Rust would look for a type that is really named T.

impl Point<f64> {
    fn distance_from_origin(&self) -> f64 {
        (self.x * self.x + self.y * self.y).sqrt()
    }
}

let p = Point { x: 3.0, y: 4.0 };
p.distance_from_origin();            // 5.0
let q = Point { x: 3, y: 4 };
// q.distance_from_origin();         // ERROR: only exists for Point<f64>

impl<T> Point2<T, T> {
    fn mix<V>(self, other: Point2<V, V>) -> Point2<T, V> {
        Point2 { x: self.x, y: other.y }
    }
}

T comes from the type, V belongs to the method and is chosen at each call.

use std::fmt::Display;

struct Pair<T> { a: T, b: T }

impl<T> Pair<T> {
    fn new(a: T, b: T) -> Self { Self { a, b } }       // for all T
}

impl<T: Display + PartialOrd> Pair<T> {
    fn print_largest(&self) {                           // only if T is comparable and displayable
        if self.a >= self.b {
            println!("{}", self.a);
        } else {
            println!("{}", self.b);
        }
    }
}

Pair<Vec<i32>> exists, but does not have print_largest (Vec is not Display).

trait Summary {
    fn summary(&self) -> String;
}

impl<T: std::fmt::Display> Summary for T {
    fn summary(&self) -> String {
        let s = self.to_string();
        if s.chars().count() > 10 {
            format!("{}…", s.chars().take(10).collect::<String>())   // in characters, not bytes
        } else {
            s
        }
    }
}

println!("{}", 12345.summary());
println!("{}", "a fairly long text".summary());

This is a blanket implementation (blanket impl). The standard library does the same: impl<T: Display> ToString for T gives .to_string() to every displayable type. You can write only one per trait and per form: it then prevents you from implementing the same trait by hand for a Display type.

fn double<T: std::ops::Add<Output = T> + Copy>(x: T) -> T { x + x }

double(2_i32);
double(2.5_f64);

The compiler generates one copy of the function per type used, as if you had written:

fn double_i32(x: i32) -> i32 { x + x }
fn double_f64(x: f64) -> f64 { x + x }

// The whole function is duplicated for each type that implements AsRef<Path>
pub fn read_v1<P: AsRef<std::path::Path>>(path: P) -> std::io::Result<String> {
    let path = path.as_ref();
    // ... fifty lines ...
    std::fs::read_to_string(path)
}

// Only the conversion is generic; the body is compiled once
pub fn read_v2<P: AsRef<std::path::Path>>(path: P) -> std::io::Result<String> {
    fn inner(path: &std::path::Path) -> std::io::Result<String> {
        // ... fifty lines ...
        std::fs::read_to_string(path)
    }
    inner(path.as_ref())
}

The standard library uses this technique (std::fs::read_to_string itself).

trait Shape {
    fn area(&self) -> f64;
}

struct Square(f64);
struct Circle(f64);
impl Shape for Square { fn area(&self) -> f64 { self.0 * self.0 } }
impl Shape for Circle { fn area(&self) -> f64 { 3.14159 * self.0 * self.0 } }

// 1. Generic: all the elements have THE SAME type
fn total_generic<S: Shape>(shapes: &[S]) -> f64 {
    shapes.iter().map(|s| s.area()).sum()
}

// 2. dyn Trait: each element can have a different type
fn total_dyn(shapes: &[Box<dyn Shape>]) -> f64 {
    shapes.iter().map(|s| s.area()).sum()
}

fn main() {
    total_generic(&[Square(1.0), Square(2.0)]);
    // total_generic(&[Square(1.0), Circle(2.0)]);   // ERROR: different types
    total_dyn(&[Box::new(Square(1.0)), Box::new(Circle(2.0))]);
}

fn sum<const N: usize>(t: [i32; N]) -> i32 {
    t.iter().sum()
}

sum([1, 2, 3]);           // N = 3
sum([1, 2, 3, 4, 5]);     // N = 5

struct Buffer<const SIZE: usize> {
    data: [u8; SIZE],
    length: usize,
}

impl<const SIZE: usize> Buffer<SIZE> {
    fn new() -> Self {
        Self { data: [0; SIZE], length: 0 }
    }
    fn capacity(&self) -> usize { SIZE }
}

let t = Buffer::<64>::new();

struct Counter<T = u32> {
    value: T,
}

let a: Counter = Counter { value: 5 };          // T = u32
let b: Counter<u64> = Counter { value: 5 };

This is how HashMap<K, V, S = RandomState> lets you choose the hashing algorithm without imposing it on everyone.

use std::marker::PhantomData;

struct Id<T> {
    value: i64,
    _type: PhantomData<T>,       // Id<T> "carries" T without storing it
}

struct User;
struct Order;

impl<T> Id<T> {
    fn new(value: i64) -> Self { Self { value, _type: PhantomData } }
}

fn cancel(_id: Id<Order>) {}

fn main() {
    let u: Id<User> = Id::new(1);
    // cancel(u);                   // ERROR: Id<User> is not Id<Order>
    cancel(Id::new(7));
}

Rust rejects an unused type parameter (parameter T is never used). PhantomData<T> uses it without taking up any memory. What it is for: telling apart at compile time values with the same representation (identifiers, units of measure, builder states).

fn length_v1<T: AsRef<str>>(x: T) -> usize { x.as_ref().len() }

// Accept &str directly as a &T with T = str
fn show<T: std::fmt::Display + ?Sized>(x: &T) {
    println!("{x}");
}

show("text");          // T = str: possible thanks to ?Sized
show(&5);

// 1. Copy: returns a copy, reserved for small types
fn max_v1<T: PartialOrd + Copy>(v: &[T]) -> Option<T> {
    let mut iter = v.iter().copied();
    let mut max = iter.next()?;
    for x in iter {
        if x > max { max = x; }
    }
    Some(max)
}

// 2. Reference: also works with String, without copying
fn max_v2<T: PartialOrd>(v: &[T]) -> Option<&T> {
    let mut max = v.first()?;
    for x in v {
        if x > max { max = x; }
    }
    Some(max)
}

// 3. Ord + standard library
fn max_v3<T: Ord>(v: &[T]) -> Option<&T> {
    v.iter().max()
}

// 4. Any iterator, not only a slice
fn max_v4<I>(it: I) -> Option<I::Item>
where
    I: IntoIterator,
    I::Item: Ord,
{
    it.into_iter().max()
}

fn main() {
    max_v1(&[3, 9, 2]);                     // Some(9)
    max_v2(&[String::from("a"), String::from("b")]);
    max_v3(&["apple", "kiwi"]);
    max_v4(vec![1, 5, 3]);
    max_v4((1..10).map(|x| x * x % 7));
    max_v2(&[1.5, 0.2]);                    // f64: PartialOrd is enough for max_v2
    // max_v3(&[1.5, 0.2]);                 // ERROR: f64 is not Ord
}

// fn sum<T>(a: T, b: T) -> T { a + b }
// ERROR E0369: cannot add `T` to `T`
use std::ops::Add;
fn sum<T: Add<Output = T>>(a: T, b: T) -> T { a + b }

The compiler often suggests the missing bound in its message (consider restricting type parameter T).

// fn show<T>(x: T) { println!("{}", x); }
// ERROR E0277: `T` doesn't implement `std::fmt::Display`
fn show<T: std::fmt::Display>(x: T) { println!("{x}"); }

// let v = Vec::new();            // ERROR E0282: type annotations needed
let v: Vec<i32> = Vec::new();
let w = Vec::<i32>::new();

// fn first<T>(v: &[T]) -> T { v[0] }   // ERROR: cannot move out of index
fn first_ref<T>(v: &[T]) -> &T { &v[0] }
fn first_copy<T: Copy>(v: &[T]) -> T { v[0] }
fn first_clone<T: Clone>(v: &[T]) -> T { v[0].clone() }

fn f<T>(x: T) -> T                         // generic
fn f<T: A + B>(x: T)                       // inline bounds
fn f<T>(x: T) where T: A + B               // where
fn f(x: impl A + B)                        // impl Trait as an argument
fn f() -> impl Iterator<Item = u32>        // impl Trait as a return type
struct S<T> { x: T }                       // generic struct
impl<T> S<T> { }                           // for all T
impl S<f64> { }                            // for a specific type
impl<T: Display> S<T> { }                  // conditional methods
impl<T: Display> MyTrait for T { }         // blanket implementation
fn f<const N: usize>(t: [u8; N])           // const generic
struct S<T = u32>                          // default type
PhantomData<T>                             // parameter without data
fn f<T: ?Sized>(x: &T)                     // accepts str, [T], dyn Trait
f::<u8>(5)                                 // turbofish