Sometimes I see functions that are meant to return a range of values, but instead of returning a container, they take one as out-parameter. There are several reasons why that is not the Right Thing to do.

The basic pattern looks like this:

void getValues(vector<MyValueType>& values) {
  values.clear();
  for (/* some loop conditions */) {
    values.push_back(anotherValue);
  }
}

void someWhereElse() {
  vector<MyValueType> values;
  getValues(values);

  //work with the values
}

The parameter to `getValues` typically is a pure out-parameter, i.e. the function does not care what’s in the container or, like in the example, clears the container just in case.

Sometimes it even gets worse – the above functionality is doubled by a function that does it right, and it is not clear what function is supposed to be used in what circumstances:

vector<MyValueType> getValues()
{
  vector<MyValueType> values;
  getValues(values);
  return values;
}

Why do people think this should be done? To be honest, I am not too sure about that. I have heard that it might be more performant than returning a container and initializing another with that return value.

But what I heard were only rumors, because nobody I heard that statement from was able to provide actual measurements to reinforce the claim.

(Named) Return Value Optimization and copy elision

The RVO, NRVO and copy elision are optimizations made by the compiler that have been around for some time now in most or all major compilers. And with “some time” I don’t mean two or three years. The first implementations of such optimizations have been made in the early 1990s.

Those optimizations are specifically aimed at the up to two copies that in theory would have to be made of an object returned by a function. When they are applied it means, that the compiler does not have to create an object for the variable inside the function and another for the temporary return value. It will perform the construction in place:

vector<MyValueType> getValues() {
  vector<MyValueType> values;        //constructs the myValues object below
  for (/* some loop conditions */) {
    values.push_back(anotherValue);
  }
  return values;                     //no temporary copy here
}

void someWhereElse() {
  vector<MyValueType> myValues = getValues(); //no copy construction here

  //work with the values
}

Trust your compiler when it comes to return value optimization. Never optimize prematurely.

Move semantics

Since C++11 there are rvalue references and move semantics. Any standard library container supports move construction and move assignment, and so should any other container.

With move semantics, the container constructed inside the function will be moved out of the function on the return statement, and the container outside the function will be move constructed or move assigned with the temporary object returned by the function.

So even if your compiler can not apply return value optimization and copy elision for some reason, move semantics will guarantee that no memory allocation is needed and the objects inside the container need not be copied. All that has to be done is usually a few cheap copies of pointers and integers.

Rely on move semantics. If your compiler and library do not support it, get a modern compiler – it really does pay off.

Simplicity and maintainability

Here we go again with the main theme of this blog: Passing the container as an out-parameter is not what would be considered clean code, because it confuses the reader.

People are used to have functions, that get their inputs via arguments and return their outputs via return values. Disguising the return value as parameter is an obfuscation and a hindrance to readability.

So, even if you are stuck with an ancient compiler that supports neither move semantics nor (N)RVO and copy elision, you are often better off returning the container, because readability is much more important than gaining a bit of performance in a place where performance is not critical.

Update:

Of course there are times when passing the container as out-parameter is beneficial and maybe even the only viable option. Such cases include reuse of the container and it’s allocated memory in loops, allocators hidden by type erasure and other cases that are usually done to optimize certain aspects of the porgram.

However, the pass by out-parameter is often done as a default in cases where there is no evidence of a need for optimization and the percieved performance improvement is not as big as thought by implementors.