String replace returns void instead of String [Resolved]

Firmware
1

The documentation of the String class says that replace() returns a new String:

string.replace(substring1, substring2)
Parameters:
string: a variable of type String
substring1: another variable of type String
substring2: another variable of type String
Returns: another String containing the new string with replaced characters.

However, the source code seems to indicate that the return type is void:

core-firmware/src/spark_wiring_string.cpp:
void String::replace(const String& find, const String& replace)

Is this a bug or simply an outdated API documentation?

2

When it says “Returns:” it’s not really implied as if it’s a returned value from a function call. Since the String we are talking about here is a Class, it has Methods and those methods are functions… yes… but the Input is the instance of the String object string from your example, and the “Returns:” is actually saying "when your program continues past the point you executed string.replace(substring1, substring2), that string will contain the new string with replaced characters.

Where that value lives is here, in an instance of a char buffer:
https://github.com/spark/core-firmware/blob/master/inc/spark_wiring_string.h#L188-L189

3

Thanks. That’s an unusual meaning of “Returns:”, but will do. Thanks for the clarification.

4

Well, I’d say that the documentation is incorrect, then. It would be more correct for it to say that the method returns nothing, but that the original string is modified in-place.

It’s kind of an important distinction. :smile: