doc: confusing language in util.format() docs

[q42jaap]

214d020

The intention to speed up util.format breaks the following case:

util.format('%%')

prior to this commit, this returned '%', now it returns '%%'.

Imho, this is a bug and should be reverted.

[q42jaap]

This works correctly in node 0.12
broken in node 4 and up

[evanlucas]

to me, if util.format('%%') is supposed to return %, then util.format('%s') would return s. I don't really think the previous return value is intuitive. At this point, I'm not sure changing it back would be worth it. Is there a scenario where this is causing a problem for you?

[mscdex]

FWIW it's only an issue when you don't pass any additional arguments to format().

[addaleax]

The current behaviour also matches the one that browsers have in console.log, fwiw.

@evanlucas The idea is been that if strings like %s are used as placeholders, then %% is the way to escape a percent sign. It’s been that way since printf() was invented, and that’s what most languages do, so I would suggest to not deviate in Node. (edit: maybe I misunderstood you – I assumed you were talking about the formatting function of util.format for multiple arguments)

[aqrln]

If the first argument is not a format string then util.format() returns a string that is the concatenation of all arguments separated by spaces. Each argument is converted to a string using util.inspect().

(https://nodejs.org/dist/latest-v7.x/docs/api/util.html#util_util_format_format_args)

I'd rather we clarify it here that if a string is the only argument, it cannot be a format string by definition, so it is returned as is.

[evanlucas]

@addaleax I probably should have clarified. I was thinking only in the case of a single argument.

[addaleax]

Yeah, I realized too late that I probably misunderstood you. 😄

[aqrln]

So how about making it a good first contribution documentation issue (#12362 (comment))?

[q42jaap]

I still think, that util.format should behave more like printf in C than console.log in javascript.

[q42jaap]

The case is winston logging a sql query with wildcards WHERE column LIKE '%string_with_s%' which I had to escape to WHERE column LIKE '%%string_with_s%%'.
winston calls util.format.apply(null, args), which in my case uses just 1 parameter.

Given that there wasn't a testcase allowing the performance improvement to break code unnoticed, I'd still opt for printf behavior over console.log.

[q42jaap]

#include <stdio.h>

int main() {
  printf("%%\n");
}

will print % not %%.

[bnoordhuis]

What printf() does is irrelevant though, util.format() is used to implement console.log() and that prints '%%' in browsers and node. Moving to close.

[q42jaap]

@bnoordhuis the docs mention printf specifically... So it is definitely not irrelevant. Furthermore, the bug was unintentionally introduced in given commit. There should have been a testcase.
Other than the mentioning of printf, the docs lay out a clear path for how tokens are processed. %% is a token that does not consume an argument and just prints %.

This is just wrong!

[bnoordhuis]

I'm willing to concede the docs are wrong (didn't check) but the behavior itself brings node closer to browsers. I see no reason to roll that back. "It's not like printf" is not a compelling argument to me.