C++ functions: declarations, definitions, returns

A rule written out in three places has to be fixed in three places: change how marks become grade points, and every copy must change the same way. A function gives the rule one name and one home. It takes its inputs as parameters, does one job and hands back a result, so every caller uses it with one call, grade_points(92), and a fix happens once.

You will define and call functions, declare them before use, return several results in a struct and make the compiler warn when a result is ignored. You will also see what happens when a function forgets its return: one file printed 1, printed 4, trapped and crashed in four builds. Every program was built with Apple clang 21 and GCC 16.

A call copies the argument, runs the body and returns a value

Here is a complete function and a main that calls it three times. Its first line says everything a caller needs: int is the type of the result, grade_points is the name, and (int marks) is the list of parametersparameter: A variable named in a function's parameter list, such as marks in int grade_points(int marks). Each call creates it anew and initialises it from the argument the call passes.. The body, between the braces, runs on each call:

// grade_points.cpp: one function, defined above main and called three times.
#include <print>

// Turns marks out of 100 into grade points on a 10-point scale.
int grade_points(int marks) {
    if (marks >= 90) return 10;
    if (marks >= 75) return 8;
    if (marks >= 60) return 6;
    if (marks >= 40) return 4;
    return 0;
}

int main() {
    int maths = 92;
    std::println("maths: {} marks, {} points", maths, grade_points(maths));
    std::println("physics: 67 marks, {} points", grade_points(67));
    int total = grade_points(81) + grade_points(39);
    std::println("two more subjects: {} points together", total);
}

maths: 92 marks, 10 points
physics: 67 marks, 6 points
two more subjects: 8 points together

The program printed 10, 6 and 8 points, and the GCC build printed the same three lines. A return statement ends the function at once and hands its value back; the rest of the body is skipped, which is why the five return lines can follow one another without else. Step through the first call and watch where 92 goes:

When main evaluates grade_points(maths), the argumentargument: The value a call passes to a function, such as maths in grade_points(maths). It is evaluated before the call starts and initialises the matching parameter. maths is evaluated first, and its value, 92, initialises marks, a new variable that belongs to this one call. The body runs until a return, and the call expression takes the returned value, 10, as if main had written 10 there. A call is an expression like any other, so grade_points(81) + grade_points(39) simply adds 8 and 0.

Because marks is a copy, the function cannot change maths in main. Copying is how C++ passes arguments unless you ask for something else; the parameter-passing lesson shows references, which let a function work on the caller’s variable instead. A function that only does something, such as printing, has the return type void: it may end with a bare return; or simply reach its closing brace.

The compiler must see a declaration before the call

The compiler reads a file from the top down, and it accepts a call only when it already knows the function’s name, parameter types and return type. Here main comes first and calls a function defined below it:

// call_too_early.cpp: main calls grade_points before the compiler has seen it.
#include <print>

int main() {
    std::println("{} points", grade_points(92));
}

int grade_points(int marks) {
    return marks >= 40 ? marks / 10 : 0;
}

// declare_first.cpp: a declaration at the top lets main call a function defined below.
#include <print>

int grade_points(int marks);  // declaration: name, parameter types, return type, then ;

int main() {
    std::println("{} points", grade_points(92));
}

int grade_points(int marks) {  // definition: the same first line, then the body
    if (marks >= 90) return 10;
    if (marks >= 75) return 8;
    if (marks >= 60) return 6;
    if (marks >= 40) return 4;
    return 0;
}

from session import run

run("""
clang++ -std=c++23 -Wall -Wextra call_too_early.cpp -o call_too_early
g++-16 -std=c++23 -Wall -Wextra call_too_early.cpp -o call_too_early
clang++ -std=c++23 -Wall -Wextra declare_first.cpp -o declare_first && ./declare_first
""")

$ clang++ -std=c++23 -Wall -Wextra call_too_early.cpp -o call_too_early
call_too_early.cpp:5:31: error: use of undeclared identifier 'grade_points'
    5 |     std::println("{} points", grade_points(92));
      |                               ^~~~~~~~~~~~
1 error generated.
[exit status 1]
$ g++-16 -std=c++23 -Wall -Wextra call_too_early.cpp -o call_too_early
call_too_early.cpp: In function 'int main()':
call_too_early.cpp:5:31: error: 'grade_points' was not declared in this scope
    5 |     std::println("{} points", grade_points(92));
      |                               ^~~~~~~~~~~~
[exit status 1]
$ clang++ -std=c++23 -Wall -Wextra declare_first.cpp -o declare_first && ./declare_first
10 points

Apple clang says use of undeclared identifier 'grade_points'; GCC says 'grade_points' was not declared in this scope. Both point at line 5, column 31, where the call is. There are two fixes: move the definition above main, or keep the order and add a declarationfunction declaration: A function's return type, name and parameter types ended by a semicolon, as in int grade_points(int marks);. It lets code call the function before, or without, seeing its body. at the top, as declare_first.cpp does: the first line of the function followed by a semicolon instead of a body. Step through what happens to that file, from its first line to the running program:

A declaration promises that the function exists; the definition keeps the promise. The parameter names are optional in a declaration (int grade_points(int); declares the same function), but they tell the reader what each argument means. Declarations may be repeated as often as you like, while a program holds exactly one definition of each ordinary function: the one-definition ruleone-definition rule: The rule that a program holds exactly one definition of each ordinary function it uses. An inline function may be defined in every translation unit that uses it, as long as all the definitions are identical. More in “How C++ compiles: preprocess, compile and link”.

That is how programs of several files work. A header holds the declarations, every .cpp file that calls the functions includes it, and one .cpp file holds the definitions. When a declared function has no definition anywhere, every file still compiles, and the linkerlinker: The last stage of a build: it joins the object files of a program and the libraries it uses into one executable, matching every symbol a file uses with exactly one definition. More in “How C++ compiles: preprocess, compile and link” then reports an undefined symbol. The exercise at the end of this lesson is built from three files in exactly this way.

Return a struct when a function has several results

A function returns one value. When a computation produces several values that belong together, return a small struct that holds them. Older code, and many C libraries, use output parametersoutput parameter: A reference or pointer parameter that a function writes a result into, so the caller must create the variable before the call. Returning a value, or a struct of several values, is usually clearer. instead: the caller passes variables, and the function writes into them. Both programs split 155 minutes into hours and minutes, one each way:

// split_struct.cpp: a function with two results returns them together in a struct.
#include <print>

struct Duration {
    int hours;
    int minutes;
};

Duration split_minutes(int total_minutes) {
    return {total_minutes / 60, total_minutes % 60};
}

int main() {
    Duration film = split_minutes(155);
    std::println("The film runs {} h {} min", film.hours, film.minutes);

    // a structured binding names both parts
    auto [hours, minutes] = split_minutes(1000);
    std::println("1000 minutes is {} h {} min", hours, minutes);
}

The film runs 2 h 35 min
1000 minutes is 16 h 40 min

// split_out_params.cpp: the same job with output parameters, as older code does it.
#include <print>

// The & makes hours and minutes refer to the caller's variables (see the next lesson).
void split_minutes(int total_minutes, int& hours, int& minutes) {
    hours = total_minutes / 60;
    minutes = total_minutes % 60;
}

int main() {
    int hours;    // must exist before the call, with no sensible value yet
    int minutes;
    // which arguments are inputs? The call does not say.
    split_minutes(155, hours, minutes);
    std::println("The film runs {} h {} min", hours, minutes);
}

The film runs 2 h 35 min

Both print The film runs 2 h 35 min, but their calls read differently:

Duration film = split_minutes(155); says what goes in and what comes out. split_minutes(155, hours, minutes); looks like a call with three inputs, and it forces main to create hours and minutes before the call with no sensible value in them. With the struct, auto [hours, minutes] = split_minutes(1000); names both parts in one line, a structured bindingA declaration such as auto [hours, minutes] = f(); that gives a name to each member of the struct, pair or tuple a call returns, in one line., which a later module covers with pairs and tuples. Rules F.20 and F.21 of the C++ Core Guidelines say the same thing: hand results back as return values, and group several of them in a struct. Returning a struct is cheap too, because C++ constructs the returned object right where the caller’s variable lives, as the parameter-passing lesson measures.

[[nodiscard]] turns an ignored result into a warning

Some functions exist only for their result. If a caller throws that result away, the call was pointless, or worse, a bug. Put the attribute [[nodiscard]] before the return type, and the compiler warns whenever the result of a call is ignored. Line 20 below is the classic mistake:

// nodiscard.cpp: two functions whose results must not be thrown away.
#include <cctype>
#include <print>
#include <string>

[[nodiscard]] bool is_leap_year(int year) {
    return (year % 4 == 0 && year % 100 != 0) || year % 400 == 0;
}

// The reason in the brackets becomes part of the warning (C++20).
[[nodiscard("it returns a new string and leaves its argument alone")]]
std::string upper_case(std::string text) {
    for (char& c : text) c = static_cast<char>(std::toupper(static_cast<unsigned char>(c)));
    return text;
}

int main() {
    std::string city = "Pune";
    is_leap_year(2028);           // the answer is computed and lost
    upper_case(city);             // a real bug: city is still "Pune"
    std::println("{}", city);

    city = upper_case(city);      // the fix: keep the result
    (void)is_leap_year(2028);     // a cast to void says "ignored on purpose"
    std::println("{}", city);
}

from session import run

run("""
clang++ -std=c++23 -Wall -Wextra nodiscard.cpp -o nodiscard && ./nodiscard
g++-16 -std=c++23 -Wall -Wextra nodiscard.cpp -o nodiscard && ./nodiscard
""")

$ clang++ -std=c++23 -Wall -Wextra nodiscard.cpp -o nodiscard && ./nodiscard
nodiscard.cpp:19:5: warning: ignoring return value of function declared with 'nodiscard' attribute [-Wunused-result]
   19 |     is_leap_year(2028);           // the answer is computed and lost
      |     ^~~~~~~~~~~~ ~~~~
nodiscard.cpp:20:5: warning: ignoring return value of function declared with 'nodiscard' attribute: it returns a new string and leaves its argument alone [-Wunused-result]
   20 |     upper_case(city);             // a real bug: city is still "Pune"
      |     ^~~~~~~~~~ ~~~~
2 warnings generated.
Pune
PUNE
$ g++-16 -std=c++23 -Wall -Wextra nodiscard.cpp -o nodiscard && ./nodiscard
nodiscard.cpp: In function 'int main()':
nodiscard.cpp:19:17: warning: ignoring return value of 'bool is_leap_year(int)', declared with attribute 'nodiscard' [-Wunused-result]
   19 |     is_leap_year(2028);           // the answer is computed and lost
      |     ~~~~~~~~~~~~^~~~~~
nodiscard.cpp:6:20: note: declared here
    6 | [[nodiscard]] bool is_leap_year(int year) {
      |                    ^~~~~~~~~~~~
nodiscard.cpp:20:15: warning: ignoring return value of 'std::string upper_case(std::string)', declared with attribute 'nodiscard': 'it returns a new string and leaves its argument alone' [-Wunused-result]
   20 |     upper_case(city);             // a real bug: city is still "Pune"
      |     ~~~~~~~~~~^~~~~~
nodiscard.cpp:12:13: note: declared here
   12 | std::string upper_case(std::string text) {
      |             ^~~~~~~~~~
Pune
PUNE

upper_case takes a copy of its argument, changes the copy and returns it, so upper_case(city); leaves city as it was, and the first line the program prints is Pune. Both compilers flag lines 19 and 20 with -Wunused-result, and both quote the reason written in the brackets, which C++20 allows. The fix is to use the result: city = upper_case(city);. To ignore a result on purpose, cast the call to void, as line 24 does: the cast tells the compiler and the reader that the result was thrown away deliberately.

The warning appears without -Wall, because the standard recommends that compilers warn here. The C++23 standard library marks functions such as empty() of std::string this way: name.empty(); only tests whether the string is empty, so a line that was meant to clear it gets a warning. Mark your own functions [[nodiscard]] when they return an error code, a new value or anything else whose loss is a bug, and leave it off functions such as std::printf, whose result, the number of characters printed, callers rarely need: the printing is the reason for the call.

Running off the end of a non-void function is undefined behaviour

The C++ standard says that reaching the closing brace of a function that returns a value is undefined behaviourundefined behaviour: What a program does when it breaks a rule for which the C++ standard sets no requirements, such as reading past the end of an array. The compiler may assume it never happens, so the result can change with the compiler and the optimisation level. More in “Object lifetime and undefined behaviour in C++”: the language makes no promise at all about what the program does next. Only main is exempt, and reaching the end of main means return 0;. Here is grade_points without its last line, so marks below 40 run off the end:

// missing_return.cpp: grade_points minus its last line; marks below 40 run off the end.
#include <print>

int grade_points(int marks) {
    if (marks >= 90) return 10;
    if (marks >= 75) return 8;
    if (marks >= 60) return 6;
    if (marks >= 40) return 4;
}  // flowing off the end of a function that returns int: undefined behaviour

int main() {
    std::println("grade_points(95) = {}", grade_points(95));
    std::println("grade_points(30) = {}", grade_points(30));
}

from session import run

# The same file, built four ways. Both compilers warn, and each build still produces a program.
run("""
clang++ -std=c++23 -O0 missing_return.cpp -o clang_O0
clang++ -std=c++23 -O2 missing_return.cpp -o clang_O2 2> /dev/null
g++-16 -std=c++23 -O0 missing_return.cpp -o gcc_O0
g++-16 -std=c++23 -O2 missing_return.cpp -o gcc_O2 2> /dev/null
./clang_O0
./clang_O2
./gcc_O0
./gcc_O2
g++-16 -std=c++23 -Werror=return-type missing_return.cpp -o checked
""")

$ clang++ -std=c++23 -O0 missing_return.cpp -o clang_O0
missing_return.cpp:9:1: warning: non-void function does not return a value in all control paths [-Wreturn-type]
    9 | }  // flowing off the end of a function that returns int: undefined behaviour
      | ^
1 warning generated.
$ clang++ -std=c++23 -O2 missing_return.cpp -o clang_O2 2> /dev/null
$ g++-16 -std=c++23 -O0 missing_return.cpp -o gcc_O0
missing_return.cpp: In function 'int grade_points(int)':
missing_return.cpp:9:1: warning: control reaches end of non-void function [-Wreturn-type]
    9 | }  // flowing off the end of a function that returns int: undefined behaviour
      | ^
$ g++-16 -std=c++23 -O2 missing_return.cpp -o gcc_O2 2> /dev/null
$ ./clang_O0
grade_points(95) = 10
grade_points(30) = 1
$ ./clang_O2
grade_points(95) = 10
grade_points(30) = 4
$ ./gcc_O0
[stopped by signal 5 (SIGTRAP): a shell reports exit status 133]
$ ./gcc_O2
[stopped by signal 10 (SIGBUS): a shell reports exit status 138]
$ g++-16 -std=c++23 -Werror=return-type missing_return.cpp -o checked
missing_return.cpp: In function 'int grade_points(int)':
missing_return.cpp:9:1: error: control reaches end of non-void function [-Werror=return-type]
    9 | }  // flowing off the end of a function that returns int: undefined behaviour
      | ^
cc1plus: some warnings being treated as errors
[exit status 1]

Both compilers warn even without -Wall: -Wreturn-type is on by default in C++ for Clang and GCC. The four programs were built anyway, and each did something different with grade_points(30):

The optimisers may assume that undefined behaviour never happens. Apple clang at -O2 therefore treated the path without a return as impossible, concluded that marks >= 40 cannot fail, and gave every mark below 60 four points. GCC at -O0 and -Og turns code that must never run into a trap instruction (its -funreachable-traps option). GCC at -O2 worked out that grade_points(30) always runs off the end, so it deleted everything in main after the first std::println, the end of main included, and the program ran on into the bytes that followed.

The two GCC builds printed nothing, not even the line for grade_points(95): when output goes to a file or a pipe it waits in a buffer, and a program stopped by a signal never writes that buffer out. Shells such as bash and zsh report a program stopped by signal n as exit statusexit status: The number a program hands back when it ends, the value main returns. 0 means success; a shell keeps the last status in $?, and && runs the next command only after a status of 0. More in “How C++ compiles: preprocess, compile and link” 128 + n (POSIX promises only a value above 128), so 133 and 138 here. The last command of the session shows the cure: with -Werror=return-type the warning becomes an error, and no program is built.

Small functions with one job are easier to change and test

Programs that do everything in main work until someone has to change them. This one prints an electricity bill for every meter reading on standard input, with a slab tariff invented for the lesson: the rate per unit rises after 100 and 200 units, a fixed charge rises above 300 units, and a duty of 5 % applies to both. Both versions read the same seven readings:

// bill_long.cpp: an electricity bill for every meter reading on standard input, all
// inside main. The tariff is invented for this lesson: 3.00 a unit up to 100 units,
// 4.50 a unit from 101 to 200, 6.00 a unit above 200; a fixed charge of 40.00 (75.00
// above 300 units); a 5 % duty on both.
#include <iostream>
#include <print>
#include <string>

int main() {
    std::println("{:<8}{:>7}{:>10}{:>8}{:>8}{:>10}", "Meter", "Units", "Energy", "Fixed", "Duty", "Total");
    std::string meter;
    int units = 0;
    int bills = 0;
    int rejected = 0;
    double billed = 0.0;
    double highest = 0.0;
    std::string highest_meter;
    while (std::cin >> meter >> units) {
        if (units < 0) {
            std::println("{:<8}{:>7}  rejected: a reading cannot be negative", meter, units);
            ++rejected;
            continue;
        }
        if (units > 100000) {
            std::println("{:<8}{:>7}  rejected: check the meter", meter, units);
            ++rejected;
            continue;
        }
        double energy = 0.0;
        int rest = units;
        if (rest > 200) {
            energy += (rest - 200) * 6.00;
            rest = 200;
        }
        if (rest > 100) {
            energy += (rest - 100) * 4.50;
            rest = 100;
        }
        energy += rest * 3.00;
        double fixed = 40.00;
        if (units > 300) {
            fixed = 75.00;
        }
        double duty = (energy + fixed) * 0.05;
        double total = energy + fixed + duty;
        std::println("{:<8}{:>7}{:>10.2f}{:>8.2f}{:>8.2f}{:>10.2f}", meter, units, energy, fixed, duty, total);
        ++bills;
        billed += total;
        if (total > highest) {
            highest = total;
            highest_meter = meter;
        }
    }
    std::println("{} bills, {} rejected, {:.2f} billed in all", bills, rejected, billed);
    if (bills > 0) {
        std::println("highest bill: {} ({:.2f})", highest_meter, highest);
    }
}

A-101 87
A-102 100
B-201 101
B-202 245
C-301 -12
C-302 412
D-401 250000

Meter     Units    Energy   Fixed    Duty     Total
A-101        87    261.00   40.00   15.05    316.05
A-102       100    300.00   40.00   17.00    357.00
B-201       101    304.50   40.00   17.23    361.73
B-202       245   1020.00   40.00   53.00   1113.00
C-301       -12  rejected: a reading cannot be negative
C-302       412   2022.00   75.00  104.85   2201.85
D-401    250000  rejected: check the meter
5 bills, 2 rejected, 4349.62 billed in all
highest bill: C-302 (2201.85)

// bill.cpp: the same program with five functions, each doing one job, and a short main.
#include <iostream>
#include <print>
#include <string>
#include <string_view>

struct Bill {
    double energy;
    double fixed;
    double duty;
    double total;
};

// The invented tariff of this lesson, one slab at a time.
double energy_charge(int units) {
    double charge = 0.0;
    if (units > 200) {
        charge += (units - 200) * 6.00;
        units = 200;
    }
    if (units > 100) {
        charge += (units - 100) * 4.50;
        units = 100;
    }
    return charge + units * 3.00;
}

double fixed_charge(int units) {
    return units > 300 ? 75.00 : 40.00;
}

Bill make_bill(int units) {
    double energy = energy_charge(units);
    double fixed = fixed_charge(units);
    double duty = (energy + fixed) * 0.05;
    return {energy, fixed, duty, energy + fixed + duty};
}

// Why a reading cannot be billed, or an empty string when it can.
std::string rejection_reason(int units) {
    if (units < 0) return "a reading cannot be negative";
    if (units > 100000) return "check the meter";
    return "";
}

void print_bill(std::string_view meter, int units, Bill bill) {
    std::println("{:<8}{:>7}{:>10.2f}{:>8.2f}{:>8.2f}{:>10.2f}", meter, units, bill.energy, bill.fixed, bill.duty, bill.total);
}

int main() {
    std::println("{:<8}{:>7}{:>10}{:>8}{:>8}{:>10}", "Meter", "Units", "Energy", "Fixed", "Duty", "Total");
    std::string meter, highest_meter;
    int units = 0, bills = 0, rejected = 0;
    double billed = 0.0, highest = 0.0;
    while (std::cin >> meter >> units) {
        std::string why = rejection_reason(units);
        if (!why.empty()) {
            std::println("{:<8}{:>7}  rejected: {}", meter, units, why);
            ++rejected;
            continue;
        }
        Bill bill = make_bill(units);
        print_bill(meter, units, bill);
        ++bills;
        billed += bill.total;
        if (bill.total > highest) {
            highest = bill.total;
            highest_meter = meter;
        }
    }
    std::println("{} bills, {} rejected, {:.2f} billed in all", bills, rejected, billed);
    if (bills > 0) std::println("highest bill: {} ({:.2f})", highest_meter, highest);
}

A-101 87
A-102 100
B-201 101
B-202 245
C-301 -12
C-302 412
D-401 250000

Meter     Units    Energy   Fixed    Duty     Total
A-101        87    261.00   40.00   15.05    316.05
A-102       100    300.00   40.00   17.00    357.00
B-201       101    304.50   40.00   17.23    361.73
B-202       245   1020.00   40.00   53.00   1113.00
C-301       -12  rejected: a reading cannot be negative
C-302       412   2022.00   75.00  104.85   2201.85
D-401    250000  rejected: check the meter
5 bills, 2 rejected, 4349.62 billed in all
highest bill: C-302 (2201.85)

A-101 87
A-102 100
B-201 101
B-202 245
C-301 -12
C-302 412
D-401 250000

The two versions printed the same ten lines, and so did their GCC builds. The split version is a few lines longer, and that is fine, because every piece now has a name. To find the pieces, look for the comments and blank lines in a long function: each commented block is a function waiting to be named after its comment. Step through one reading, B-201 with 101 units, on its way through the functions:

energy_charge holds the slab tariff and nothing else, so a change of rates touches one place. make_bill returns a Bill struct with all four amounts, so it can be checked without typing any input: a test can call it with 0, 100, 101, 200, 201 and 301 units, the edges of every slab. And main now reads like a summary of the program.

A few habits make functions easy to read and test: one job per function, a name that says what it returns or does (fixed_charge, print_bill), few parameters, and results returned rather than printed, so that the caller decides what to do with them.

Practise: three functions about primes

The exercise has three files: a header with the declarations, a source file where you write the definitions, and the public tests.

// primes.h: the three functions of the exercise. Keep these declarations as they are.
#pragma once

// True when n is prime: greater than 1, with no divisor other than 1 and itself.
[[nodiscard]] bool is_prime(int n);

// The smallest prime number greater than n (next_prime(13) is 17).
[[nodiscard]] int next_prime(int n);

// How many prime numbers are less than or equal to limit (count_primes_up_to(10) is 4).
[[nodiscard]] int count_primes_up_to(int limit);

// primes.cpp: your definitions. Each compiles, and gives wrong answers until you write it.
#include "primes.h"

bool is_prime(int n) {
    (void)n;  // remove this line when you use n
    return false;
}

int next_prime(int n) {
    return n + 1;
}

int count_primes_up_to(int limit) {
    (void)limit;
    return 0;
}

// primes_test.cpp: the public tests. Build them together with your primes.cpp.
#include <cstdlib>
#include <print>
#include <string_view>

#include "primes.h"

int checks = 0;
int failures = 0;

void check(bool passed, std::string_view what) {
    ++checks;
    if (!passed) {
        ++failures;
        std::println("FAIL: {}", what);
    }
}

int main() {
    check(!is_prime(-7), "-7 is not prime");
    check(!is_prime(0), "0 is not prime");
    check(!is_prime(1), "1 is not prime");
    check(is_prime(2), "2 is prime");
    check(is_prime(3), "3 is prime");
    check(!is_prime(91), "91 is not prime (7 x 13)");
    check(is_prime(97), "97 is prime");
    check(!is_prime(1'000'000), "1000000 is not prime");
    check(is_prime(2'147'483'647), "2147483647 is prime");
    check(next_prime(-5) == 2, "next_prime(-5) is 2");
    check(next_prime(2) == 3, "next_prime(2) is 3");
    check(next_prime(13) == 17, "next_prime(13) is 17");
    check(next_prime(89) == 97, "next_prime(89) is 97");
    check(count_primes_up_to(1) == 0, "no primes up to 1");
    check(count_primes_up_to(10) == 4, "4 primes up to 10");
    check(count_primes_up_to(100) == 25, "25 primes up to 100");
    check(count_primes_up_to(100'000) == 9'592, "9592 primes up to 100000");
    if (failures == 0) {
        std::println("All {} checks passed", checks);
        return EXIT_SUCCESS;
    }
    std::println("{} of {} checks failed", failures, checks);
    return EXIT_FAILURE;
}

1. Save the three files in one folder and build the tests with the starter file. They fail, as the session below shows: 10 of the 17 checks fail before you have written anything.
2. Write is_prime, then next_prime and count_primes_up_to, both of which can call is_prime. Rebuild with clang++ -std=c++23 -Wall -Wextra primes.cpp primes_test.cpp -o primes_test (or g++-16) until it prints All 17 checks passed.
3. Build once more with -fsanitize=undefined added and run the tests again: no runtime error line may appear.

from session import run

# The tests built with the starter file: every function still gives a wrong answer.
run("""
cd exercise && clang++ -std=c++23 -Wall -Wextra primes.cpp primes_test.cpp -o primes_test && ./primes_test
""")

$ cd exercise && clang++ -std=c++23 -Wall -Wextra primes.cpp primes_test.cpp -o primes_test && ./primes_test
FAIL: 2 is prime
FAIL: 3 is prime
FAIL: 97 is prime
FAIL: 2147483647 is prime
FAIL: next_prime(-5) is 2
FAIL: next_prime(13) is 17
FAIL: next_prime(89) is 97
FAIL: 4 primes up to 10
FAIL: 25 primes up to 100
FAIL: 9592 primes up to 100000
10 of 17 checks failed
[exit status 1]

A first hint: use trial divisiontrial division: Testing whether a number n is prime by dividing it by 2, 3, 4 and so on. A divisor larger than the square root of n pairs with one below it, so the test can stop once d * d is greater than n. More in “C++ practice set: loops, conditions and numbers”, testing divisors d from 2 while d <= n / d. The obvious condition d * d <= n overflows int on the check for 2,147,483,647, the largest int on these compilers, because 46,341 × 46,341 is larger than that, and signed overflow is undefined behaviour too. The sanitizer build of step 3 catches it.

Once is_prime and its two partners pass, try the questions below on calls, declarations, returned structs, warnings and small functions. They adapt to your answers, opening with whichever of the six ideas has tripped you up most, and a wrong choice names the slip behind it:

Interview questions

Fresher · What does [[nodiscard]] do, and how do you ignore such a result on purpose?

[[nodiscard]] on a function, or on a type, asks the compiler to warn whenever the result of a call is thrown away, as in upper_case(city);, which computes a new string and loses it. Apple clang and GCC both warn with -Wunused-result, even without -Wall, and since C++20 a reason in brackets, [[nodiscard("...")]], becomes part of the warning. The attribute changes no generated code; it only adds the warning, which -Werror turns into an error. Use it for functions whose result is the whole point: error codes, new values, tests such as empty(). To discard a result deliberately, cast the call to void: (void)is_leap_year(2028);.

A good answer usually earns a follow-up about types and headers. Try these two before you look at the reasons behind each choice:

Key takeaways

• A function has a return type, a name, a parameter list and a body; a call copies each argument into its parameter, runs the body until a return, and takes the returned value.
• The compiler must see a declaration before a call. Declare as often as you need, and define each ordinary function exactly once.
• Return results instead of writing into output parameters, and return a struct when there are several.
• [[nodiscard]] makes both compilers warn when a result is ignored; cast the call to void to ignore it on purpose.
• Reaching the end of a non-void function other than main is undefined behaviour: one file printed 1, printed 4, trapped and crashed, so build with -Werror=return-type.
• Short functions with one job and a clear name make a program easier to change, and their results can be tested without running the whole program.