Overloading stream insertion for your own types

Understanding Overloading stream insertion for your own types

`std::cout << value` is a function call: the compiler looks for an overload of `operator<<` whose left operand is a stream and whose right operand is your type. For a member operator the left operand is always the object the function belongs to, so a member `operator<<` on your class would only support `myObject << std::cout`, and you cannot add a member to `std::ostream` because that class is not yours. That is why insertion is written as a free function at namespace scope, with the stream as the first parameter and your type as the second.

Every part of `std::ostream& operator<<(std::ostream& os, const Fraction& f)` is forced by something concrete. The stream is taken by non-const reference because inserting characters mutates it (buffer contents, error flags, the width that `setw` just set) and because streams are not copyable. Your type is taken by `const&` so that const objects and temporaries bind to it and nothing is copied. The return type is a reference to that same stream because `<<` is left-associative: `std::cout << a << b` means `(std::cout << a) << b`, so the first call has to hand a stream back for the second one to write into.

The mental model is that your operator is a guest writing into a stream somebody else owns and configured. It should emit exactly the characters that represent the value and nothing more: no trailing newline, no `std::endl`, no headers or labels the caller did not ask for. It must also write through `os` rather than `std::cout`, otherwise the same object cannot be sent to a file or an `std::ostringstream`. Whether you need `friend` is a separate decision: use it when the operator reads private members, and skip it when public const accessors already expose everything it prints.

#include <iostream>
#include <sstream>
#include <string>

class Fraction {
public:
    Fraction(int numerator, int denominator)
        : num_(numerator), den_(denominator) {}

    // Grants the free function access to num_ and den_.
    friend std::ostream& operator<<(std::ostream& os, const Fraction& f);

private:
    int num_;
    int den_;
};

// Non-member: the left operand is the stream, not a Fraction.
std::ostream& operator<<(std::ostream& os, const Fraction& f) {
    os << f.num_ << '/' << f.den_;  // the value only, no newline
    return os;                      // hand the stream back for chaining
}

int main() {
    Fraction half(1, 2);
    Fraction third(1, 3);

    std::cout << half << " and " << third << '\n';

    std::ostringstream text;
    text << "sum of " << half << " and " << third;
    std::cout << text.str() << '\n';
}

Worked examples

#include <iomanip>
#include <iostream>

class Point {
public:
    Point(double x, double y) : x_(x), y_(y) {}

    // A hidden friend: still a non-member, just written in the class body.
    friend std::ostream& operator<<(std::ostream& os, const Point& p) {
        return os << '(' << p.x_ << ", " << p.y_ << ')';
    }

private:
    double x_;
    double y_;
};

int main() {
    std::cout << std::fixed << std::setprecision(2);
    std::cout << Point(1.5, -0.25) << '\n';
    std::cout << '[' << std::setw(8) << Point(0, 0) << "]\n";
}

#include <iostream>
#include <sstream>
#include <string>

class Tag {
public:
    explicit Tag(const std::string& name) : name_(name) {}
    const std::string& name() const { return name_; }

private:
    std::string name_;
};

std::ostream& operator<<(std::ostream& os, const Tag& t) {
    return os << '<' << t.name() << '>';
}

// Works with any output stream because it only touches the one it is given.
void describe(std::ostream& os, const Tag& t) {
    os << "tag " << t << " has " << t.name().size() << " letters";
}

int main() {
    const Tag div("div");

    describe(std::cout, div);
    std::cout << '\n';

    std::ostringstream buffer;
    describe(buffer, div);
    std::cout << buffer.str().size() << " chars captured\n";
}

Important notes

Common mistakes

Try it yourself