Search

7.3 — Passing arguments by reference

While pass by value is suitable in many cases, it has a couple of limitations. First, when passing a large struct or class to a function, pass by value will make a copy of the argument into the function parameter. In many cases, this is a needless performance hit, as the original argument would have sufficed. Second, when passing arguments by value, the only way to return a value back to the caller is via the function’s return value. While this is often suitable, there are cases where it would be more clear and efficient to have the function modify the argument passed in. Pass by reference solves both of these issues.

Pass by reference

To pass a variable by reference, we simply declare the function parameters as references rather than as normal variables:

When the function is called, ref will become a reference to the argument. Since a reference to a variable is treated exactly the same as the variable itself, any changes made to the reference are passed through to the argument!

The following example shows this in action:

This program is the same as the one we used for the pass by value example, except foo’s parameter is now a reference instead of a normal variable. When we call addOne(value), ref becomes a reference to main’s value variable. This snippet produces the output:

value = 5
value = 6

As you can see, the function changed the value of the argument from 5 to 6!

Returning multiple values via out parameters

Sometimes we need a function to return multiple values. However, functions can only have one return value. One way to return multiple values is using reference parameters:

This function takes one parameter (by value) as input, and “returns” two parameters (by reference) as output. Parameters that are only used for returning values back to the caller are called out parameters. We’ve named these out parameters with the suffix “out” to denote that they’re out parameters. This helps remind the caller that the initial value passed to these parameters doesn’t matter, and that we should expect them to be rewritten.

Let’s explore how this works in more detail. First, the main function creates local variables sin and cos. Those are passed into function getSinCos() by reference (rather than by value). This means function getSinCos() has access to the actual sin and cos variables, not just copies. getSinCos() accordingly assigns new values to sin and cos (through references sinOut and cosOut respectively), which overwrites the old values in sin and cos. Main then prints these updated values.

If sin and cos had been passed by value instead of reference, getSinCos() would have changed copies of sin and cos, leading to any changes being discarded at the end of the function. But because sin and cos were passed by reference, any changes made to sin or cos (through the references) are persisted beyond the function. We can therefore use this mechanism to return values back to the caller.

This method, while functional, has a few minor downsides. First, the caller must pass in arguments to hold the updated outputs even if it doesn’t intend to use them. More importantly, the syntax is a bit unnatural, with both the input and output parameters being put together in the function call. It’s not obvious from the caller’s end that sin and cos are out parameters and will be changed. This is probably the most dangerous part of this method (as it can lead to mistakes being made). Some programmers and companies feel this is a big enough problem to advise not passing by reference this way, and using pass by address instead when mixing in and out parameters (which has a clearer syntax indicating whether a parameter is modifiable or not).

Personally, we recommend avoiding mixing input and output parameters for this reason, but if you do so, good documentation on the caller’s side can help.

Limitations of pass by reference

Non-const references can only reference non-const l-values (e.g. non-const variables), so a reference parameter cannot accept an argument that is a const l-value or an r-value (e.g. literals and the results of expressions).

Pass by const reference

As mentioned in the introduction, one of the major disadvantages of pass by value is that all arguments passed by value are copied into the function parameters. When the arguments are large structs or classes, this can take a lot of time. References provide a way to avoid this penalty. When an argument is passed by reference, a reference is created to the actual argument (which takes minimal time) and no copying of values takes place. This allows us to pass large structs and classes with a minimum performance penalty.

However, this also opens us up to potential trouble. References allow the function to change the value of the argument, which is undesirable when we want an argument be read-only. If we know that a function should not change the value of an argument, but don’t want to pass by value, the best solution is to pass by const reference.

You already know that a const reference is a reference that does not allow the variable being referenced to be changed through the reference. Consequently, if we use a const reference as a parameter, we guarantee to the caller that the function will not change the argument!

The following function will produce a compiler error:

Using const is useful for several reasons:

  • It enlists the compilers help in ensuring values that shouldn’t be changed aren’t changed (the compiler will throw an error if you try, like in the above example).
  • It tells the programmer that the function won’t change the value of the argument. This can help with debugging.
  • You can’t pass a const argument to a non-const reference parameter. Using const parameters ensures you can pass both non-const and const arguments to the function.
  • Const references can accept any type of argument, including l-values, const l-values, and r-values.

Rule: When passing an argument by reference, always use a const reference unless you need to change the value of the argument

References to pointers

It’s possible to pass a pointer by reference, and have the function change the address of the pointer entirely:

As a reminder, you can pass a C-style array by address by reference. This is useful if you need the ability for the function to change the array (e.g. for a sort function) or you need access to the array’s type information of a fixed array (to do sizeof() or a for-each loop). However, note that in order for this to work, you explicitly need to define the array size in the parameter:

This means this only works with fixed arrays of one particular length. If you want this to work with fixed arrays of any length, you can make the array length a template parameter (see chapter 13).

Pros and cons of pass by reference

Advantages of passing by reference:

  • References allow a function to change the value of the argument, which is sometimes useful. Otherwise, const references can be used to guarantee the function won’t change the argument.
  • Because a copy of the argument is not made, pass by reference is fast, even when used with large structs or classes.
  • References can be used to return multiple values from a function (via out parameters).
  • References must be initialized, so there’s no worry about null values.

Disadvantages of passing by reference:

  • Because a non-const reference cannot be initialized with a const l-value or an r-value (e.g. a literal or an expression), arguments to non-const reference parameters must be normal variables.
  • It can be hard to tell whether an argument passed by non-const reference is meant to be input, output, or both. Judicious use of const and a naming suffix for out variables can help.
  • It’s impossible to tell from the function call whether the argument may change. An argument passed by value and passed by reference looks the same. We can only tell whether an argument is passed by value or reference by looking at the function declaration. This can lead to situations where the programmer does not realize a function will change the value of the argument.

When to use pass by reference:

  • When passing structs or classes (use const if read-only).
  • When you need the function to modify an argument.
  • When you need access to the type information of a fixed array.

When not to use pass by reference:

  • When passing fundamental types that don’t need to be modified (use pass by value).
7.4 -- Passing arguments by address
Index
7.2 -- Passing arguments by value

94 comments to 7.3 — Passing arguments by reference

  • Clapfish

    Hi Alex! I hope you're well.

    Some amendment suggestions:

    1) In the "Pass by reference" section, the second cope snippet is inconsistent with the first and third. It contains the variable 'value' and reference '&value', and the text immediately afterwards talks about 'x' and '&y' thus: "When we call foo(x), y becomes a reference to x." Also, 'cout' usage instead of 'std::cout'.
    ---

    2) Just above the "Limitations of pass by reference" section, in the large paragraph, the following sentence might be inconsistent:

    "Second, the caller must pass in variables to hold the updated values, which means it must have (or create) parameters to hold these output values even if it doesn’t intend to use them."

    Shouldn't it say something like:

    "Second, the caller must pass in arguments designed to hold the output values, which means it must have (or create) variables to hold the updated values even if it doesn't intend to use them."

    (Hopefully I'm not getting my terminology mixed up here - please correct me if I am!)
    ---

    3) Just above the "References to pointers" section:

    "Rule: When passing an argument by reference, always use a const references unless you need to change the value of the argument"

    Should be: '...always use a const reference...' (-s)
    ---

    4) Under "Disadvantages of passing by reference:"

    "Because a non-const reference cannot be initialized with an const l-value or an r-value (e.g. a literal or an expression), arguments to reference parameters must be normal variables."

    '...a const l-value...' (not an)
    '...arguments to non-const reference parameters...' (specifically)
    ---

    "It can be hard to tell whether a parameter passed by non-const reference is meant to be input, output, or both. Judicious use of const and a naming suffix for out variables can help."

    '...a non-const reference parameter is meant for...' (suggestion, since [as I understand it] arguments are passed, not parameters)

  • DecSco

    "As a reminder, you can pass a C-style array by pointer by reference." Is the "by pointer" erroneously placed there?

  • Peter Baum

    1. In the section “Returning multiple values via out parameters” the use of “sin” and “cos” as simple variables is problematic.
       a. They have the same name as the common trigonometry functions, especially if a using statement is used.
       b. Initialization such as

    looks very much like a function call.

    One does see this kind of thing when reading code, so I think it is great to point out this potential for confusion.  However, as a code example, maybe using other names would be a better choice.

    2. In the section “Pros and cons of pass by reference”, I didn’t understand the statement:

    • References must be initialized, so there’s no worry about null values.

    The following example demonstrates that the statement is false.  The reference is assigned a value but not initialized within the function.  Also the argument is not initialized before the call.

    Perhaps the intent was to say something about functions using a reference parameter to give the argument a value, and in such a case, the argument does not have to be initialized.

    3. The sentence
    “Because a non-const reference cannot be made to an const l-value or an r-value (e.g. a literal or an expression), reference arguments must be normal variables.”

    is confusing because the word reference can be a noun or transitive verb.  Look in particular at the first use of the word.  I think what is meant is that the argument of a function cannot be a const l-value or an r-value if the corresponding parameter of the function is a non-const reference.

    • nascardriver

      Hi Peter!

      1. I pointed this out too, but I can't find my comment. Alex' response was something along the lines
      "These variables have fitting names, because they store sin and cos, you can still access the functions by using ::sin and ::cos".
      Generally, @std::sin and @std::cos should be used. 'using namespace' should be avoided and uniform initialization should be used, because direct initialization can be mixed up with function calls.

      2. @x is initialized to @xx, not the value of @xx! There are no uninitialized references (Unless you're using a reference wrapper).

      • Peter Baum

        Hi nascardriver,
        Regarding item 2.  You could certainly view &x as an initialization or the assignment as an initialization, but that doesn't seem to fit within any of the examples given of initialization and there is no definition of initialization given in the lessons that would suggest this interpretation.  In any event, I think, as a minimum, it shows a place where students might get confused and so a little more work is needed.

        • Alex

          Regarding item 2, The initialization of reference x happens when the function call is made, and reference parameter x is initialized with argument xx. xx isn't a null value, it's an undefined value. When I said, "null value", I generally meant 0/NULL/nullptr.

          Regarding item 3, I've reworded the sentence as: "Because a non-const reference cannot be initialized with an const l-value or an r-value (e.g. a literal or an expression), arguments to reference parameters must be normal variables."

          Hopefully that is more clear. Thanks for pointing out the confusing wording.

          • Peter Baum

            Hi Alex,

            Item 3 looks good.

            Now I'm even more confused about 2.  I think some definitions would help.  How can reference parameter x be initialized with argument xx if xx is an undefined value?  The only thing the run-time system could do is initialize it to some "null value." But why would it bother to do that?

            • nascardriver

              @x isn't initialized to the value of @xx, it's initialized to the address of @xx. Imagine references like pointers with a different syntax, because that's pretty much what they are.

              • Peter Baum

                I follow what you are saying, but don't forget, Alex said "it's an undefined value", so at that point he couldn't be talking about the address of @xx because that address is known.  Maybe he meant something else by "it."  I think at this point the problem is really English rather than computer language.

                Thanks for wading in though... it helps.

                • nascardriver

                  "it" is the value of @xx. The value of @xx is undefined.

                • Peter Baum

                  At this point we have to go back to the original statement:

                  "References must be initialized, so there’s no worry about null values."

                  Now I agree with Alex (and nascardriver) that, to use "initialization" broadly, we can say, as Alex wrote:

                  "The initialization of reference x happens when the function call is made, and reference parameter x is initialized with argument xx."

                  provided, as nascardriver suggests, we are talking about addresses rather than values.  If the addresses are the same, the values will also be the same.

                  But, in the first sentence above, the words "must be" were used.  To me that is different from something that happens automatically.  I interpret it to be summarizing what the programmer needs to do.

                  At this point, I think Alex should just rewrite it to says whatever he intends.  Since, although I agree with what nascardriver is saying, I don't know what Alex meant to say.

                • Alex

                  We hit the max thread depth, so replying here to your last comment.

                  I say "must be" because the programmer must provide an initializer for the reference. That does not happen automatically.

                  In the case where a reference is declared as a local variable, the initializer must be supplied as part of definition:

                  In the case of a function reference parameter, the parameter's initializer is the argument that is passed in when the function is called (which the programmer provides).

                  I'm still not totally clear on where the disconnect between what I'm saying and what you're understanding is, but I'd love to clarify further.

                • Peter Baum

                  That helps a lot Alex.  When the  phrase "initialization" is used, the only other thing that might make things more understandable is to make sure it is clear when the initialization occurs - at compile time or at run-time.

                • Alex

                  References can be initialized at either compiler or run-time, depending on what they are referencing.

                  But obviously a reference parameter can't be initialized until run-time.

                  These follow the same logic as initialization of normal variables, so I'm not sure a specific callout is warranted.

  • waz

    hi Alex - great tutorial!!
    I am trying to pass a pointer by reference ... I change the value of the pointer within the function and then from the caller can see the new value. However when dereferencing the pointer from the caller I get junk ... not sure where I am going wrong - please help..

    using namespace std;
    void printVal(int *&ptr1) {    
        int y = 15;
        ptr1 = &y;
        cout << "In function: " << ptr1 << endl;
        cout << "In function: " << *ptr1 << endl;
    }

    int main()  {
        int x = 5;
        int *ptr = &x;
        
        cout << ptr << endl;
        cout << *ptr << endl;
        printVal(ptr);
        cout << "After function: " << ptr << endl;
        cout << *ptr << endl;
        
        exit(1);
    }
    // output as follows:-
    0x7fff5fbff648
    5
    In function: 0x7fff5fbff5e4
    In function: 15
    After function: 0x7fff5fbff5e4
    32767     // this should be 15 ???

    • nascardriver

      Hi waz!

      You have a dangling pointer. Declare @y static or outside of @printVal.

  • Cosmin

    Why it is not a good idea to pass by reference a built-in array? Also, by built-in array you mean something like:

    Am I correct?

    • nascardriver

      Hi Cosmin!

      The only reason I can think of is that you have to explicitly state the size of the array in the function declaration. This causes your function to only be able to accept arrays of one specific size. When passing an array by address you can have another parameters to pass the size to allow your function to handle all sizes of arrays.

    • Alex

      It's fine to pass a built-in array by address by reference if you want the function to be able to modify the array or use sizeof(). I'll make this clearer.

  • The Inquisitive Dude

    Sir, in the following code:

    When I put '&' before withdrawMoney and depositMoney arguments in the methods withdraw and deposit respectively, it throws an error, but it works for money in balance. Why?

    • nascardriver

      Yo Dude!

      The error is caused by you passing r-values to those functions, you cannot have a standard reference to an r-value. If you modified your @main function like so

      it'd work.

      This isn't nice though, that's why you shouldn't pass a simple reference to those functions but a const reference instead.

      Also, don't use 'using namespace x;'

  • Paul

    I am a little confused. sin and cos in  getSinCos are C++ built-in functions, right?   But sin and cos in main function are variables?

    • nascardriver

      Hi Paul!

      You're correct. The variable names are badly chosen, after declaring them you won't be able to use the sin and cos functions in main.

      • Alex

        I'm not sure I'd say the variable names are badly chosen -- they reflect exactly what those things are meant to be. You can still use the C-style sin and cos functions in main by prefixing them with the :: scope resolution operator, to indicate that you want to use the global function, not the local variable.

        That said, we really should be using the standard library version of these functions since this is C++. I've updated the example accordingly.

  • Rasikko

    I've read that you should only pass a struct/class to a function by reference. Does this apply to their member variables/functions as well?

    • nascardriver

      Hi Rasikko!

      To answer your question you'll need a little bit of background knowledge.
      Your computer is good at handling data types with a size of 2^n bits. That is 1, 2, 4, 8, 16, 32, 64 and so on. It stops being good at types larger than 32 bits on x86 or 64 bits on x64 systems.
      Structs and classes are usually larger that 32 or 64 bits or they have an odd size, thus making your program run slower than it could be. On top of that you'll create a copy of the object every time you pass it to a function without passing it by reference (copying memory is slow).
      By passing a reference you're not creating a copy, instead you're only passing the address of the object you want to pass. That address is exactly 32 or 64 bits in size, making it great for your computer to work with.

      If your member variable has an odd size you should pass it by reference.
      All the standard numeric types (char, int, long, float, double, ...) can be passed by value, because they have 2^n sizes. Anything other than those should be passed by
      (const) reference.

      • Rasikko

        Ok, I think I understand. My machine is 64bit. So it appears it's ok to pass by value(they are all numeric types) and to pass by reference if it's other types or the whole class/struct. Thank you for your answer. I was stuck on that for sometime.

  • Aitor

    Hi Alex,
    i'm trying to understand, why "const int& variableName" as a function parameter works with constant literals, it is a thing that always confuse me. So having the code below:

    we could say, that both expressions are, in some way, an r-value references but the only difference between the first and the second one, is the first one (const int& i) cannot be modify, and the second one (int&& x) can be modify? or i'm just totally confused. Thanks for your time.

    Best regards, Aitor

    • Alex

      Both of the above are l-value references. The first is a const l-value reference assigned to r-value 10. In the latter, the second ampersand is essentially ignored -- named r-value references are l-values! So this becomes non-const l-value reference assigned to r-value 10. Remember, l-value and r-value are properties of expressions, not variables. We use the term r-value reference not to denote that the variable is an r-value itself, but to denote the type of expressions that it can reference.

  • ty

    Hi, dear Alex, May I ask when you say

    Const references can accept any type of argument, including l-values, const l-values, and r-values.

    the r-values. How come when not pass by const reference we cant recevied the r-values but when we declare a const parameter we can pass the r- values? r-value are literals right? they do not have address am i right thanks so much!

    • Alex

      r-values can be literals or temporary values. When you bind a const reference to an r-value, the duration of the r-value is extended to match the reference. This is useful because it allows us to pass r-values to functions by reference! Otherwise we'd have to pass them by value, which requires making a copy (or in C++11, by r-value reference).

  • D Brown

    In chapter 6 on question 2 I believe in the solution you passed a structure to the function and it was void because it changed the argument. I was very confused since I'm not sure we had done this before. Would be it be appropriate to add a note since its explained after the fact? I apologize if it is explained before that.

  • KG

    You have written: "Some programmers and companies feel this is a big enough program to advise not passing by reference this way..."

    I'm guessing you meant to write "big enough problem..." instead?

    This is all fantastic stuff by the way, I've been meaning to learn C++ for quite some time but always felt a little intimidated, but perhaps it's not quite as complicated as I had led myself to believe.

  • KOBE JAPONICA

    Hello Alex. I refer learn c++ almost everyday. I respect you as a ubiquitous tutor.  
    You say that
    Disadvantages of passing by reference:
    Because a non-const reference cannot be made to an non-const l-value or an r-value (e.g. a literal or an expression)

    But, I think that
    Because a non-const reference cannot be made to an const l-value or an r-value (e.g. a literal or an expression)

    Is it correct or not?

Leave a Comment

Put all code inside code tags: [code]your code here[/code]