How string accepting interface should look like?

Question

This is a follow up of this question. Suppose I write a C++ interface that accepts or returns a const string. I can use a const char* zero-terminated string:

void f(const char* str); // (1)

The other way would be to use an std::string:

void f(const string& str); // (2)

It's also possible to write an overload and accept both:

void f(const char* str); // (3)
void f(const string& str);

Or even a template in conjunction with boost string algorithms:

template<class Range> void f(const Range& str); // (4)

My thoughts are:

• (1) is not C++ish and may be less efficient when subsequent operations may need to know the string length.
• (2) is bad because now f("long very long C string"); invokes a construction of std::string which involves a heap allocation. If f uses that string just to pass it to some low-level interface that expects a C-string (like fopen) then it is just a waste of resources.
• (3) causes code duplication. Although one f can call the other depending on what is the most efficient implementation. However we can't overload based on return type, like in case of std::exception::what() that returns a const char*.
• (4) doesn't work with separate compilation and may cause even larger code bloat.
• Choosing between (1) and (2) based on what's needed by the implementation is, well, leaking an implementation detail to the interface.

The question is: what is the preffered way? Is there any single guideline I can follow? What's your experience?

Edit: There is also a fifth option:

void f(boost::iterator_range<const char*> str); // (5)

which has the pros of (1) (doesn't need to construct a string object) and (2) (the size of the string is explicitly passed to the function).

Answer 1

If you are dealing with a pure C++ code base, then I would go with #2, and not worry about callers of the function that don't use it with a std::string until a problem arises. As always, don't worry too much about optimization unless there is a problem. Make your code clean, easy to read, and easy to extend.

Answer 2

There is a single guideline you can follow: use (2) unless you have very good reasons not to.

A const char* str as parameter does not make it explicit, what operations are allowed to be performed on str. How often can it be incremented before it segfaults? Is it a pointer to a char, an array of chars or a C string (i.e. a zero-terminated array of char)?

Answer 3

I don't really have a single hard preference. Depending on circumstances, I alternate between most of your examples.

Another option I sometimes use is similar to your Range example, but using plain old iterator ranges:

template <typename Iter>
void f(Iter first, Iter last);

which has the nice property that it works easily with both C-style strings (and allows the callee to determine the length of the string in constant time) as well as std::string.

If templates are problematic (perhaps because I don't want the function to be defined in a header), I sometimes do the same, but using char* as iterators:

void f(const char* first, const char* last);

Again, it can be trivially used with both C-strings and C++ std::string (as I recall, C++03 doesn't explicitly require strings to be contiguous, but every implementation I know of uses contiguously allocated strings, and I believe C++0x will explicitly require it).

So these versions both allow me to convey more information than the plain C-style const char* parameter (which loses information about the string length, and doesn't handle embedded nulls), in addition to supporting both of the major string types (and probably any other string class you can think of) in an idiomatic way.

The downside is of course that you end up with an additional parameter.

Unfortunately, string handling isn't really C++'s strongest side, so I don't think there is a single "best" approach. But the iterator pair is one of several approaches I tend to use.

Answer 4

For taking a parameter I would go with whatever is simplest and often that is const char*. This works with string literals with zero cost and retrieving a const char* from something stored in a std:string is typically very low cost as well.

Personally, I wouldn't bother with the overload. In all but the simplest cases you will want to merge to two code paths and have one call the other at some point or both call a common function. It could be argued that having the overload hides whether one is converted to the other or not and which path has a higher cost.

Only if I actually wanted to use const features of the std::string interface inside the function would I have const std::string& in the interface itself and I'm not sure that just using size() would be enough of a justification.

In many projects, for better or worse, alternative string classes are often used. Many of these, like std::string give cheap access to a zero-terminated const char*; converting to a std::string requires a copy. Requiring a const std::string& in the interface is dictating a storage strategy even when the internals of the function don't need to specify this. I consider it this to be undesirable, much like taking a const shared_ptr<X>& dictates a storage strategy whereas taking X&, if possible, allows the caller to use any storage strategy for a passed object.

The disadvantages of a const char* are that, purely from an interface standpoint, it doesn't enforce non-nullness (although very occasionally the difference betweem a null parameter and an empty string is used in some interfaces - this can't be done with std::string), and a const char* might be the address of just a single character. In practice, though, the use of a const char* to pass a string is so prevalent that I would consider citing this as a negative to be a fairly trivial concern. Other concerns, such as whether the encoding of the characters specified in the interface documentation (applies to both std::string and const char*) are much more important and likely to cause more work.

Answer 5

The answer should depend heavily on what you are intending to do in f. If you need to do some complex processing with the string, the approach 2 makes sense, if you simply need to pass to some other functions, then select based on those other functions (let's say for arguments sake you are opening a file - what would make most sense? ;) )

Answer 6

It's also possible to write an overload and accept both:

void f(const string& str) already accepts both because of the implicit conversion from const char* to std::string. So #3 has little advantage over #2.

Answer 7

I would choose void f(const string& str) if the function body does not do char-analysis; means it's not referring to char* of str.

Answer 8

Use (2).

The first stated problem with it is not an issue, because the string has to be created at some point regardless.

Fretting over the second point smells of premature optimization. Unless you have a specific circumstance where the heap allocation is problematic, such as repeated invocations with string literals, and those cannot be changed, then it is better to favor clarity over avoiding this pitfall. Then and only then might you consider option (3).

(2) clearly communicates what the function accepts, and has the right restrictions.

Of course, all 5 are improvements over foo(char*) which I have encountered more than I would care to mention.