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&&
andstd::move
the parameter - F.19: For “forward” parameters, pass by
TP&&
and onlystd::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*
overT&
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.
Modernes C++ Mentoring
Do you want to stay informed: Subscribe.
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.
- You need a template parameter: typename Args
- Take your function argument per forwarding reference: Args&& args
- 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.
Thanks a lot to my Patreon Supporters: Matt Braun, Roman Postanciuc, Tobias Zindl, G Prvulovic, Reinhold Dröge, Abernitzke, Frank Grimm, Sakib, Broeserl, António Pina, Sergey Agafyin, Андрей Бурмистров, Jake, GS, Lawton Shoemake, Jozo Leko, John Breland, Venkat Nandam, Jose Francisco, Douglas Tinkham, Kuchlong Kuchlong, Robert Blanch, Truels Wissneth, Mario Luoni, Friedrich Huber, lennonli, Pramod Tikare Muralidhara, Peter Ware, Daniel Hufschläger, Alessandro Pezzato, Bob Perry, Satish Vangipuram, Andi Ireland, Richard Ohnemus, Michael Dunsky, Leo Goodstadt, John Wiederhirn, Yacob Cohen-Arazi, Florian Tischler, Robin Furness, Michael Young, Holger Detering, Bernd Mühlhaus, Stephen Kelley, Kyle Dean, Tusar Palauri, Juan Dent, George Liao, Daniel Ceperley, Jon T Hess, Stephen Totten, Wolfgang Fütterer, Matthias Grün, Phillip Diekmann, Ben Atakora, Ann Shatoff, Rob North, Bhavith C Achar, Marco Parri Empoli, Philipp Lenk, Charles-Jianye Chen, Keith Jeffery,and Matt Godbolt.
Thanks, in particular, to Jon Hess, Lakshman, Christian Wittenhorst, Sherhy Pyton, Dendi Suhubdy, Sudhakar Belagurusamy, Richard Sargeant, Rusty Fleming, John Nebel, Mipko, Alicja Kaminska, Slavko Radman, and David Poole.
My special thanks to Embarcadero | |
My special thanks to PVS-Studio | |
My special thanks to Tipi.build | |
My special thanks to Take Up Code | |
My special thanks to SHAVEDYAKS |
Modernes C++ GmbH
Modernes C++ Mentoring (English)
Rainer Grimm
Yalovastraße 20
72108 Rottenburg
Mail: schulung@ModernesCpp.de
Mentoring: www.ModernesCpp.org
Modernes C++ Mentoring,
Leave a Reply
Want to join the discussion?Feel free to contribute!