Carbon Copy No.13: Operator overloading

[wolffg]

Carbon Copy, August 2026

Here is the new Carbon Copy, your periodic update on the Carbon language!

Carbon Copy is designed for those people who want a high-level view of what's happening on the project. If you'd like to subscribe, you can join announce@carbon-lang.dev. Carbon Copy should arrive roughly (sometimes extremely, extremely roughly) every other month.

Toolchain update

As of #7462 and #7595, Carbon can export generic classes and functions to C++.

C++ can call a Carbon function such as fn F[T: type](t: T) or fn F[T: SomeInterface](t: T). In C++ code, these exported functions act like function templates.

Example:

import Cpp library "<iostream>";

interface Animal {
  fn MakeSomeNoise(self);
}

class Cat {
  impl as Animal {
    fn MakeSomeNoise(unused self) {
      Cpp.std.cout << "Meow!\n";
    }
  }
}

class Dog {
  impl as Animal {
    fn MakeSomeNoise(unused self) {
      Cpp.std.cout << "Woof!\n";
    }
  }
}

fn F[T: Animal](t: T) {
  t.MakeSomeNoise();
}

inline Cpp '''
void G() {
  Carbon::Cat cat;
  Carbon::Dog dog;
  Carbon::F(cat);
  Carbon::F(dog);
}
''';

fn Run() {
    // Outputs Meow Woof
    Cpp.G();
}

See it in Compiler Explorer!

And similarly, C++ can use parameterized classes from Carbon:

import Cpp;

class Pride(T: type) {
  var t: T;
}

class Lion {
  var mane: bool;
}

class Ostrich {
  var height: f32;  // in meters
}

inline Cpp '''
void F() {
  Carbon::Pride<Carbon::Lion> troop;
  troop.t.mane = true;

  Carbon::Pride<Carbon::Ostrich> flock;
  flock.t.height = 2.1;
}
''';

Also: Syntax changes to declarations

First, under Carbon Proposal #7016 updates the syntax for class (and interface/impl) methods to move self into the parameter parentheses (...) and make the type in its binding optional (defaulting to Self).

Secondly, under Carbon Proposal #7254, the :! syntax was officially removed and replaced by a less-noisy system of contextual defaults and explicit phase keywords (generic, template, and runtime). Above, we used the contextual defaults, but check out the proposal for the updates.

This change does break some of the samples in previous spotlights. We'll be looking at updating those soon. Thanks for your patience!

Spotlight: Operator overloading

Ernesta the Knifefish is doing some designs with Carbon, and needs to create a complex number representation, commonly used in electrical engineering to represent both amplitude and wavelength in a single computation.¹

import Cpp library "<iostream>";
private alias std = Cpp.std;

// Define a class representing a complex number.
class Complex {
  var real: f64;
  var imag: f64;
}

When the operand types and the result type are all identical, the + the operator would be overloaded by implementing the Add interface for that type, which would look like this:

impl Complex as Core.Add {
  // Methods use an explicit `self` parameter 
  // The type of `self` is optional and defaults to `Self`
  fn Op(self: Self, other: Self) -> Self {
    // Return a struct literal, which implicitly converts to `Complex`
    return {.real = self.real + other.real, .imag = self.imag + other.imag};
  }
}

Core.Add is a named constraint, making it easier to define the Core.AddWith interface when the parameters and the return type are all the same:

constraint Add {
  extend require impls AddWith(Self) where .Result = Self;
}

Note: Core.Add is not yet implemented and exposed. The above impl is equivalent to this code, which does work in the current toolchain:

// Use `AddWith(Self)`
impl Complex as Core.AddWith(Complex) where .Result = Complex {
  // Methods use an explicit `self` parameter
  // The type of `self` is optional and defaults to `Self`
  fn Op(self, other: Self) -> Self {
    // Return a struct literal, which implicitly converts to `Complex`
    return {.real = self.real + other.real,
            .imag = self.imag + other.imag};
  }
}

The expression x + y is systematically rewritten by the compiler to an interface method call: x.(AddWith(U).Op)(y).

fn Run ()  {
  let c: Complex = {.real = 0.1, .imag = 0.1};
  let d: Complex = {.real = 0.3, .imag = 0.2};
  // Outputs "0.3"
  std.cout << (d + c).imag;
}

See this in Compiler Explorer!

Contrasting overloading to C++

C++ operator overloading is ad-hoc. Coders must choose between writing member functions or declaring free functions in a namespace, relying on an open overload-resolution pass to match them. C++ templates are late-checked and structurally conformant (duck-typed); the compiler only checks if a type supports an operator when the template is instantiated. This results in slow compilations and hard-to-read error messages when a type lacks an operator.

Carbon adheres to the "one static open extension mechanism" principle, that all open extensions, including operator overloading, must go through nominal interface implementations (impl ... as ...). Carbon generics are fully type-checked at the definition site. A generic function that needs to, say, add values constrains its type parameters with the nominal interface (e.g., T impls Add). The compiler verifies that the generic code is valid immediately, without needing to instantiate the code first.

C++ allows developers to define conflicting operators in different translation units or namespaces, which often results in silent and dangerous ODR (One Definition Rule) violations. Carbon enforces implementation coherence via strict orphan and overlap rules. In Carbon, a type can have exactly one implementation of an interface in the entire program. This ensures that learning more about a type (such as importing a library) never silently changes how an expression like x + y behaves.

Mixed types and overloading

The above example only has two identical types being added. Ernesta needs some energy to do her engineering work, so let's do some heterogeneous addition by mixing up some java².

First, let's set up some basic classes and the first homogeneous operator.

import Cpp library "<iostream>";
private alias std = Cpp.std;

class Coffee {
  var ounces: f64;
}

class Chocolate {
  var ounces: f64;
}

class Mocha {
  var ounces: f64;
}

// 1. Homogeneous addition directly using AddWith: Coffee + Coffee -> Coffee.
// Very similar to the above
impl Coffee as Core.AddWith(Coffee) where .Result = Coffee {
  fn Op(self: Self, other: Self) -> Self {
    return {.ounces = self.ounces + other.ounces};
  }
}

Mocha is coffee + chocolate, so we have a specialized AddWith.

// 2. Heterogeneous addition: Chocolate + Coffee -> Mocha.
impl Chocolate as Core.AddWith(Coffee) where .Result = Mocha {
  fn Op(self: Self, other: Coffee) -> Mocha {
    return {.ounces = self.ounces + other.ounces};
  }
}

// 3. Symmetric heterogeneous addition: Coffee + Chocolate -> Mocha.
impl Coffee as Core.AddWith(Chocolate) where .Result = Mocha {
  fn Op(self: Self, other: Chocolate) -> Mocha {
    return {.ounces = self.ounces + other.ounces};
  }
}

Making a new Mocha object looks the same as making Coffee, as they have the same fields, but the automatic conversion of the struct to the return type takes care of knowing we're returning Mocha.

Using generics allows you to define functionality without being specific about implementation:

// Define the coffee machine using definition-checked generics.
class CoffeeMachine {
  // A generic method to blend any two ingredients.
  // Under the modern rules, deduced parameters in `[...]` default 
  // to checked generics. No keywords or punctuation are required!
  fn Blend[U: type, T: Core.AddWith(U)](unused self, ingredient1: T, ingredient2: U) -> T.Result {
    return ingredient1 + ingredient2;
  }
}

Because U and T are declared inside deduced brackets [...], they default to checked generic parameters (symbolic constants) rather than templates. This means the compiler fully type-checks the body of Blend at its definition site, verifying it is valid for any types that satisfy these constraints, without needing to instantiate the code first.

Let's try it out.

fn Run() {
  var machine: CoffeeMachine = {};

  var espresso: Coffee = {.ounces = 2.0};
  var drip: Coffee = {.ounces = 6.0};

  // 1. Blending coffee and coffee -> returns Coffee.
  var double_shot: Coffee = machine.Blend(espresso, drip);
  ((std.cout << "Blended coffee ") << double_shot.ounces) << "oz\n";

  var cocoa: Chocolate = {.ounces = 3.0};
  var americano: Coffee = {.ounces = 8.0};

  // 2. Blending chocolate and coffee -> returns Mocha.
  var morning_mocha: Mocha = machine.Blend(cocoa, americano);
  ((std.cout << "Blended mocha ") << morning_mocha.ounces) << "oz\n";
}

Alas, Ernesta never implemented mixing two mochas together. The checked-generics part of this means if we write an unhandled case, we'll get a simple error at compile time.

fn DoesntCompile() {
    var machine: CoffeeMachine = {};
    var hot_mocha: Mocha = {.ounces = 4.0};
    var cold_mocha: Mocha = {.ounces = 4.0};

    // ❌ at compile time
    // error: cannot convert type `Mocha` into type implementing `Core.AddWith(Mocha)`
    // <source>:44:3: note: while deducing parameters of generic declared here
    var failed: Mocha = machine.Blend(hot_mocha, cold_mocha);
}

The source pointer in the error points directly back to the definition of Blend in CoffeeMachine.

Have a cuppa joe in Compiler Explorer!

Conclusion

As we have often said about Carbon, there is one mechanism for generics to support a variety of features including operator overloading. Learn one thing, you know everything! Also, the intent is always to give short, specific errors no matter what the problem.

There are a lot of choices for the next spotlight. Write it in if you'd like to know more about how we handle C++ macros across the language boundaries, or else if you have another topic you're curious about!

Recent proposals and issues

If you want to keep up on Carbon’s proposals and issues, follow "Last Week In Carbon". Check out the RSS feed!

Recently accepted proposals including:

• Restrict observe declarations to names that are part of the enclosing interface #7545
• Ensure where requirements in named constraints are visible to lookups #7299
• Disallow impl in match_first twice #7493
• Trailing comments #7441
• Replace :! and :? with keywords and contextual defaults #7254
• CharLiteral difference should be an IntLiteral #7314
• Clarify support for imported object-like macros #7308
• Orphan rule for scopes #7140
• Make proposal filenames use 6 digits and include the title #7245
• Updating self syntax and adding static member variables #7016

Recently closed leads issues including:

• Do nested patterns with entirely specified default values also need to specify a default value to accept callee elision? #7529
• Consider renaming Destructor #7508
• Is trivial destruction expressable as a requirement? #6464
• Should we move away from :! syntax for generics and templates? #6932

Wrap-up

Don't forget to subscribe! You can join announce@carbon-lang.dev. If you have comments or would like to contribute to future editions of Carbon Copy, please reach out. And, always, join us any way you can!

We went to Boron because we were after the 6th element in zero-based indexing,
Wolff, Josh, Richard, and the Carbon team

Footnotes

1. Ernesta, is, of course, an electric eel. ³ ↩

2. No, not Java, the liquid kind of java. ↩

3. Eels are knifefish. I just learned that. There are also electric catfish. Who knew? (I mean, outside of the catfish, who definitely knew after an awkward high-five.) ↩