Custom format strings with section separators have weird behavior

[tannergooding]

Currently, there seems to be a lot of "weird" behavior around the section separator and it doesn't seem to be consistent.

For example, from the docs for the "three section" case:

The second section can be left empty (by having nothing between the semicolons), in which case the first section applies to all nonzero values.

The "two section" case doesn't have any explicit wording on it, but I would imagine it would/should follow the same logic.

For "-1234.0" and various format specifiers, we currently get the following:

Format Specifier	Output
""	-1234
";"	-
"#;"	-1234
";#"	1234
"#;#"	1234
";;"	-
"#;;"	-1234
";#;"	1234
";;#"	-
"#;#;"	1234
";#;#"	1234
"#;;#"	-1234
"#;#;#"	1234
";;;"	-

I would expect:
the documentation to give an example of one vs two vs three section separators

• I interpreted, based on testing, no ; to be single-section and one ; to be a two-section
• different behavior for more than 3 sections (since that is the "max")
• the two or three section separator to always exclude the negative sign
  • I interpreted this to also apply when the second separator is empty and forwards to the first separator
  • I interpreted this to not apply to "single section" (no ; present)
• an empty section to be treated as "", less the negative sign ("" is currently treated as "G")

[tannergooding]

Issue was copied from the original discussion on dotnet/coreclr#20109

CC. @jkotas, @danmosemsft, @stephentoub

[tannergooding]

@jkotas, @stephentoub.

I'd appreciate some input on how you feel this should be addressed, either changing the behavior to better match the documentation or updating the documentation to match the behavior.

[jkotas]

I assume that we have these corner cases covered by tests, so that we do not change the behavior by accident. Is that correct?

I do not see anything to fix in the product. None of the examples in your table look obviously wrong to me.

The examples in https://docs.microsoft.com/en-us/dotnet/standard/base-types/custom-numeric-format-strings#the--section-separator make it clear how these format specifiers are meant to be used. I do not think it is important for the documentation to describe the behavior in corner cases. The documentation is not meant to be a detailed spec. Do you believe that there is anything missing in the documentation that prevents our customers from using this successfully?

[tannergooding]

I assume that we have these corner cases covered by tests, so that we do not change the behavior by accident

Not that I can see, actually and changing the behavior locally did not cause any tests to fail.

Do you believe that there is anything missing in the documentation that prevents our customers from using this successfully?

Yes. I believe the documentation and implementation aren't lining up. For example, it specifies that:

However, ";" causes either nothing or - to be printed (depending on if positive or negative input), which doesn't match the behavior for "one section"
Likewise, it says that if the second section is empty, it should use the format specifier from the first section, but if you compare "#;" vs "#;#", the behaviors are not the same for negative inputs.

I don't necessarily think the behavior is wrong (except for printing nothing vs just -), but I do feel the documentation doesn't correctly indicate that #; and #;# have different behaviors, which is confusing at the very least

[tannergooding]

Basically, I would expect each section to build on the previous. So the logic behind things is clear/consistent.
But that isn't the case, and you can get drastically different behaviors where you otherwise might not expect it.

[jkotas]

Not that I can see, actually and changing the behavior locally did not cause any tests to fail.

That would be useful to fix.

I would expect each section to build on the previous

Feel free to update the doc. Keep in mind the target audience - these format strings are likely going be used by people used to Excel formatting.

[dotnet-policy-service]

Due to lack of recent activity, this issue has been marked as a candidate for backlog cleanup. It will be closed if no further activity occurs within 14 more days. Any new comment (by anyone, not necessarily the author) will undo this process.

This process is part of our issue cleanup automation.

[dotnet-policy-service]

This issue will now be closed since it had been marked no-recent-activity but received no further activity in the past 14 days. It is still possible to reopen or comment on the issue, but please note that the issue will be locked if it remains inactive for another 30 days.