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);
}

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.

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.

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.

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.

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.

Another situation when you may need this is if you have stl collection of pointers and want to change them using stl algorithm. Example of for_each in c++98.

struct Storage {
  typedef std::list<Object*> ObjectList;
  ObjectList objects;

  void change() {
    typedef void (*ChangeFunctionType)(Object*&);
    std::for_each<ObjectList::iterator, ChangeFunctionType>
                 (objects.begin(), objects.end(), &Storage::changeObject);
  }

  static void changeObject(Object*& item) {
    delete item;
    item = 0;
    if (someCondition) item = new Object();
  } 

};

Otherwise, if you use changeObject(Object* item) signature you have copy of pointer, not original one.