FunctionParameters

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:

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.

FunctionParameters

 

Rainer D 6 P2 500x500Modernes C++ Mentoring

Be part of my mentoring programs:

  • "Fundamentals for C++ Professionals" (open)
  • "Design Patterns and Architectural Patterns with C++" (open)
  • "C++20: Get the Details" (open)
  • "Concurrency with Modern C++" (starts March 2024)
  • Do you want to stay informed: Subscribe.

     

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

    FunctionParametersAdvanced

     

    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.

     

     

     

    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, Kris Kafka, 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, Dmitry Farberov, 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, moon, Philipp Lenk, Hobsbawm, and Charles-Jianye Chen.

    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

    Seminars

    I’m happy to give online seminars or face-to-face seminars worldwide. Please call me if you have any questions.

    Standard Seminars (English/German)

    Here is a compilation of my standard seminars. These seminars are only meant to give you a first orientation.

    • C++ – The Core Language
    • C++ – The Standard Library
    • C++ – Compact
    • C++11 and C++14
    • Concurrency with Modern C++
    • Design Pattern and Architectural Pattern with C++
    • Embedded Programming with Modern C++
    • Generic Programming (Templates) with C++
    • Clean Code with Modern C++
    • C++20

    Online Seminars (German)

    Contact Me

    Modernes C++ Mentoring,

     

     

    0 replies

    Leave a Reply

    Want to join the discussion?
    Feel free to contribute!

    Leave a Reply

    Your email address will not be published. Required fields are marked *