Amount toString serialization discussions

[sffc]

Diving straight in: there are a number of constraints around toString, which could carry different weight:

• Should be consistently (always or never) parseable by existing parse functions like JSON.parse and Number.parseFloat
• Should work seamlessly with sequence units
• Should be parseable by a custom parser
• Should be developer-readable
• Should build on top of existing serialization formats if possible

Any other constraints? Please comment below.

With that in mind, here are some possible syntaxes for these inputs:

• Unitless: { value: 1, unit: null }
• Meter: { value: 5, unit: "meter" }
• Sequence: { value: { pound: 7, ounce: 1 }, unit: "pound-and-ounce" }

Name	Unitless	Meter	Sequence
Stage 2	[1e+0 ~]	[5e+0 meter]	[7e+0 pound, 1e+0 ounce]
With IXDTF annotations	1e+0[]	5e+0[meter]	7e+0,1e+0[pound-and-ounce]
Raw JSON	{"value":1e+0,"unit":null}	{"value":5e+0,"unit":"meter"}	{"value":{"pound":7e+0,"ounce":1e+0},"unit":"pound-and-ounce"}
Nicer JS, A	[{value:1e+0}]	[{value:5e+0,unit:"meter"}]	[{value:7e+0,unit:"pound"},{value:1e+0,unit:"ounce"}]
Nicer JS, B	[1e+0]	[{meter:5e+0}]	[{pound:7e+0},{ounce:1e+0}]
Inspired by ISO 8601 P-string	A1e+0	A5e+0meter	A7e+0pound1e+0ounce
P-string with well-known abbreviations	A1e+0	A5e+0M	A7e+0L1e+0O
P-string with annotations	A1e+0	A5e+0[meter]	A7e+0[pound]1e+0[ounce]

Please feel free to offer more ideas.

[gibson042]

Note that the "P-string" rows other than "with annotations" as written are incompatible with any unit whose first character is a digit, such as the deprecated "1e6" (e.g., A51e6 is ambiguous between { value: 5, unit: "1e6" } and { value: 51, unit: "e6" }).

Also, "Should be consistently (always or never) parseable by existing parse functions like JSON.parse and Number.parseFloat" does not accurately capture my constraint that output is always mapped to NaN by parseFloat, parseInt, and Number (i.e., I'm open to always-or-never only for JSON.parse and similarly powerful parsers), which eliminates from consideration the "With IXDTF annotations" row as written.

And finally, I recommend tweaking the table header for better rendering:

-| Name | { value: 1, unit: null } | { value: 5, unit: "meter" } | { value: { pound: 7, ounce: 1 }, unit: "pound-and-ounce" } |
+| Name | unitless | meter | pound-and-ounce |

preview

Name	unitless	meter	pound-and-ounce
Stage 2	[1 ~]	[5 meter]	[7 pound, 1 ounce]
With IXDTF annotations	1[]	5[meter]	7+1[pound-and-ounce]
Raw JSON	{"value":1,"unit":null}	{"value":5,"unit":"meter"}	{"value":{"pound":7,"ounce":1},"unit":"pound-and-ounce"}
Nicer JS, A	[{value:1}]	[{value:5,unit:"meter"}]	[{value:7,unit:"pound"},{value:1,unit:"ounce"}]
Nicer JS, B	[1]	[{meter:5}]	[{pound:7},{ounce:1}]
Inspired by ISO 8601 P-string	A1	A5meter	A7pound1ounce
P-string with well-known abbreviations	A1	A5M	A7L1O
P-string with annotations	A1	A5[meter]	A7[pound]1[ounce]

[gibson042]

It would be nice for the sequence-unit example to include a medial zero (e.g. unit degree-and-arc-minute-and-arc-second with value 1 degree 59 seconds), because that introduces multiple possibilities for serialization (although I think we'll just always include each unit in the sequence rather than omitting zeros).

[eemeli]

All the numeric values should be 1e+0, 5e+0, etc, unless you're also proposing that we revert the changes we've recently made to always using exponential syntax?

[gibson042]

The fundamental variation introduced by "P-string" rows is use of a prefix rather than a (prefix, suffix) pair. It's nice, but I don't think we'd go for just the letter "A", which fails to intuitively convey "Amount". If we do head in that direction, I would instead expect punctuation, e.g. ~1/~5[meter]/~7[pound]1[ounce]¹.

Footnotes

1. I know, I keep reaching for ~... other possibilities that come to mind are =, :=, U+2248 ALMOST EQUAL TO ≈, U+2245 APPROXIMATELY EQUAL TO ≅, and U+224A ALMOST EQUAL OR EQUAL TO ≊ (but the latter two become very ugly at small font sizes, and even ≈ is borderline). ↩

[sffc]

I changed the table headers and added e+0 to the values.

[gibson042]

Repeating my constraints on amount.toString() output from #97 (comment) and adding @eemeli's amendment:

Required

1. It is always mapped to NaN by parseFloat, parseInt, and Number (in practice, this likely means that it must start with punctuation—and probably not +, -, or .).
2. It is either always accepted or always rejected by eval and JSON.parse.
3. Absence of a unit is not visually confusable with use of a potentially valid unit (cf. Change serialization style #102 (comment)).
4. If it is not opaque, then it does not preclude representation of mixed units like foot-and-inch (although the representation of such mixtures might possibly consist of separate [number, unit] pairs).

Valuable

By descending value:

1. It can be used to mechanically reconstruct an equivalent Amount by a simple approach that works for unitless, single-unit, and mixed-unit Amounts (and complexity that would result in subtle incorrectness of a naïve manual implementation is minimal).
2. It is understandable by a human who has not read any documentation on Amount.
3. It is concise.
4. Absence of a unit is represented by omission rather than by substitution with a placeholder pseudo-unit such as ∅ or ~, unless there is no such condition as "absence of a unit" (e.g., because unit defaults to a special value such as 1).

[gibson042]

I changed the table headers and added e+0 to the values.

It still needs [7 pound, 1e+0 ounce] → [7e+0 pound, 1e+0 ounce], and there's no way 7e+0+1e+0[pound-and-ounce] is on the table... maybe change that middle + (e.g., 7e+0:1e+0[pound-and-ounce]).

[sffc]

I changed the table headers and added e+0 to the values.

It still needs [7 pound, 1e+0 ounce] → [7e+0 pound, 1e+0 ounce], and there's no way 7e+0+1e+0[pound-and-ounce] is on the table... maybe change that middle + (e.g., 7e+0:1e+0[pound-and-ounce]).

Fixed

[eemeli]

Of the options above, I prefer to keep the "Stage 2" presentation, i.e. what we currently have in the proposal. It's the one that I find easiest to quickly read, while remaining easily machine-parseable. In other words it looks like debugging output, which I consider to be the primary audience for this serialization.

All the other serializations look like they're primarily meant for machine parsing, and only secondarily for human parsing.

[gibson042]

I agree with @eemeli. I'm not thrilled about unitless Amounts having a pseudo-unit placeholder (although that could be avoided by using braces rather than brackets, e.g. {1e+0}/{5e+0 meter}/{7e+0 pound, 1e+0 ounce}), and the comma–space separation of unit sequences is a bit contrived, but overall it seems to strike the right balance.

[sffc]

I see it as very important to essential that the serialization format, if we have one, supports future extensions to Amount, such as precision annotations and rational numbers.