.. highlight:: c++
  :linenothreshold: 5

.. _ref-in-functions:

***************************
Reference-type in Functions
***************************

.. _pass-by-ref:

Pass by reference
=================
+ Allows modifications of the actual parameters::

    // modifies the actual parameter
    // no return value
    void addOne(int &var) {
      ++var;
    }

    int main() {
      int a = 10;
      addOne(a);  // the actual parameter is a, must be an lvalue
      cout << a << endl;  // 11
      return 0;
    }

+ Avoid duplication of the value (reduce overhead when the value is an
  object)::

    string processText(const string &inputText) {
      string processedText;
      // process the text
      return processedText;
    }

    int main() {
      string inputText = "This is a very long text";
      string result = processText(inputText);
      cout << result << endl;
    }

+ It is a good practice to always use pass-by-reference for objects
  (class-typed variables)
+ Extensively used in many scenarios

  * copy constructor
  * copy assignment operator overloading

Returning a Reference
=====================
Returning a reference allows a function call to be used as a lvalue. It allows
modifications to the result of a function call.

::

  class MyArr {
   private:
    int *arr;
    int size;
   public:
    MyArr();
    MyArr(int size, int value);
    ~MyArr();
    int &at(int i);
  };

  // returns a reference
  int & MyArr::at(int i) {
    return arr[i];  // the reference to arr[i] is passed out
  }

  int main() {
    MyArr myArr1(10, 10);
    myArr1.at(0) = 10;  // you can assign a value to a function call now
                        // because myArr1.at() is an alias of myArr1.arr[i]
    myArr1.at(1)++;
  }

.. warning::

  Never return a reference to a local variable! Returning a reference to an
  instance variable is fine.