Document terms and units in `DataSize.parse()`

[maikwodarz]

org.springframework.util.unit.DataSize.parse(String value)

does not parse KB and MB as described in java doc. In fact it parses KiB and MiB according [IEC 80000-13]

Currently the comment is:

Obtain a DataSize from a text string such as 12MB using DataUnit.BYTES if no unit is specified. 

Examples: 
 "12KB" -- parses as "12 kilobytes"
 "5MB"  -- parses as "5 megabytes"
 "20"   -- parses as "20 bytes"

But that comment is wrong. It parses 12KB to 12288 bytes. This are not 12 KB. This are 12 KiB.

IEC 80000-13 defines:

1 KiB = 1024 bytes
1MiB = 1024KiB


1KB = 1000 bytes
1MB = 1000 KB

Please clarify the documentation for the Parse method to avoid confusion for developers and minimize the risk of errors. Note: The confusion could be avoided in the class documentation. It explains what KB and MB mean (regardless of the fact that this is not IEC-compliant). However, there is no reference to this documentation. I also suggest making a correction in the class documentation.

[sbrannen]

Related Issues

• Fix DataSize class according to ISO/IEC 80000 #23682
• Clarify units handling in DataSize javadoc  #23697
• DataSize bytes is acutally bibytes for method toKilobytes and above #35184

[sbrannen]

As I see it, this is effectively a continuation of #23697, where we documented the terms and units in DataSize and DataUnit in the class-level Javadoc.

Thus, for this issue we will improve the documentation for DataSize.parse().

[sbrannen]

FWIW, if you read the class-level Javadoc for DataSize as well as the Javadoc for DataSize.parse(), you can infer that 12KB = 12 * 1KB = 12 * 1024 bytes = 12288 bytes.

[sbrannen]

@mykola-yefremov, as you can see, this issue is already assigned to me.

Thus, there is no need for a PR.

[mykola-yefremov]

Thanks for letting me know. I won’t submit a PR for it.