C++ Core Guidelines: The Rules for in, out, in-out, consume, and forward Function Parameter

You have many choices to pass function parameters. You can pass by value or by reference. A reference can be const or non-const. You can even move or forward your parameters.  Your decision should depend on if it is an in, and out, an in-out, a consume, or a forward function parameter. Curious? Read the post!

According to the guidelines, let's discuss in, out, in-out, consume, or forward parameters.

Parameter passing expression rules:

• F.15: Prefer simple and conventional ways of passing information
• F.16: For “in” parameters, pass cheaply-copied types by value and others by reference to const
• F.17: For “in-out” parameters, pass by reference to non-const
• F.18: For “consume” parameters, pass by X&& and std::move the parameter
• F.19: For “forward” parameters, pass by TP&& and only std::forward the parameter
• F.20: For “out” output values, prefer return values to output parameters
• F.21: To return multiple “out” values, prefer returning a tuple or struct
• F.60: Prefer T* over T& when “no argument” is a valid option

It seems to be a lot of stuff, but bear with me. The first rule F.15 summarises the guidelines F.16 - F.21

F.15: Prefer simple and conventional ways of passing information

Here is the big picture from the C++ core guidelines. These are the standard parameter passing rules.

Based on these rules there are a few additions in green, the so-called advanced parameter passing rules.

The rationale for the rules and their variations will follow in the next rules.

F.16: For “in” parameters, pass cheaply-copied types by value and others by reference to const

This rule for in parameters is straightforward, and so is the example:

void f1(const string& s);  // OK: pass by reference to const; always cheap

void f2(string s);         // bad: potentially expensive

void f3(int x);            // OK: Unbeatable

void f4(const int& x);     // bad: overhead on access in f4()

I often hear the question in my seminars: What is cheaply copyable? The guidelines are pretty concrete.

• You should not  copy the parameter p if sizeof(p) > 4 * sizeof(int)
• You should not use a const reference to p if sizeof(p) < 3 * sizeof(int)

 I assume these numbers are based on experience.

F.17: For “in-out” parameters, pass by reference to non-const

In-out parameters will be modified in the function, so using a non-const reference makes sense.

void appendElements(std::vector<int>& vec){
  // append elements to vec
  ...
}

F.18: For “consume” parameters, pass by X&& and std::move the parameter

This is the first advanced rule to consume parameters. Use an rvalue reference if you consume the parameter and move it inside the function body. Here is an example:

void sink(vector<int>&& v) {   // sink takes ownership of whatever the argument owned
    // usually there might be const accesses of v here
    store_somewhere(std::move(v));
    // usually no more use of v here; it is moved-from
}

There is an exception to this rule. std::unique_ptr is a move-only type that is cheap to move. Therefore, you can move it.

void sink(std::unique_ptr<int> p) { 
  ...
}
...
sink(std::move(uniqPtr));

F.19: For “forward” parameters, pass by TP&& and only std::forward the parameter

This is the idiom that factory methods such as std::make_unique or std::make_shared use. Both functions take a type T and arbitrary numbers of arguments args and forward them unchanged to the constructor of T. Have a look here:

template<typename T, typename... Args>                              // 1
std::unique_ptr<T> make_unique(Args&&... args)                      // 2
{
    return std::unique_ptr<T>(new T(std::forward<Args>(args)...));  // 3
}

This pattern is called perfect forwarding: If a function templates forward its arguments without changing its lvalue or rvalue characteristics, we call it perfect forwarding. 

Here is my previous post to perfect forwarding.

To get perfect forwarding for a function template, you have to follow the three-step recipe. I skip this part because it must not be a variadic template (...) such as for std::make_unique.

1. You need a template parameter: typename Args
2. Take your function argument per forwarding reference: Args&& args
3. Forward the function arguments: std::forward<Args>(args)

F.20: For “out” output values, prefer return values to output parameters

An explicit return value documents the intention of a function. Using a parameter with a reference as out output value may be misleading. This can also be an in-out value. Returning the result of a function by value also holds for the standard container that uses move semantics implicitly.

// OK: return pointers to elements with the value x
vector<const int*> find_all(const vector<int>&, int x);

// Bad: place pointers to elements with value x in-out
void find_all(const vector<int>&, vector<const int*>& out, int x);

There is an exception to this rule. If you have an expensive-to-move object, you can use a reference as out parameter.

struct Package {      // exceptional case: expensive-to-move object
    char header[16];
    char load[2024 - 16];
};

Package fill();       // Bad: large return value
void fill(Package&);  // OK

F.21: To return multiple “out” values prefer returning a tuple or struct

Sometimes your function returns more than one out value. In this case, you should use a std::tuple or a struct, but you should not use the parameter with a reference. This is very error-prone.

// BAD: output-only parameter documented in a comment
int f(const string& input, /*output only*/ string& output_data)
{
    // ...
    output_data = something();
    return status;
}

// GOOD: self-documenting
tuple<int, string> f(const string& input)
{
    // ...
    return make_tuple(status, something());
}

With C++17 and structured binding returning more than one value becomes quite convenient.

auto [value, success] = getValue(key);

if (success){
  // do something with the value;

The function getValue returns a pair. success indicates if the query for the key was successful.

The next rule is special. For me, this rule is more of a semantic rule. But anyway.

F.60: Prefer T* over T& when “no argument” is a valid option

If your parameter can never get a "no argument" such as a nullptr, you should use a T&. T& cannot be a nullptr. If nullptr is possible, use T*.

std::string upperString(std::string* str){
  if (str == nullptr) return std::string{};  // check for nullptr
  else{
    ...
}

If no argument is an option, you have to check for it.

What's next

This post was about in, out, in-out, consume, and forward parameters, but there are more questions to answer. How should you deal with sequences or with ownership? I will write about it in the next post.