sys/string_utils: add string_writer helper

[benpicco]

Contribution description

Assembling a string through multiple writes if often open-coded like this

char buffer[64];
size_t len = 0;
for (unsigned i = 0; i < ARRAY_SIZE(names); ++i) {
    len += snprintf(&buffer[len], sizeof(buffer) - len, "%u: %s\n", i, names[i]);
}

This is error prone (the above example foregoes any error handling) and ugly.

This introduces a small helper function to achieve the same in a much more convenient fasion:

char buffer[64];
string_writer_t sw;
string_writer_init(&sw, buffer, sizeof(buffer));

for (unsigned i = 0; i < ARRAY_SIZE(names); ++i) {
    swprintf(&sw, "%u: %s\n", i, names[i]);
}

Testing procedure

A new unit test has been added.

Issues/PRs references

[maribu]

That API indeed disarms the usual footguns :)

I wonder if there is some BSD / whatever API already that we could steal?

[Teufelchen1]

All in all looks good. Some nits, some ideas.

You mentioned that this is often done manually in RIOT, could you also replace such instances with this helper right away?

[Teufelchen1]

I think it is worth it, to use a new string_writer_t + buffer. Not because it's technically needed but it signals to the reader "we are testing a new/different behavior". Also, which behavior is tested here? ;)

[benpicco]

No this is all the same string write - we want to append to it until it's full and test at every step that it behaves as expected.

I added comments to better explain what's going on.

[Teufelchen1]

Great improvements.

[Teufelchen1]

Squash & Ci?

[riot-ci]

Murdock results

❌ FAILED

0fe3ac4 unittests: add test for string_writer

Success	Failures	Total	Runtime
28	0	9199	01m:33s

Artifacts

[derMihai]

you can add

__attribute__ ((format (printf, 2, 3)))

to enable static printf-like compiler checks for the format string and arguments, see https://gcc.gnu.org/onlinedocs/gcc-3.2/gcc/Function-Attributes.html.

[derMihai]

clang should complain here, you can:

#ifdef __clang__
    _Pragma("clang diagnostic push") \
    _Pragma("clang diagnostic ignored \"-Wformat-nonliteral\"") \
    res = vsnprintf(sw->position, sw->capacity, format, args);
    _Pragma("clang diagnostic pop")
#else
    res = vsnprintf(sw->position, sw->capacity, format, args);
#endif

[derMihai]

if res == capacity, the output was truncated by one character. This check should therefore be <.