Skip to content
Tutorials Center
My learning

Topics

Rust Reference ยท Core Traits

Bitwise operator traits

Reference for Rust bitwise operator traits: implementing BitAnd, BitOr, BitXor, Not, Shl and Shr for flag sets and custom types, with Output types and examples.

The bitwise operators are traits in std::ops. a & b is BitAnd::bitand, a | b is BitOr::bitor, a ^ b is BitXor::bitxor, unary !a is Not::not, a << n is Shl::shl and a >> n is Shr::shr. Integers and bool already implement them; you implement them for your own types, most commonly flag sets and bit-board wrappers.

Like the arithmetic traits, the binary ones are generic over the right-hand side and have an Output type. For shifts the right-hand side is usually a different type than Self, such as u32.

Rust
impl BitOr for Flags {
    type Output = Flags;
    fn bitor(self, rhs: Flags) -> Flags { Flags(self.0 | rhs.0) }
}

Try it

Rust A permission flag set

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 Shift traits with a different right-hand type

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 BitAnd<Rhs = Self> { type Output; fn bitand(self, rhs: Rhs) -> Self::Output; }
// BitOr::bitor and BitXor::bitxor have the same shape.

pub trait Not { type Output; fn not(self) -> Self::Output; }

pub trait Shl<Rhs = Self> { type Output; fn shl(self, rhs: Rhs) -> Self::Output; }
// Shr::shr has the same shape.
Name Description
Rhs The right operand type. For shifts it is the shift amount and may be any integer type.
Output The result type.
self The left operand, taken by value.

Returns: Self::Output.

Errors / panics / edge cases: shifting a built-in integer by its bit width or more panics in debug builds (overflow check) and masks the amount in release builds. Use checked_shl, wrapping_shl or overflowing_shl to control it. Your own impls define their own rules.

Usage notes

  • ! on integers is bitwise NOT, while on bool it is logical NOT. For unsigned integers !0u8 is 255; for your own flag type, mask the result as shown above so unused bits stay zero.
  • && and || are not overloadable. They short-circuit and always work on bool. Only &, | and ^ can be implemented.
  • Operands are moved, so make flag types Copy.
  • Each shift has many impls. The standard library implements Shl and Shr for every integer type combined with every other integer type, so 1u32 << 3u8 and 1u32 << 3i64 both compile.
  • Pair with assign traits. |=, &=, ^=, <<= and >>= use BitOrAssign and friends.
  • bool supports &, | and ^ without short-circuiting, which is occasionally useful when both sides have side effects.
  • Production flag sets usually use a small macro or crate, but the traits above are all such a crate implements.
  • Precedence: &, ^ and | bind tighter than comparisons in Rust (unlike C), but parentheses make intent obvious.