Rust glossary
Short definitions of the Rust terms used in this book, with the chapter that explains each one.
| Term | Meaning | Explained in |
|---|---|---|
Anonymous lifetime ('_) | A lifetime written without a name, meaning “the lifetime of the borrowed argument”. | Tempo, meter, swing and feel |
Arc<T> | A shared, reference-counted pointer that is safe to use across threads; the data is freed when the last Arc goes. | Instruments |
| Array | A fixed number of values stored inline, like [u8; 12]; the length is part of the type. | Twelve-tone rows and their rules |
Array map | [T; N]::map calls a closure on each item of an array and gives back a new array of the same length, with no Vec and no collect. | Twelve-tone rows and their rules |
array::from_fn | Builds an array by calling a closure once for each element. | Instruments |
as cast | Converts between number types, or a fieldless enum to its number: PitchClass::D as u8 is 2. | Five crates, and what each one may know |
| Associated function | A function in an impl block without self, called as Type::name(). Note::new is one. | Five crates, and what each one may know |
| Associated type | A type that each implementation of a trait chooses, like type Error = FileError; in an impl TryFrom. | Saving |
| Atomic | A value (like AtomicUsize) that threads can read and write without a lock. | Two threads |
AtomicU64 for an f64 | There is no atomic float, but f64::to_bits turns a float into the u64 with the same bits, and f64::from_bits turns it back, so an AtomicU64 can share one. | MIDI |
| Backtracking | Building an answer a piece at a time, and taking the last piece back when it leads nowhere; usually a function that calls itself. | Twelve-tone rows and their rules |
Big-endian / to_be_bytes | Writing a number’s most significant byte first; 6u32.to_be_bytes() is [0, 0, 0, 6]. MIDI files use it. | MIDI |
| Bit operations | & (and), | (or), ! (not), << and >> (shift) work on the bits of an integer. | Pitch classes, notes and spelling |
bool::then / then_some | Turn a condition into an Option: cond.then_some(x) is Some(x) if cond is true and None if not; cond.then(|| ...) only runs the closure when it is true. | Editing tools as plain functions |
| Borrow | Using a value through a reference (&T shared, &mut T mutable) without taking ownership. | Two threads |
| Borrow checker | The part of the compiler that enforces: one &mut or any number of & at a time, and no reference outliving its value. | Telling the audio thread what changed |
Borrow trait | A promise that an owned type (like PathBuf) hashes and compares exactly like the type it holds (Path), so a HashMap<PathBuf, _> can be searched with a &Path. | Telling the audio thread what changed |
Box<T> | An owned pointer to a value on the heap. | Drawing the windows with egui |
Byte string (b"...") | A string literal that is a &[u8; N] of ASCII codes instead of a &str, like b"MThd". | MIDI |
| Capacity | How many items a Vec can hold before it must allocate more memory. | Two threads |
| Cargo | Rust’s build tool and package manager. | Five crates, and what each one may know |
Cell<T> | A box whose value can be replaced through a shared reference, by moving whole values in and out with get and set (for Copy types); nothing can hold a reference to the inside, so nothing reads it while it changes. | Roman numerals, the harmony keys and chord functions |
cfg / cfg_attr | Conditional compilation: #[cfg(target_os = "windows")] keeps the next item only when the condition is true, and cfg_attr applies an attribute only then. | Three systems and continuous integration |
#[cfg(test)] on an item | Keeps one function (or use, or struct) only in test builds, so a helper that only the tests call does not warn as unused in a normal build. | Micromodes |
checked_add_signed | Adds a signed number to an unsigned one, like usize + isize, and gives None instead of going below zero or overflowing. | Editing tools as plain functions |
chunk_by | Splits a slice into runs of neighbours that belong together, without copying. | The editors |
chunks / chunks_exact | Split a slice into pieces of n items; chunks_exact leaves out a last piece that is too short. | Twelve-tone rows and their rules |
chars / Chars::as_str | text.chars() walks a string one whole character at a time (“♭” is three bytes but one char); as_str() is the part not walked yet, borrowed from the same text. | Pitch classes, notes and spelling |
| Closure | An anonymous function, |args| body, that can capture variables from its surroundings. | Two threads |
| Closure captures fields | Since the 2021 edition, a closure that uses self.plays borrows only that field, not all of self, so other fields can be borrowed at the same time. | The sequencer |
cmp::Reverse | Wraps a value so that it compares the other way round: sorting by Reverse(count) puts the largest count first. | Micromodes |
Collecting Options | Collecting an iterator of Option<T> into an Option<Vec<T>> gives Some of all the values, or None as soon as one item is None. Result works the same way. | Editing tools as plain functions |
const fn | A function simple enough to run while compiling, so it can be used to set a const. | Saving |
| Constant promotion | Writing &[1, 2, 3] of plain constant values gives a &'static borrow, because the compiler stores the values with the program. A function call inside the brackets, even a const fn, is not promoted. | The library |
Copy | A marker trait for small values that are copied instead of moved, like numbers and Note; let held = list[i]; then copies the item out. | Five crates, and what each one may know |
count_ones | How many bits of an integer are 1: the size of a set stored as bits. | Pitch classes, notes and spelling |
| Crate | One library or program; the unit Cargo builds and publishes. | Five crates, and what each one may know |
cycle | Repeats an iterator forever. Safe because iterators are lazy: something else, like zip, decides when to stop. | Editing tools as plain functions |
Declarative macro (macro_rules!) | A macro defined by patterns: macro_rules! hit { ($at:expr, ...) => { ... } } matches what it is given and pastes it into a template, before the code is compiled. | The library |
Default | A trait for “the default value” of a type; on an enum, #[derive(Default)] needs #[default] on one variant. | Five crates, and what each one may know |
| Deref coercion | Rust turning &Vec<T> into &[T] (or &String into &str) automatically where needed. | MIDI |
Dereference (*) | Follow a reference to the value it points at, to read or write it. | The project |
| Derive | #[derive(Trait)] asks the compiler to implement common traits automatically. | Five crates, and what each one may know |
| Derive macro | Code that writes a trait implementation for a type; serde’s #[derive(Serialize)] comes from a crate, not from the compiler. | Saving |
Display | The trait behind {} in format! and behind to_string(). Implement its fmt method once, and every place writes the value the same way. | Five crates, and what each one may know |
| Disjoint borrows | Borrowing two different fields of a struct at once, even one mutably; allowed because they cannot overlap. | Drawing the windows with egui |
div_ceil | Integer division that rounds up: 16.div_ceil(6) is 3, where 16 / 6 is 2. | Micromodes |
drain(..) | Takes every item out of a Vec, in order, and keeps the Vec’s memory for later. | MIDI |
dyn Trait | A trait object: some type implementing Trait, chosen at run time. | Saving |
| Edition | A version of the language (2015, 2018, 2021, 2024) chosen per crate. | Five crates, and what each one may know |
| Enum | A type whose value is one of several variants, each of which can hold data. | Two threads |
| Enum size | An enum takes as much room as its biggest variant; putting a big variant’s data in a Box keeps every value small. Clippy’s large_enum_variant lint points it out. | MIDI |
env! and concat! | Macros that run while the program is compiled: env!("CARGO_PKG_VERSION") becomes the version Cargo read from Cargo.toml, and concat! joins literals into one &'static str, so both can build a const. | Drawing the windows with egui |
expect | Like unwrap, but panics with the message given. It states a promise (“this is always Some”), best kept by a test. | Pitch-class sets, and one harmony with four names |
| Feature | An optional part of a crate, turned on or off in Cargo.toml; features can only add, never take away. | Saving |
find_map | Calls a closure on each item and returns the first Some it gives. | Chords |
flat_map | Maps each item to an iterator and joins all of them into one iterator. | The editors |
Float to integer as | x as usize drops the fraction and saturates: negative numbers and NaN become 0, numbers too big become the type’s maximum. It never panics. | MIDI |
fn pointer | The type of a plain function, like fn(usize) -> Change. Enum variants that hold data are such functions too: Change::RemovePattern builds a Change from a usize. | Telling the audio thread what changed |
Fn / FnMut / FnOnce | The traits closures implement: only reads, mutates its captures, or can be called once. | Instruments |
From / Into | Conversion traits: implementing From<A> for B also gives a.into(). The ? operator uses From to convert errors. | The project |
FromIterator | The trait behind collect(); implement it to collect into your own type. | Pitch classes, notes and spelling |
FromStr / str::parse | The trait for “can be read from text”: implement from_str, and "Am7".parse::<ChordSymbol>() works, as it does for numbers. | Chords |
| Generic | Code written for a placeholder type T, filled in at compile time. | Two threads |
| Glob import | use super::*; brings in every name the other module can see, including a parent’s private items when used from a child. Two glob imports that bring the same name make it ambiguous. | How a demo is written |
HashMap<K, V> | A map from keys to values that finds a key in about the same time however many entries it holds. | Telling the audio thread what changed |
if let / while let | Run a block if (or while) a value matches one pattern. | Drawing the windows with egui |
ilog2 | The integer base-2 logarithm: how many times a number can be halved before reaching 1. 8u8.ilog2() is 3. It panics on 0. | Tempo, meter, swing and feel |
impl Trait | As an argument type: any type with this trait. As a return type: one type with this trait, left unnamed. | The project |
Inner attribute (#![...]) | An attribute that applies to the thing it is written inside, such as the whole crate at the top of main.rs. | Three systems and continuous integration |
| Invariant | A rule that is always true about a value, usually protected by private fields. | Twelve-tone rows and their rules |
is_some_and | true if an Option is Some and its value passes a test, false for None. | Roman numerals, the harmony keys and chord functions |
| Iterator | A lazy sequence of values, transformed with methods like map, filter, count. | How the code is tested |
JoinHandle<T> | What thread::spawn returns. join() waits for the thread to end and gives back what its closure returned, or an Err if it panicked. | Exporting |
| Lazy | Iterators do no work until something pulls items out of them. | Editing tools as plain functions |
Leading underscore (_name) | Tells the compiler that a variable or field is unused on purpose, so it does not warn about it. | Exporting |
let ... else | Destructure a pattern, or run an else block that must leave the function. | Telling the audio thread what changed |
| Let chain | if cond && let Some(x) = value { ... }: conditions and pattern matches in one if (Rust 1.88). | Two threads |
| Literal in a pattern | Event::Key { repeat: false, .. }: a value written in a pattern only matches when the field equals it. | MIDI |
match | Compare a value against patterns; must cover every case. | Two threads |
| Match guard | pattern if condition =>: the arm matches only if the condition is also true. | Chords |
matches! | A macro that is true if a value matches a pattern. | Pitch classes, notes and spelling |
mem::replace | Put a new value into a place and get the old one back. | Two threads |
mem::swap | Exchanges the values behind two &mut references, without copying either. | Undo and redo |
mem::take | Take a value out of a place, leaving the type’s default (such as an empty Vec) behind. | The sequencer |
| Method | A function in an impl block that takes self, &self or &mut self. | Five crates, and what each one may know |
min_by_key | The item of an iterator with the smallest key, or None if there are no items. | Pitch-class sets, and one harmony with four names |
| Module | A namespace inside a crate, usually one file, declared with mod. | Five crates, and what each one may know |
| Monomorphization | The compiler making a specialized copy of generic code for each type used. | Two threads |
| Move | Transferring ownership of a value; the old name becomes unusable. | Two threads |
move closure | A closure that takes ownership of everything it uses instead of borrowing it; needed for a closure given to another thread. | Exporting |
mpsc channel | A queue from the standard library with many senders (Sender can be cloned) and one receiver; try_iter takes what is waiting without waiting for more. | MIDI |
Mutex<T> and poisoning | A lock that lets one thread at a time reach the T inside. If a thread panics while holding it, the mutex is poisoned, and lock returns an error until you take the data anyway with PoisonError::into_inner. | MIDI |
| Newtype | A struct with one field that wraps another type to give it its own meaning. | Pitch classes, notes and spelling |
? operator | Return early with the error if a Result is Err (or an Option is None). | Two threads |
Option::and_then | Calls a closure that itself returns an Option on the value, if there is one; None stays None. | The editors |
Option::as_mut | Turns &mut Option<T> into Option<&mut T>, to use the value inside without moving it out. | Two threads |
Option::filter | Keeps a Some only if a closure says yes, and gives None otherwise. | MIDI |
Option<T> | Some(value) or None; Rust’s replacement for null. | Two threads |
Option::take | Moves the value out of an Option and leaves None in its place; handy to take ownership of something stored in a field. | Exporting |
| Or-pattern | A | B in a pattern matches either A or B. | Drawing the windows with egui |
| Ownership | Every value has exactly one owner, and is dropped when the owner goes away. | Two threads |
partition | Splits an iterator in two by a closure, in one pass: the items it says yes to and the rest, each collected into its own collection. | Micromodes |
partition_point | On a slice sorted so that a test is true for a first part and false for the rest, the index where the false part begins, found by binary search. | Pitch-class sets, and one harmony with four names |
| Panic | An unrecoverable error that stops the current thread (panic!, failed assert!). | Five crates, and what each one may know |
| Property-based test | A test that checks a rule which must hold for any input (“following the changes gives the new project”), rather than one answer for one input. | Telling the audio thread what changed |
pub(crate) | Visible everywhere inside the current crate, but not to other crates. | The project |
pub(super) | Visible to the parent module and everything inside it. | Saving |
| Pure function | A function whose result depends only on its arguments and that changes nothing else; the easiest kind of code to test. | Editing tools as plain functions |
Rc<T> | A reference-counted pointer for one thread: cloning it adds to a count instead of copying the value, which is freed when the last Rc goes. Rc<[T]> shares a slice. | Pitch-class sets, and one harmony with four names |
RAII / Drop | Owning a value means owning its resource; dropping it releases the resource. | Two threads |
| Range | a..b, the numbers from a up to but not including b; a value with methods like contains. | The sequencer |
| Recursion | A function that calls itself on a smaller piece of the problem, until a piece is small enough to answer directly. | Twelve-tone rows and their rules |
rem_euclid | A remainder that is never negative: (-1_i32).rem_euclid(12) is 11, while -1 % 12 is -1. | Pitch classes, notes and spelling |
Result<T, E> | Ok(value) or Err(error); Rust’s way to return errors. | Two threads |
retain | Keeps only the items of a Vec for which a closure returns true, in one pass. | The project |
| RON | Rust Object Notation, a text format that looks like Rust’s own struct syntax; Ferrous Lineup’s project files use it. | Saving |
rsplit_once / split_once | Splits a string at the last (or first) place a pattern occurs, into the parts before and after, or None if it does not occur. | Chords |
rposition | The index of the last item of a slice that matches, searching from the end; position searches from the start. | Micromodes |
saturating_sub | Subtraction that stops at the smallest value (0 for usize) instead of overflowing. | Editing tools as plain functions |
Send | A marker trait: values of this type can be moved to another thread. | Two threads |
| serde | The usual crate for turning Rust values into text or bytes and back, through the Serialize and Deserialize traits. | Saving |
| serde container attributes | #[serde(try_from = "String", into = "String")] on a type saves it as the String its From gives, and reads it back through its TryFrom<String>, so a value read from a file is checked like any other. | Twelve-tone rows and their rules |
| serde field attributes | #[serde(default)] fills in a missing field with its Default when reading; #[serde(skip_serializing_if = "path")] leaves a field out when writing if that function says so. | Saving |
| Slice | A borrowed view of part of an array or Vec: &[T] or &mut [T]. | Two threads |
| Slice pattern | let [a, b, c, ..] = *bytes else { ... }: matches a slice by its shape, naming the first items, so no indexing can panic. | MIDI |
Slice pattern with @ | [first @ .., last] matches a slice of two or more items and names everything but the last as the slice first. | Micromodes |
| State machine | Code that keeps a current state, often an enum, and moves between states as things happen. | Instruments |
'static | A lifetime meaning “lives as long as needed”; for closures, “borrows nothing temporary”. | Two threads |
static item | static NAME: T = ...; is one value at one fixed address for the whole program. A const is pasted in wherever it is used instead. | The library |
step_by | Takes every n-th item of an iterator: (0..8).step_by(2) is 0, 2, 4, 6. | Editing tools as plain functions |
| Struct update syntax | NoteEvent { length: 2, ..note }: a new struct with some fields changed and the rest taken from note. | Drawing the windows with egui |
| Target | The kind of system a program is compiled for, like x86_64-pc-windows-gnu; rustup target add installs Rust’s library for one. | Three systems and continuous integration |
thread::Builder | Starts a thread with options such as a name; its spawn returns a Result instead of panicking when the system refuses. | MIDI |
thread_local! | Declares a value of which each thread has its own copy, reached with .with(...); the app keeps its settings for numerals, note names and language this way, so tests running side by side never see each other’s. | Roman numerals, the harmony keys and chord functions |
| Trait | A set of methods a type promises to provide, like an interface. | Five crates, and what each one may know |
| Trait bound | A requirement on a generic type, such as T: FromSample<f32>. | Two threads |
TryFrom / TryInto | Conversions that can fail, returning a Result. | Saving |
| Tuple | A fixed group of values, possibly of different types, like (usize, Note); it can be matched and taken apart. | Pitch classes, notes and spelling |
| Tuple comparison | Tuples compare item by item: the second item only decides when the first ones are equal. A tuple as a sort key gives tie-breaks in order. | The mixer |
| Tuple struct | A struct whose fields have no names, like struct Note(u8); the fields are read as .0, .1… | Five crates, and what each one may know |
Turbofish (::<>) | Writing a generic function’s type out at the call, as in collect::<Vec<Note>>(), when Rust cannot work it out. | Two threads |
| Type alias | A second name for an existing type: type Hit = (u8, i32);. | The library |
VecDeque<T> | A double-ended queue: a ring buffer that is cheap to add to and take from at both ends. | Undo and redo |
windows | Every run of n neighbours of a slice, overlapping: [1, 2, 3].windows(2) gives [1, 2] and [2, 3]. | How the code is tested |
wrapping_add / wrapping_mul | Arithmetic that wraps around on overflow instead of stopping a debug build, for when wrapping is what you want, as in random numbers. | Twelve-tone rows and their rules |
| Workspace | A group of crates built together with one Cargo.lock. | Five crates, and what each one may know |
zip | Pairs the items of two iterators, (a, b), and stops when either runs out. | Telling the audio thread what changed |
Where to learn more
- The Rust Programming Language (“the book”): installed with Rust, open
it offline with
rustup doc --book. - Rust by Example:
rustup doc --rust-by-example. - The standard library docs:
rustup doc --std.