Re: [PATCH] Strbuf documentation: document most functions

Miklos Vajna schrieb:

It can be used to expand a format string containing placeholders. To that end, it parses the string and calls the specified function for every percent sign found.

The callback function is given a pointer to the character after the '%' and a pointer to the struct strbuf. It is expected to add the expanded version of the placeholder to the strbuf, e.g. to add a newline character if the letter 'n' appears after a '%'. The function returns the length of the placeholder recognized and strbuf_expand skips over it.

All other characters (non-percent and not skipped ones) are copied verbatim to the strbuf. If the callback returned zero, meaning that the placeholder is unknown, then the percent sign is copied, too.

In order to facilitate caching and to make it possible to give parameters to the callback, strbuf_expand passes a context pointer, which can be used by the programmer of the callback as she sees fit.

You can see it in action in pretty.c, where it expands --pretty=format: placeholder strings. The callback may be a bit heavy for a first encounter, though. ;-)

René