deprecation(semver): rename `format*()` to `stringify*()`

[timreichen]

renames

• comparatorFormat() => stringifyComparator()
• format() => stringify() -~~rangeFormat() => stringifyRange()~~

deprecates all old functions.

Note stringify() has a different api than format(): It does not take a FormatStyle but stringifies everything that is passed as an Partial<SemVer>

[timreichen]

This also concerns stringifyRange: https://github.com/denoland/deno_std/pull/3957#issuecomment-1857116472

Please do not merge until this fundamental problem is solved.

[timreichen]

@iuioiua similar to https://github.com/denoland/deno_std/pull/3957, I also revert the Range changes here.

[kt3k]

I don't see the motivation of this change well. stringify sounds confusing than format to me.

[timreichen]

I don't see the motivation of this change well. stringify sounds confusing than format to me.

Reason is that the name fits the function better. The SemVer is not formatted but predicatively turned into a string. It is also more intuitive name because there are lots of parse/stringify function pairs in std and web APIs (JSON for example) that do the reverse process from each other.

[kt3k]

From my observation, stringify name is usually used for serialization of complex object/data to string representation (such as the case of toml, yaml, csv, json, etc), on the other hand, format is used for formatting something into human-readable form (such as the case of fmt/bytes, fmt/duration). I think format function of semver module belongs to the 2nd category because it can't contain complex data in it.

[timreichen]

From my observation, stringify name is usually used for serialization of complex object/data to string representation (such as the case of toml, yaml, csv, json, etc), on the other hand, format is used for formatting something into human-readable form (such as the case of fmt/bytes, fmt/duration). I think format function of semver module belongs to the 2nd category because it can't contain complex data in it.

I don't think complexity is a a parameter. format() normally has options how it should be formatted, because there are multiple ways of a value representation (for example style: "narrow" | "digital" | "full" in fmt/duration or style: "decimal" | "currency" | "percent" | "unit" in Intl.NumberFormat. That is not the case with stringify(). And a SemVer only has one string represention.

[iuioiua]

I agree with Tim's points. These functions appear to be more fitting for stringify* names.

[kt3k]

That is not the case with stringify().

JSON.stringify has formatting options: replacer and space

I still don't see the motivation of the rename. The first line of jsdoc of stringify says Format a SemVer object into a string. Doesn't this imply format is the natural name for it?

I kind of agree that style option of format is not useful. Why not just deprecate that option?

[timreichen]

That is not the case with stringify().

JSON.stringify has formatting options: replacer and space

That is true. The replacer function is basically a property preprocessor function. space on the other hand actually changes the format of the output, but that whitespace is ignored by the parser. So the appearance changes, but the output of the value is lossless.

I still don't see the motivation of the rename. The first line of jsdoc of stringify says Format a SemVer object into a string. Doesn't this imply format is the natural name for it?

I think we just need to be consistent in std, because we have both names format and stringify which do the same task. How would you differentiate between the two?

I kind of agree that style option of format is not useful. Why not just deprecate that option?

I agree, that could be done in any case.

[kt3k]

I think we just need to be consistent in std, because we have both names format and stringify which do the same task. How would you differentiate between the two?

In my view stringify is synonymous to serialize. The output can be extremely long and unreadable to humans, but they are machine readable. The output of format is mainly for human readability on the other hand.

[timreichen]

In my view stringify is synonymous to serialize. The output can be extremely long and unreadable to humans, but they are machine readable. The output of format is mainly for human readability on the other hand.

Ok, I see what you mean. I will close this PR for now, but I think we should find an objective definition. Human readable is a really loose term, wasn't json designed to be human readable? Some of the std modules are using the terms interchangeably (toml stringify calls dump on an Dumper instance which internally calls #format for example).