Reason to Pass a Pointer by Reference in C++?

Under which circumstances would you want to use code of this nature in c++?

void foo(type *&in) {...}

void fii() {
  type *choochoo;
  ...
  foo(choochoo);
}

Solution 1:

You would want to pass a pointer by reference if you have a need to modify the pointer rather than the object that the pointer is pointing to.

This is similar to why double pointers are used; using a reference to a pointer is slightly safer than using pointers.

Solution 2:

50% of C++ programmers like to set their pointers to null after a delete:

template<typename T>    
void moronic_delete(T*& p)
{
    delete p;
    p = nullptr;
}

Without the reference, you would only be changing a local copy of the pointer, not affecting the caller.

Solution 3:

David's answer is correct, but if it's still a little abstract, here are two examples:

1. You might want to zero all freed pointers to catch memory problems earlier. C-style you'd do:

   void freeAndZero(void** ptr)
   {
       free(*ptr);
       *ptr = 0;
   }
   
   void* ptr = malloc(...);
   
   ...
   
   freeAndZero(&ptr);
   

   In C++ to do the same, you might do:

   template<class T> void freeAndZero(T* &ptr)
   {
       delete ptr;
       ptr = 0;
   }
   
   int* ptr = new int;
   
   ...
   
   freeAndZero(ptr);
   

2. When dealing with linked-lists - often simply represented as pointers to a next node:

   struct Node
   {
       value_t value;
       Node* next;
   };
   

   In this case, when you insert to the empty list you necessarily must change the incoming pointer because the result is not the NULL pointer anymore. This is a case where you modify an external pointer from a function, so it would have a reference to pointer in its signature:

   void insert(Node* &list)
   {
       ...
       if(!list) list = new Node(...);
       ...
   }
   

There's an example in this question.

Solution 4:

I have had to use code like this to provide functions to allocate memory to a pointer passed in and return its size because my company "object" to me using the STL

 int iSizeOfArray(int* &piArray) {
    piArray = new int[iNumberOfElements];
    ...
    return iNumberOfElements;
 }

It is not nice, but the pointer must be passed by reference (or use double pointer). If not, memory is allocated to a local copy of the pointer if it is passed by value which results in a memory leak.

Solution 5:

One example is when you write a parser function and pass it a source pointer to read from, if the function is supposed to push that pointer forward behind the last character which has been correctly recognized by the parser. Using a reference to a pointer makes it clear then that the function will move the original pointer to update its position.

In general, you use references to pointers if you want to pass a pointer to a function and let it move that original pointer to some other position instead of just moving a copy of it without affecting the original.