Should std::string be returned by value from a function or by "std::string &s" as an argument?

Question

For returning a string out of a function, which of these two is more efficient (i.e. which one should I be using):

std::string f(const std::string& s)
{
    return s + "some text";
}

or

void f(const std::string& s, std::string &result)
{
    result = s + "some text";
}

I understand that maybe the answer depends on a particular compiler. But I want to know what the recommended approach (if there is one) is in a modern C++ code.

Based on "Lightness Races in Orbit" comment below, here are some related questions that I found on stackoverflow before I asked this question:

Are the days of passing const std::string & as a parameter over?

Passing std::string by Value or Reference

Pass by value or const reference?

"std::string" or "const std::string&" argument? (the argument is internally copied and modified)

None of which answer my particular question regarding returning a value from a function versus returning the string as an extra argument.

Answer 1

Let me micro-optimize your second version of f() and call it g():

#include <cstdio>
#include <string>
using namespace std;

string f(const string& s) {
    return s + "some text";
}

void g(const string& s, string &result) {
    result.clear();
    result += s;
    result += "some text";
}

Now, let's compare the return by value approach f() to the "out-parameter" approach g().

Return by value:

int main(int argc, char* argv[]) {

    string s(argv[1]);

    for (int i=0; i<10; ++i) {

      string temp = f(s); // at least 1 memory allocation in each iteration, ouch!

      fprintf(stderr, "%s\n", temp.c_str());
    }
}

In each iteration, there is a memory allocation. The total number of allocations will be the number of iterations + 1, that is, 11 in this case.

The "out-parameter" approach:

int main(int argc, char* argv[]) {

    string s(argv[1]);

    string temp; // note that this time, it is outside the loop

    for (int i=0; i<10; ++i) {

      g(s, temp);

      fprintf(stderr, "%s\n", temp.c_str());
    }
}

In this case, you get 3 memory allocations (assuming the buffer of temp doesn't need to be re-allocated inside the loop), even if you iterate 1000000 times! That is a significant improvement over the return by value approach.

Returning by value and relying on copy-elision or on move semantics is a good advice, but as the example shows, there are situations in which the out-parameter approach wins (e.g. when you can re-use a buffer).

The danger with out-parameters is that at the call site, it must be obvious, just by looking at the code, that the function is modifying some of its arguments. The name of the function must strongly suggest that it is mutating some of its arguments. Otherwise you get surprising results... :(

If you find this example too twisted, well, it isn't: Think of std::getline()!

And for those who think it is premature optimization: In case of std::getline() it certainly isn't! If you shove the lines of a file into a std::vector and allocate a new string for each line it will be 1.6x slower than the out-paramter approach (with lines of 80 bytes). It sounds crazy as the file IO should be the bottleneck but it isn't, it is the unnecessary memory allocations. For details, see Andrei Alexandrescu: Writing Quick Code in C++, Quickly at around 48 min.

---

UPDATE:

1. R. Martinho Fernandes kindly pointed out below in comments that his measurements with gcc contradict my results but are in agreement with my claims with clang and libc++; see GCC and Clang.

2. After he pointed out these, I made measurements on Andrei Alexandrescu's example. At the moment, I cannot reproduce his results; it needs further analysis as to understand what is happening under the hood.

Please be patient and give me some time to clear up the inconsistencies.

The take-away of this story is to always measure. I did measure the number of memory allocations mentioned in the answer, that is still OK (at least on my machine).

Answer 2

The first alternative, return s + "some text";, is simpler. Its behavior in terms of memory allocation is also simple: first s + "some text is evaluated, presumably causing allocation of a new string object with sufficient capacity to hold the result. That object is the return value, assuming copy elision, otherwise a move occurs.

The second interface, as Ali notes, gives the user an opportunity to reuse a string buffer over several calls. Availing of the ability requires a bit more code and incurs a bit more complexity.

Furthermore according to his measurements it's hard to tell which really wins in general. Fortunately, there is a middle path:

#if STRING_BUFFER_REUSE_OPTIMIZATION

string h( string const & s, string && result = {} ) {
    result.clear();
    result += s;
    result += "some text";
    return std::move( result );
}

#else

string const no_hint = {};

string h( string const & s, string const & hint = no_hint ) {
    return s + "some text";
}

#endif

With this, you can set the STRING_BUFFER_REUSE_OPTIMIZATION macro according to measurements du jour on each build target. Both memory access styles are adapted to the same interface with no sacrifices.

Answer 3

For returning a newly created string, I would definitely go with the return-by-value approach. The typical compiler implementation of returning objects by value is having the compiler allocate space for the object in the calling function, and passing it a pointer to that allocated space, which is essentially the same as your reference parameter, but with one important difference: The pass-by-reference output parameter needs that the reference to a fully constructed string is passed into the function that gets overwritten by the results, while in the return-by-value case, the function constructs the object itself.

Note that there is one specific use case in which the pass-by-reference solution is faster: If a caller calls this function repeatedly to change the same variable, the overwrite inside the function is exactly what is needed, while returning and assigning in the caller would cause the result to be constructed in a temporary which gets (move) assigned to the variable on the caller side. If you use pre-C++11 compilers, it even gets copy-assigned.