Crate overload

Provides a macro to simplify operator overloading.

To use, include the following:

extern crate overload;
use overload::overload;
use std::ops; // <- don't forget this or you'll get nasty errors

Introduction

Suppose we have the following struct definition:

#[derive(PartialEq, Debug)]
struct Val {
    v: i32
}

We can overload the addition of Vals like so:

overload!((a: Val) + (b: Val) -> Val { Val { v: a.v + b.v } });

The macro call above generates the following code:

impl ops::Add<Val> for Val {
    type Output = Val;
    fn add(self, b: Val) -> Self::Output {
        let a = self;
        Val { v: a.v + b.v }
    }
}

We are now able to add Vals:

assert_eq!(Val{v:3} + Val{v:5}, Val{v:8});

Owned and borrowed types

If we also wanted to overload addition for the borrowed type &Val we could write:

overload!((a: &Val) + (b: &Val) -> Val { Val { v: a.v + b.v } });

We might also want to overload addition between the owned and borrowed types:

overload!((a: Val) + (b: &Val) -> Val { Val { v: a.v + b.v } });
overload!((a: &Val) + (b: Val) -> Val { Val { v: a.v + b.v } });

Let’s see how we can write these combinations more concisely.

We can include a ? in front of a type to indicate that it should stand in for both the owned and borrowed type.

To overload addition for all four combinations between Val and &Val we can therefore simply include a ? in front of both types:

overload!((a: ?Val) + (b: ?Val) -> Val { Val { v: a.v + b.v } });

The macro call above generates the following code:

impl ops::Add<Val> for Val {
    type Output = Val;
    fn add(self, b: Val) -> Self::Output {
        let a = self;
        Val { v: a.v + b.v }
    }
}
 
impl ops::Add<&Val> for Val {
    type Output = Val;
    fn add(self, b: &Val) -> Self::Output {
        let a = self;
        Val { v: a.v + b.v }
    }
}
 
impl ops::Add<Val> for &Val {
    type Output = Val;
    fn add(self, b: Val) -> Self::Output {
        let a = self;
        Val { v: a.v + b.v }
    }
}
 
impl ops::Add<&Val> for &Val {
    type Output = Val;
    fn add(self, b: &Val) -> Self::Output {
        let a = self;
        Val { v: a.v + b.v }
    }
}

We are now able to add Vals and &Vals in any combination:

assert_eq!(Val{v:3} + Val{v:5}, Val{v:8});
assert_eq!(Val{v:3} + &Val{v:5}, Val{v:8});
assert_eq!(&Val{v:3} + Val{v:5}, Val{v:8});
assert_eq!(&Val{v:3} + &Val{v:5}, Val{v:8});

Binary operators

The general syntax to overload a binary operator between types <a_type> and <b_type> is:

overload!((<a_ident>: <a_type>) <op> (<b_ident>: <b_type>) -> <out_type> { /*body*/ });

Inside the body you can use <a_ident> and <b_ident> freely to perform any computation.

The last line of the body needs to be an expression (i.e. no ; at the end of the line) of type <out_type>.

Operator	Example	Trait
+	overload!((a: A) + (b: B) -> C { /*...*/ );	Add
-	overload!((a: A) - (b: B) -> C { /*...*/ );	Sub
*	overload!((a: A) * (b: B) -> C { /*...*/ );	Mul
/	overload!((a: A) / (b: B) -> C { /*...*/ );	Div
%	overload!((a: A) % (b: B) -> C { /*...*/ );	Rem
&	overload!((a: A) & (b: B) -> C { /*...*/ );	BitAnd
|	overload!((a: A) | (b: B) -> C { /*…*/ );	BitOr
^	overload!((a: A) ^ (b: B) -> C { /*...*/ );	BitXor
<<	overload!((a: A) << (b: B) -> C { /*...*/ );	Shl
>>	overload!((a: A) >> (b: B) -> C { /*...*/ );	Shr

Assignment operators

The general syntax to overload an assignment operator between types <a_type> and <b_type> is:

overload!((<a_ident>: &mut <a_type>) <op> (<b_ident>: <b_type>) { /*body*/ });

Inside the body you can use <a_ident> and <b_ident> freely to perform any computation and mutate <a_ident> as desired.

Operator	Example	Trait
+=	overload!((a: &mut A) += (b: B) { /*...*/ );	AddAssign
-=	overload!((a: &mut A) -= (b: B) { /*...*/ );	SubAssign
*=	overload!((a: &mut A) *= (b: B) { /*...*/ );	MulAssign
/=	overload!((a: &mut A) /= (b: B) { /*...*/ );	DivAssign
%=	overload!((a: &mut A) %= (b: B) { /*...*/ );	RemAssign
&=	overload!((a: &mut A) &= (b: B) { /*...*/ );	BitAndAssign
|=	overload!((a: &mut A) |= (b: B) { /*…*/ );	BitOrAssign
^=	overload!((a: &mut A) ^= (b: B) { /*...*/ );	BitXorAssign
<<=	overload!((a: &mut A) <<= (b: B) { /*...*/ );	ShlAssign
>>=	overload!((a: &mut A) >>= (b: B) { /*...*/ );	ShrAssign

Unary operators

The general syntax to overload a unary operator for type <a_type> is:

overload!(<op> (<a_ident>: <a_type>) -> <out_type> { /*body*/ });

Inside the body you can use <a_ident> freely to perform any computation.

The last line of the body needs to be an expression (i.e. no ; at the end of the line) of type <out_type>.

Operator	Example	Trait
-	overload!(- (a: A) -> B { /*...*/ );	Neg
!	overload!(! (a: A) -> B { /*...*/ );	Not

Notes

Remember that you can only overload operators between one or more types if at least one of the types is defined in the current crate.

Macros

overload

Overloads an operator. See the module level documentation for more information.