Incorrect description in BIN2DEC and similar Number Representation Conversion Functions

[Mike Kaganski <mikekaganski@hotmail.com>]

Hello,

This is somewhat related to 
https://lists.oasis-open.org/archives/office-comment/202209/msg00000.html.

In ODF 1.3 [1], BIN2DEC (6.19.4) has the following problematic pieces:

> When considered as a Number, INT(X) = X.

This phrase is unclear, and likely is an attempt to "justify" incorrect 
use of "OrNumber" in the "TextOrNumber" type of X (see the mail 
mentioned above). The meaning of the "INT(X) = X" still is unclear, no 
clear indication why INT is mentioned here (does it mean that the number 
is converted to its integral part as per use of INT? Then why this 
order?), and the whole piece should be dropped.

> Semantics: Converts given binary number into decimal equivalent

The use of "decimal" is wrong here. The very use of "DEC" in the name of 
the function itself is unfortunate, and in an ideal world, it would be 
something like "BIN2NUM"; but at least the description must not imply 
some "decimal" representation of the result. The result of the function 
is *number*, period. It's up to the other parties to represent it in any 
way for display, or use in the internal (likely binary in most 
implementations!) representation for further calculations. Use of such 
incorrect terms increases user confusion, who doesn't realize the 
difference between the number and its *usual* visual representation.

> If given a Number, the digits of the number when printed as base 10 are considered the digits of the equivalently-represented binary number.

As per the discussion above and the mentioned previous mail, this piece 
should be dropped. Or at least converted to mention of respective 
implicit conversion description in the standard (6.3.5), but still even 
that would best be avoided, to not create an incorrect impression that 
passing numbers is the intended use case. Some corner case "correct" use 
of number passed to such functions would be some esoteric like "which 
numbers produce decimal representations that incidentally also happen to 
be valid binary strings".

The same considerations apply also to BIN2HEX, BIN2OCT, HEX2BIN, 
HEX2DEC, HEX2OCT, OCT2BIN, OCT2DEC, OCT2HEX.

DEC2BIN (6.19.7) has similar problems:

> Summary: Converts a decimal number to base 2

The "decimal" here is bad. It converts *a number*, period. The passed 
parameter of other types may be converted to number using the implicit 
conversion rules (6.3.5), but that is orthogonal, and the use of 
decimals in that conversion is unrelated.

> Constraints: X shall contain only decimal digits (no space or other characters), and shall contain at least one decimal digit.

This is completely misleading, creating an impression of decimal 
*string* expected here as the main argument value, which is wrong. 
Additionally, indeed it is even factually wrong, because per the 
implicit conversion rules, strings may contain non-decimal characters 
(like "1e2" being treated using E-notation as 100; "1 2/2" having the 
space and "/" characters, and being interpreted as fraction and equal to 
2; percent notation, date and time, etc. all being valid candidates to 
the mentioned implicit conversion).

> If given Text, the text is considered a decimal number representation, and may have a leading minus sign.

Similarly to the respective discussion above for BIN2DEC, this should 
better be removed or replaced with reference to implicit conversion rules.

Same considerations apply to DEC2HEX and DEC2OCT.

DECIMAL (6.19.10) has this problem:

> Summary: Converts text representing a number in a given base into a base 10 number.

Similar to above, the use of "base 10 number" here is wrong, should be 
simple "number" (the naming of the function, again, is unfortunate).

By the way, possibly all "Number" argument types should be "Integer" 
instead, to imply the respective conversion with truncation, without 
additional discussion of the conversion-to-integer rules. Interestingly, 
BASE (6.19.3) seems to do it all correctly.


[1] 
http://docs.oasis-open.org/office/OpenDocument/v1.3/OpenDocument-v1.3-part4-formula.html

--
Best regards,
Mike Kaganski