Re: Final draft of Proposed Binary Module

Dear Jirka, dear John,

I finally implemented the Binary Module, and I stumbled upon some
minor issues (all the other parts of the spec. look completely fine!):

– bin:pad-left, bin:pad-right: It’s not clear to me what “blank
octets” are. Do you refer to the zero value (00)?

– bin:pad-left, bin:pad-right: The XPath expressions in the notes must
be swapped.

– bin:decode-string: typo "passed though" -> "passed through".

– bin:encode-string: [bin:unknown-encoding] needs to be added.
[bin:decoding-error] needs to be replaced with a new error code
[bin:encoding-error] (or a common code like [bin:conversion-error]
needs to be added).

– bin:shift: are values larger than 8 allowed for $by? In other words,
may a shift extend over more than one byte? If yes, queries such as
the following one would be allowed, too:

– bin:shift(bin:hex("000001"), 17) → bin:hex("020000")

– [offset-beyond-end] The descriptions of this error are a bit
inconsistent, as they sometimes refers to the last array position
($offset + $size - 1, see e.g. bin:unpack-unsigned-integer) and
sometimes to the length of the array ($offset + $size, see e.g.
bin:part). Maybe it’s better to always refer to the array length, and
remove the occurrences of "-1" and change "+7" to "+8" and "+3" to
"+4".

Last but not least, three suggestions:

– bin:decode-string, bin:encode-string: I would love to see a
1-argument-signature added with UTF-8 as default encoding, as this is
the quasi-default encoding for XML data. We are providing similar
signatures in the File and Archive Module.

– bin:find: we could accept empty search data as well, and discard the
corresponding error, this is quite common for many other related
functions (like fn:contains), and completely valid from a logical
perspective (empty search data returns $offset as result). While empty
search data may seem useless, it can be the result of other
operations, and code may get unnecessarily bloated if array length
checks needed to be added in order to avoid errors.

– [offset-beyond-end]: the error code could be renamed to a more
general designation such as "out-of-bounds", as in many cases it does
not only refer to $offset, but involves another value as well (such as
$size, or a constant).

Thanks,
Christian
___________________________

On Thu, Nov 14, 2013 at 10:49 AM, John Lumley <john@saxonica.com> wrote:
> We have pleasure in announcing what we hope is the final draft of the
> specification of the EXPath Binary module at:
>
> http://expath.org/spec/binary
>
> (A revision markup version from that published 20th September is available
> at http://expath.org/spec/binary/20131113/diff)
>
> We think that all the issues raised over the previous months have been
> addressed and the specification can now proceed towards a 'last call' and
> promotion to '1.0' status. We thank all those who have made constructive
> criticisms and assisted in beating this spec. into something we hope can be
> solid, long-lasting and useful. Other information regarding the module
> (samples, implementation notes etc.) will be published under
> http://expath.org/modules/binary/. A test suite is available and pointed to
> from the specification.
>
> All we need now is general consensus from the EXPath community that this
> specification can now be 'put to bed'.
>
> Jirka Kosek,
> John Lumley
>
> --
> John Lumley MA PhD CEng FIEE
> john@saxonica.com
> on behalf of Saxonica Ltd

Received on Saturday, 16 November 2013 13:49:41 UTC