Skip to content
Tutorials Center
My learning

Topics

Rust Reference ยท Core Traits

Arithmetic operator traits

Reference for Rust arithmetic operator traits in std::ops: implementing Add, Sub, Mul, Div, Rem and Neg, Output types, references, scalar mixing and common mistakes.

Every arithmetic operator in Rust is sugar for a trait method in std::ops. a + b calls Add::add(a, b), a - b calls Sub::sub, a * b calls Mul::mul, a / b calls Div::div, a % b calls Rem::rem, and unary -a calls Neg::neg. Implement the trait for your type and the operator works on it.

Each binary trait is generic over the right-hand side type (defaulting to Self) and has an associated Output type, so Vector * f64 can produce a Vector while Vector * Vector produces something else, such as a number.

Rust
impl Add for Point {
    type Output = Point;
    fn add(self, rhs: Point) -> Point { /* ... */ }
}

Try it

Rust A 2D vector with operators

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.

Rust Operators on references and the missing impl

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.

Syntax

Rust
pub trait Add<Rhs = Self> {
    type Output;
    fn add(self, rhs: Rhs) -> Self::Output;
}
// Sub::sub, Mul::mul, Div::div, Rem::rem have the same shape.

pub trait Neg {
    type Output;
    fn neg(self) -> Self::Output;
}
Name Description
Rhs Type of the right operand. Defaults to Self. Implement several Rhs types for mixed operations.
Output Type of the result. Often Self, but any type is allowed.
self The left operand, taken by value.
rhs The right operand, taken by value.

Returns: Self::Output.

Errors / panics / edge cases: the traits themselves never fail. Built-in integers panic on overflow in debug builds and wrap in release builds by default; Div and Rem on integers panic on division by zero. Your own implementations decide their behavior.

Usage notes

  • Operands are moved. a + b consumes both unless the type is Copy or you implement the trait for references (&a + &b). Heavy types such as matrices normally provide reference impls.
  • The left operand picks the impl. Vector * 2.0 needs impl Mul<f64> for Vector. To also allow 2.0 * Vector you must write impl Mul<Vector> for f64, which is allowed because Vector is local to your crate (the orphan rule).
  • Output need not be Self. Dot products, durations (Instant - Instant = Duration) and unit types all use a different Output.
  • No implicit conversions. Money + i64 does not work unless you implement Add<i64>. Rust never converts operand types automatically.
  • Pair with the assign traits. a += b uses AddAssign, not Add. Implement both if you want both forms.
  • Keep operators intuitive. Use them for real arithmetic. For unrelated actions (appending, joining) a named method is clearer.
  • Generic code can require T: Add<Output = T> + Copy to write functions that work over any numeric type.
  • Rem is a remainder, not a modulo: for built-in signed integers the sign follows the left operand. Use rem_euclid for a non-negative result.