References: A Second Name for the Same Box

Maria wrote a swap function in C last month. It took two pointers, put a star in front of every use, and needed an ampersand at every call. Bob forgot one star and spent an evening finding it. C++ has a way to write the same function with no stars and no ampersands at the call. It is called a reference, and every STL lesson after this one leans on it.

Maria's swap, in C and in C++

Here is Maria's C version. A function in C gets copies of its arguments, so to change the caller's x and y it needs their addresses.

#include <stdio.h>

void swap_ptr(int *a, int *b)
{
    int keep = *a;
    *a = *b;
    *b = keep;
}

int main(void)
{
    int x = 3;
    int y = 5;

    swap_ptr(&x, &y);
    printf("x = %d, y = %d\n", x, y);
    return 0;
}

x = 5, y = 3

And here is the same job in C++, with references.

#include <iostream>

void swapRef(int& a, int& b)
{
    int keep = a;
    a = b;
    b = keep;
}

int main()
{
    int x = 3;
    int y = 5;

    swapRef(x, y);
    std::cout << "x = " << x << ", y = " << y << '\n';
    return 0;
}

x = 5, y = 3

The output is the same. Three things moved, and the table names them.

So the C++ swap does the same work, with no address taken at the call and no star inside the function.

A reference is a second name for the same box

A reference is a second name for a variable that already exists. It is not a copy, and it is not a separate variable holding an address. Whatever you do to the reference, you do to the original box.

type& name = existing_variable;

Watch one box under two names.

#include <iostream>

int main()
{
    int score = 7;
    int& r = score;

    std::cout << "score = " << score << ", r = " << r << '\n';
    r = 8;
    std::cout << "after r = 8, score = " << score << '\n';
    score = 9;
    std::cout << "after score = 9, r = " << r << '\n';
    std::cout << "same box: " << (&r == &score) << '\n';
    return 0;
}

score = 7, r = 7
after r = 8, score = 8
after score = 9, r = 9
same box: 1

Writing through r changed score, and writing to score changed what r reads. The last line asks whether the two names have the same address. std::cout prints a true comparison as 1, so they do.

Here is the picture. On the left, one box carries both names. On the right, a pointer p = &score for comparison: the pointer is a second box, with its own address, holding the first box's address.

So r is not a copy of score and not a pointer to it. It is score, under a second name.

Why & means two things

Maria spotted it at once: & already meant "the address of" in C. Now it also means "reference to". Both are real, and the place the sign stands tells them apart.

#include <iostream>

int main()
{
    int x = 5;
    int& r = x;
    int* p = &x;

    std::cout << r << ' ' << *p << '\n';
    std::cout << (6 & 3) << '\n';
    return 0;
}

5 5
2

So read the left side of the &. A type on its left makes a reference, nothing on its left takes an address, and a value on each side is bitwise AND.

Passing by reference: the function works on the caller's box

A function parameter can be a reference. Then the parameter is a second name for the caller's variable, for the length of the call. This is called passing by reference. The ordinary way, where the function gets its own copy, is passing by value.

Step through Maria's swapRef(x, y). When the call starts, a and b become second names for main's boxes, so nothing is copied in and nothing needs to be copied back.

A reference parameter also gives a function a way to hand back more than one result. Kenji's till records each sale in two running numbers.

#include <iostream>

void addSale(int price, int& count, long long& total)
{
    count = count + 1;
    total = total + price;
}

int main()
{
    int count = 0;
    long long total = 0;

    addSale(120, count, total);
    addSale(80, count, total);
    addSale(45, count, total);
    std::cout << count << " sales, total " << total << '\n';
    return 0;
}

3 sales, total 245

price is passed by value, because the function only reads it. count and total are passed by reference, because the function must change main's copies.

Bob noticed something here. scanf("%d", &x) needs an ampersand, but std::cin >> x does not. The reason is this lesson: the >> that reads an int takes its right side as an int&. So std::cin writes straight into your box, and the ampersand disappears.

So a reference parameter lets a function work on the caller's own box, which is exactly what C did with a pointer, minus the stars.

The three rules a reference keeps

A pointer can be empty, can be changed to point elsewhere, and can be left without a value. A reference can do none of those. Each rule is checked by the compiler or shown by a run.

Rule 1: a reference is born naming a box. A reference with no box is refused.

int& r;

GCC 12 says, on the Playground's command line and with -Wall -Wextra alike: error: 'r' declared as reference but not initialized.

Rule 2: a reference is never null. There is no "reference to nothing" to start from.

int& r = nullptr;

GCC 12 refuses it at every command line: error: invalid initialization of non-const reference of type 'int&' from an rvalue of type 'std::nullptr_t'. nullptr is C++'s null pointer, the NULL of C with a type of its own.

Rule 3: a reference never moves to another box. This one compiles, so watch what it does.

#include <iostream>

int main()
{
    int a = 10;
    int b = 20;
    int& r = a;

    r = b;
    r = 99;
    std::cout << a << ' ' << b << ' ' << r << '\n';
    return 0;
}

99 20 99

r = b; looks as if r now names b. It does not: it copies 20 into a, the box r has named since birth. So r = 99 also lands in a, and b keeps its 20.

So a reference is set once, at its declaration, to a real box, and it names that box until it goes out of scope.

const&: read a big value without copying it

Passing by value copies the argument. For an int that is four bytes, and nobody notices. For a list of a million numbers it is four million bytes, copied again on every call.

A const reference, written const type&, gives the function the caller's box under a read-only name. Nothing is copied, and the function promises not to change the box. The compiler holds it to that promise.

void show(const int& x)
{
    x = 7;
}

GCC 12, at every command line: error: assignment of read-only reference 'x'.

Here is the cost measured. The program builds a list of 1,000,000 int values with std::vector, an array that knows its own size; Module 2 teaches it. It sums the list 100 times through a by-value parameter, then 100 times through a const& one, and times both with <chrono>, the standard clock.

#include <chrono>
#include <iostream>
#include <vector>

long long sumByValue(std::vector<int> v)
{
    long long total = 0;
    for (int i = 0; i < (int)v.size(); i++) {
        total += v[i];
    }
    return total;
}

long long sumByConstRef(const std::vector<int>& v)
{
    long long total = 0;
    for (int i = 0; i < (int)v.size(); i++) {
        total += v[i];
    }
    return total;
}

int main()
{
    std::vector<int> big(1000000, 1);
    const int calls = 100;

    auto t0 = std::chrono::steady_clock::now();
    long long a = 0;
    for (int c = 0; c < calls; c++) {
        a += sumByValue(big);
    }
    auto t1 = std::chrono::steady_clock::now();
    long long b = 0;
    for (int c = 0; c < calls; c++) {
        b += sumByConstRef(big);
    }
    auto t2 = std::chrono::steady_clock::now();

    std::chrono::duration<double, std::milli> byValue = t1 - t0;
    std::chrono::duration<double, std::milli> byRef = t2 - t1;
    std::cout << "by value:     " << a << " in " << byValue.count() << " ms\n";
    std::cout << "by const ref: " << b << " in " << byRef.count() << " ms\n";
    return 0;
}

The times change from run to run, so they sit in a table rather than an output block. This is one run on Compiler Explorer, x86-64 GCC 12.2, at the Playground's flags, -O2 -std=c++17.

Both give the same sum. The by-value version is about 2.7 times slower, and every extra millisecond is copying: 400 MB moved over 100 calls to read numbers that never changed.

The usual advice, from the C++ Core Guidelines, rule F.16: pass small things such as int, double and char by value, and anything bigger by const&. So const& is how a function reads a big value: the caller's own box, read-only, at no copying cost.

A preview: the range-for by reference

Lesson 04 teaches the range-for, a loop that visits every box of an array in turn. One part of it belongs here, because it is a reference again.

#include <iostream>

int main()
{
    int marks[4] = {70, 85, 62, 91};

    for (int m : marks) {
        m = m + 5;
    }
    std::cout << "after a copy loop:      " << marks[0] << ' ' << marks[3] << '\n';

    for (int& m : marks) {
        m = m + 5;
    }
    std::cout << "after a reference loop: " << marks[0] << ' ' << marks[3] << '\n';
    return 0;
}

after a copy loop:      70 91
after a reference loop: 75 96

In the first loop, m is a copy of each box, so adding 5 to it changes nothing in marks. In the second, m is a second name for each box in turn, so the marks really change. One & decides it.

Pointer or reference: which one, when

References do not replace pointers. Each does a job the other cannot, and the table puts them side by side.

Choose a reference for a parameter the function changes, and const& for a big one it only reads. Choose a pointer when "nothing" is a real answer, when it must walk along an array, or when the code is shared with C. The STL hands you references almost everywhere, and Module 11 shows the one pointer-like thing it adds: the iterator.

#include <iostream>

void clampTemp(int& t, int low, int high)
{
    if (t < low) {
        t = low;
    }
    if (t > high) {
        t = high;
    }
}

int main()
{
    int a = 25;
    int b = -55;
    int c = 70;

    clampTemp(a, -40, 60);
    clampTemp(b, -40, 60);
    clampTemp(c, -40, 60);
    std::cout << a << ' ' << b << ' ' << c << '\n';
    return 0;
}

25 -40 60

#include <iostream>

bool readMark(int& mark)
{
    std::cin >> mark;
    return mark >= 0 && mark <= 100;
}

int main()
{
    int mark = 0;
    int good = 0;
    int bad = 0;

    for (int i = 0; i < 4; i++) {
        if (readMark(mark)) {
            good++;
        } else {
            bad++;
            std::cout << "rejected " << mark << '\n';
        }
    }
    std::cout << good << " good, " << bad << " bad\n";
    return 0;
}

rejected 120
rejected -3
2 good, 2 bad

#include <iostream>
#include <string>

const int MAX_N = 100;

void applyDiscount(int& price, int percent)
{
    price = price - price * percent / 100;
}

void printList(const std::string& shop, const int prices[], int n)
{
    std::cout << shop << ':';
    for (int i = 0; i < n; i++) {
        std::cout << ' ' << prices[i];
    }
    std::cout << '\n';
}

int main()
{
    int prices[MAX_N] = {0};
    int n = 0;
    int percent = 0;
    std::string shop = "Amara's Books";

    std::cin >> n;
    for (int i = 0; i < n; i++) {
        std::cin >> prices[i];
    }
    std::cin >> percent;

    printList(shop, prices, n);
    for (int i = 0; i < n; i++) {
        applyDiscount(prices[i], percent);
    }
    printList(shop, prices, n);
    return 0;
}

Amara's Books: 400 250 120 90
Amara's Books: 300 188 90 68

void swapValues(int a, int b)
{
    int keep = a;
    a = b;
    b = keep;
}

swapRef(3, 5);

int& bad()
{
    int local = 42;
    return local;
}

const int limit = 10;
int& r = limit;

#include <iostream>

int main()
{
    const int& r = 5;
    std::cout << r << '\n';
    return 0;
}

#include <iostream>

const int MAX_N = 100;

// Add bonus to mark, but never above 100.
void addBonus(int& mark, int bonus)
{
    // your code
}

int main()
{
    int marks[MAX_N] = {0};
    int n = 0;
    int bonus = 0;

    std::cin >> n;
    for (int i = 0; i < n; i++) {
        std::cin >> marks[i];
    }
    std::cin >> bonus;

    // Call addBonus on every mark, then print the marks on one line.

    return 0;
}

#include <iostream>

const int MAX_N = 100;

// Put the smallest of a[0] to a[n - 1] in lo and the largest in hi.
void minMax(const int a[], int n, int& lo, int& hi)
{
    // your code
}

int main()
{
    int a[MAX_N] = {0};
    int n = 0;

    std::cin >> n;
    for (int i = 0; i < n; i++) {
        std::cin >> a[i];
    }

    int lo = 0;
    int hi = 0;
    minMax(a, n, lo, hi);
    std::cout << lo << ' ' << hi << '\n';
    return 0;
}

#include <iostream>

// Put a and b in order: after the call, a <= b.
void order(int& a, int& b)
{
    // your code
}

int main()
{
    std::ios::sync_with_stdio(false);
    std::cin.tie(nullptr);
    int t = 0;
    std::cin >> t;
    for (int i = 0; i < t; i++) {
        int a = 0;
        int b = 0;
        int c = 0;
        std::cin >> a >> b >> c;

        // Use order() to put a, b and c in increasing order,
        // then print them on one line, separated by single spaces.
    }
    return 0;
}

Next, lesson 04 lets the compiler write the types for you with auto, and finishes the range-for this lesson previewed.