EXPath Binary : copy-edits and minor enhancements #1750
Description
Suggested minor enhancements:
- Allow underscores and whitespace in strings of binary, octal, or hex digits supplied as strings.
- Use type
xs:unsignedByterather than xs:integer for octet values - Use an enum type for params like "little-endian".
The following are some suggested copy-edits:
Abstract para 4 - link to XQuery 4.1. The last sentence of the para ("The signatures and summaries of functions defined in this document...") makes no sense.
1.1 para 1, twice, ".)" should be ").".
1.2 Mention that the coercion rules in 4.0 mean that wherever a function accepts xs:base64Binary, it also accepts xs:hexBinary (but we've changed the signature to allow either, anyway).
para 2. " if the result return"?
The Note is ineleganty worded.
1.3 I guess we should integrate the test suite into QT4.
1.5 para 2 "In accordance with current practice" eh?
2.1 Example would benefit from reformatting.
2.2 Example, similarly. Could use underscores in the long integers. "and the examples from above reverse"??
-
"fn:fn:binary-resource" does not yet exist and is triple-barrelled.
-
Avoid "apologetic quotes" in 'constants'. And elsewhere. If it doesn't work as plain English without quotes, then it needs to be a defined term.
4.1 and throughout, in Examples, use the F&O rendition rather than the right arrow. Also, add these functions to the example checking mechanism.
4.1 Notes, be more precise than "similarly". Define formal equivalent. Non-editorial enhancement: allow underscores in the string.
4.2 There must be a more elegant way of saying "(8-wise) (ASCII) binary digits ([01])". Allow underscores.
4.2 "a xs:base64Binary with no embedded data" - use the term "zero-length".
4.3 similarly. Allow underscores.
Function properties: I think all these functions are pure functions so it's a waste of space to say this explicitly for each function.
4.4, 4.5 Use xs:unsignedByte to represent octets now that we have implicit downcasting. (Changes error code [[bin:octet-out-of-range]to XPTY0004).
5.6 "blank octets"?
7.1.2 "or assumed to be represented"
7.1.3 "Care should be taken" - what does this mean?
"Positive and negative infinities are supported" - who or what is doing the supporting?
Use underscore rather than space as separators between digits.
'quiet' NaN - avoid apologetic quotes.
7.4 - I find the note regarding signed/unsigned integers very confusing.
8.1: "bitwise or" - avoid apologetic quotes. For these three functions we should say what they do rather than assuming the reader will guess from the names. bin:shift could do with more precision. Perhaps the functions could be explained more formally by a mapping from a binary value to a sequence of booleans, then for example bin:and becomes something like for-each-pair(op:from-bits($a), op:from-bits($b), op('and') ) => op:to-bits().
8.5: avoid the notation |$by| for absolute value. Not all of us remember our schooldays. (And when I was at school, by meant b × y, and $ meant dollars.)