Type aliases

type Name = ExistingType;

type Kilometers = f64;
type Bytes = Vec<u8>;
type Grid = [[u8; 9]; 9];
type Callback = fn(i32) -> i32;

The name follows the convention for types: PascalCase. An alias can be pub, pub(crate) or private, like any item.

type Kilometers = f64;

fn distance(a: Kilometers, b: Kilometers) -> Kilometers {
    (a - b).abs()
}

let trip: Kilometers = 42.0;
let d = distance(trip, 10.0);

use std::collections::HashMap;

type Scores = HashMap<String, u32>;

struct Game {
    scores: Scores,
}

impl Game {
    fn new() -> Self {
        Self { scores: Scores::new() }     // associated functions go through the alias
    }
}

type Meters = f64;
type Seconds = f64;

fn speed(d: Meters, t: Seconds) -> f64 {
    d / t
}

let d: Meters = 100.0;
let t: Seconds = 9.58;
speed(t, d);              // compiles: the arguments are swapped, no error

use std::collections::HashMap;
use std::sync::{Arc, Mutex};

type Shared<T> = Arc<Mutex<T>>;
type Index<V> = HashMap<String, V>;

let counter: Shared<u32> = Arc::new(Mutex::new(0));
let cities: Index<u32> = Index::new();

use std::collections::HashMap;

type Table<K, V> = HashMap<K, V>;
type TextTable<V> = Table<String, V>;        // K fixed
type CountTable = TextTable<u64>;             // K and V fixed

Each level fixes one more parameter: you start from a generic alias and specialize it.

// type Displayable<T: std::fmt::Display> = Vec<T>;
// warning: bounds on generic parameters are not enforced in type aliases

A bound in an alias is ignored (the compiler warns). Put it on the functions and impl blocks that use the type.

#[derive(Debug)]
pub enum Error {
    NotFound,
    Database(String),
}

pub type Result<T> = std::result::Result<T, Error>;

pub fn load(id: u32) -> Result<String> {
    if id == 0 {
        return Err(Error::NotFound);
    }
    Ok("Ada".into())
}

The standard library does the same: std::io::Result<T>, std::fmt::Result. So do SeaORM, anyhow (anyhow::Result<T>) and Runique (AppResult<T>).

use std::io;

type Result<T> = std::result::Result<T, io::Error>;

// fn parse(s: &str) -> Result<i32, std::num::ParseIntError> { ... }
// ERROR: this Result has only one parameter
fn parse(s: &str) -> std::result::Result<i32, std::num::ParseIntError> {
    s.parse()
}

An alias named Result shadows the prelude one in the whole module. Two ways to avoid the confusion:

// 1. Give it a distinct name
type IoResult<T> = std::result::Result<T, std::io::Error>;

// 2. Use it prefixed from another module: io::Result<T>, my_lib::Result<T>

pub type Outcome<T, E = Error> = std::result::Result<T, E>;

fn a() -> Outcome<u32> { Ok(1) }                         // E = Error
fn b() -> Outcome<u32, String> { Err("other".into()) }   // E chosen

use std::future::Future;
use std::pin::Pin;

type Listener = Box<dyn Fn(&str) + Send + Sync>;
type SendableFuture<T> = Pin<Box<dyn Future<Output = T> + Send>>;
type AsyncHandler = Box<dyn Fn(String) -> SendableFuture<String> + Send + Sync>;

struct Bus {
    listeners: Vec<Listener>,
}

Without an alias, Vec<Box<dyn Fn(&str) + Send + Sync>> comes back in every signature.

type Operation = fn(f64, f64) -> f64;

fn apply(op: Operation, a: f64, b: f64) -> f64 {
    op(a, b)
}

let table: [(&str, Operation); 2] = [("+", |a, b| a + b), ("*", |a, b| a * b)];

use std::collections::HashMap;
use std::sync::{Arc, RwLock};

type Cache = Arc<RwLock<HashMap<String, Vec<u8>>>>;

fn read(cache: &Cache, key: &str) -> Option<Vec<u8>> {
    cache.read().unwrap().get(key).cloned()
}

type Grade = Option<u8>;

let a: Grade = Grade::Some(15);       // variants go through the alias
let b = Grade::None;

#[cfg(feature = "big-numbers")]
pub type Integer = i64;

#[cfg(not(feature = "big-numbers"))]
pub type Integer = i32;

pub fn double(x: Integer) -> Integer { x * 2 }

#[cfg(unix)]
pub type Descriptor = std::os::unix::io::RawFd;      // i32
#[cfg(windows)]
pub type Descriptor = std::os::windows::io::RawHandle;

// 1. Alias: a synonym
type UserId = u32;

// 2. Newtype: a new type
struct OrderId(u32);

// 3. Rename on import: another name for an existing item
use std::collections::HashMap as Table;

// Alias: nothing prevents the mistake
type Euros = i64;
type Cents = i64;
fn pay(amount: Cents) {}
let price: Euros = 12;
pay(price);                               // compiles: bug (12 cents instead of 12 euros)

// Newtype: the mistake becomes a compile error
struct InEuros(i64);
struct InCents(i64);
impl From<InEuros> for InCents {
    fn from(e: InEuros) -> Self { InCents(e.0 * 100) }
}
fn pay2(amount: InCents) {}
// pay2(InEuros(12));                     // ERROR: expected InCents
pay2(InEuros(12).into());                 // explicit conversion

struct Point(i32, i32);
type P = Point;

// let p = P(1, 2);               // ERROR E0423: the alias exists only as a type
let p = Point(1, 2);
let q: P = Point(3, 4);
let r = P { 0: 5, 1: 6 };         // the brace form goes through the alias

For a struct with named fields, P { x, y } works.

type List = Vec<i32>;

// impl std::fmt::Display for List { ... }
// ERROR E0117: Display and Vec come from the standard library (orphan rule)

The alias is Vec<i32>: the implementation would target Vec<i32>, which only the standard library can do. A newtype (struct List(Vec<i32>)) allows it.

Conversely, on an alias of a local type, impl works normally, since it targets the local type.

// src/types.rs
use std::collections::HashMap;
use std::sync::Arc;

pub type StrMap = HashMap<String, String>;
pub type Shared<T> = Arc<T>;
pub type Result<T> = std::result::Result<T, crate::Error>;

// src/lib.rs
pub mod types;
pub use types::*;          // or through a prelude

// runique/src/utils/config/pk.rs
#[cfg(all(feature = "big-pk", feature = "pk-uuid"))]
compile_error!("features `big-pk` and `pk-uuid` are mutually exclusive — enable at most one of them");

#[cfg(feature = "pk-uuid")]
pub type Pk = uuid::Uuid;

#[cfg(all(feature = "big-pk", not(feature = "pk-uuid")))]
pub type Pk = i64;

#[cfg(not(any(feature = "big-pk", feature = "pk-uuid")))]
pub type Pk = i32;

The whole framework writes Pk. Changing the primary key type means changing a feature in Cargo.toml, not hundreds of signatures. The compile_error! prevents enabling two contradictory choices.

// runique/src/db/adb.rs
#[cfg(not(feature = "test-utils"))]
type Inner = sea_orm::DatabaseConnection;
#[cfg(feature = "test-utils")]
type Inner = crate::db::RuniqueDb;      // real connection or test transaction

#[derive(Clone, Debug)]
pub struct ADb(Arc<Inner>);

The alias is private: the user only sees ADb, whatever the feature.

// runique/src/utils/aliases/definition.rs
pub type AEngine = Arc<RuniqueEngine>;
pub type StrMap = HashMap<String, String>;
pub type StrVecMap = HashMap<String, Vec<String>>;
pub type JsonMap = HashMap<String, serde_json::Value>;
pub type AppResult<T> = Result<T, Box<AppError>>;

// In a handler
pub async fn contact(mut request: Request) -> AppResult<Response> {
    // ...
}

// runique/src/app/builder/mod.rs
pub mod state {
    pub struct No;
    pub struct Yes;
    pub type Fresh = (No, No, No, No, No, No, No);
}

Runique's builder records in its type which one-time settings have already been made (No or Yes per setting). Fresh names the starting state: without the alias, you would have to write the tuple of seven No in every signature that mentions it.