Binary Module

http://expath.org/ns/binary

This module is statically bound to the prefix "binary".

Description
Extension functions to process data from binary files, including extracting subparts, searching, basic binary operations and conversion between binary and structured forms.
Functions

binary:hex

Signature
binary:hex($in as xs:string?) as xs:string?
Description

$in will be effectively zero-padded from the left to generate an integral number of octets, i.e. an even number of hexadecimal digits. If $in is an empty string, then the result will be a xs:base64Binary with no embedded data.

Byte order in the result follows (per-octet) character order in the string.

If the value of $in is the empty sequence, the function returns an empty sequence.

back to top

binary:binary

Signature
binary:binary($in as xs:string?) as xs:string?
Description

$in will be effectively zero-padded from the left to generate an integral number of octets. If $in is an empty string, then the result will be a xs:base64Binary with no embedded data.

Byte order in the result follows (per-octet) character order in the string.

If the value of $in is the empty sequence, the function returns an empty sequence.

back to top

binary:octal

Signature
binary:octal($in as xs:string?) as xs:string?
Description

$in will be effectively zero-padded from the left to generate an integral number of octets. If $in is an empty string, then the result will be a xs:base64Binary with no embedded data.

Byte order in the result follows (per-octet) character order in the string.

If the value of $in is the empty sequence, the function returns an empty sequence.

back to top

binary:to-octets

Signature
binary:to-octets($in as xs:base64Binary) as xs:base64Binary
Description

If $in is a zero length binary data then the empty sequence is returned.

Octets are returned as integers from 0 to 255.

back to top

binary:from-octets

Signature
binary:from-octets($in as xs:integer*) as xs:integer*
Description

Octets are integers from 0 to 255.

If the value of $in is the empty sequence, the function returns zero-sized binary data.

back to top

binary:length

Signature
binary:length($in as xs:base64Binary) as xs:base64Binary
Description

Returns the size of binary data in octets.

back to top

binary:part

Signature
binary:part($in as xs:base64Binary?, $offset as xs:integer) as xs:integer
binary:part($in as xs:base64Binary?, $offset as xs:integer, $size as xs:integer) as xs:integer
Description

Returns a section of binary data starting at the $offset octet. If $size is defined, the size of the returned binary data is $size octets. If $size is absent, all remaining data from $offset is returned.

The $offset is zero based.

The values of $offset and $size must be non-negative integers.

It is a dynamic error if $offset + $size is larger than the size of the binary data in $in.

If the value of $in is the empty sequence, the function returns an empty sequence.

back to top

binary:join

Signature
binary:join($in as xs:base64Binary*) as xs:base64Binary*
Description

The function returns an xs:base64Binary created by concatenating the items in the sequence $in, in order.

If the value of $in is the empty sequence, the function returns a binary item containing no data bytes.

back to top

binary:insert-before

Signature
binary:insert-before($in as xs:base64Binary?, $offset as xs:integer, $extra as xs:base64Binary?) as xs:base64Binary?
Description

Returns binary data consisting sequentially of the data from $in upto and including the $offset - 1 octet, followed by all the data from $extra, and then the remaining data from $in.

The $offset is zero based.

The value of $offset must be a non-negative integer.

If the value of $in is the empty sequence, the function returns an empty sequence.

If the value of $extra is the empty sequence, the function returns $in.

If $offset eq 0 the result is the binary concatenation of $extra and $in, i.e. equivalent to bin:join(($extra,$in)).

back to top

binary:pad-left

Signature
binary:pad-left($in as xs:base64Binary?, $size as xs:integer) as xs:integer
binary:pad-left($in as xs:base64Binary?, $size as xs:integer, $octet as xs:integer) as xs:integer
Description

The function returns an xs:base64Binary created by padding the input with $size octets in front of the input. If $octet is specified, the padding octets each have that value, otherwise they are initialized to 0.

$size must be a non-negative integer.

If the value of $in is the empty sequence, the function returns an empty sequence.

back to top

binary:pad-right

Signature
binary:pad-right($in as xs:base64Binary?, $size as xs:integer) as xs:integer
binary:pad-right($in as xs:base64Binary?, $size as xs:integer, $octet as xs:integer) as xs:integer
Description

The function returns an xs:base64Binary created by padding the input with $size blank octets after the input. If $octet is specified, the padding octets each have that value, otherwise they are initialized to 0.

$size must be a non-negative integer.

If the value of $in is the empty sequence, the function returns an empty sequence.

back to top

binary:index-of

Signature
binary:index-of($in as xs:base64Binary?, $offset as xs:integer, $search as xs:base64Binary) as xs:base64Binary
Description

The function returns the first location of the binary search sequence in the input, or if not found, the empty sequence.

If $search is empty $offset is returned.

The value of $offset must be a non-negative integer.

The $offset is zero based.

The returned location is zero based.

If the value of $in is the empty sequence, the function returns an empty sequence.

back to top

binary:decode-string

Signature
binary:decode-string($in as xs:base64Binary?) as xs:base64Binary?
binary:decode-string($in as xs:base64Binary?, $encoding as xs:string) as xs:string
binary:decode-string($in as xs:base64Binary?, $encoding as xs:string, $offset as xs:integer) as xs:integer
binary:decode-string($in as xs:base64Binary?, $encoding as xs:string, $offset as xs:integer, $size as xs:integer) as xs:integer
Description

If $offset and $size are provided, the $size octets from $offset are decoded. If $offset alone is provided, octets from $offset to the end are decoded, otherwise the entire octet sequence is used.

The $encoding argument is the name of an encoding. The values for this attribute follow the same rules as for the encoding attribute in an XML declaration. The only values which every implementation is required to recognize are utf-8 and utf-16.

If $encoding is ommitted, utf-8 encoding is assumed.

The values of $offset and $size must be non-negative integers.

If the value of $in is the empty sequence, the function returns an empty sequence.

$offset is zero based.

back to top

binary:encode-string

Signature
binary:encode-string($in as xs:string?) as xs:string?
binary:encode-string($in as xs:string?, $encoding as xs:string) as xs:string
Description

The $encoding argument is the name of an encoding. The values for this attribute follow the same rules as for the encoding attribute in an XML declaration. The only values which every implementation is required to recognize are utf-8 and utf-16.

If $encoding is ommitted, utf-8 encoding is assumed.

If the value of $in is the empty sequence, the function returns an empty sequence.

back to top

binary:pack-double

Signature
binary:pack-double($in as xs:double) as xs:double
binary:pack-double($in as xs:double, $octet-order as xs:string) as xs:string
Description

Most-significant-octet-first number representation is assumed unless the $octet-order parameter is specified. Acceptable values for $octet-order are described in 8.1 Number 'endianness' .

The binary representation will correspond with that of the IEEE double-precision 64-bit floating point type [IEEE 754-1985]. For more details see 8.3 Representation of floating point numbers .

back to top

binary:pack-float

Signature
binary:pack-float($in as xs:float) as xs:float
binary:pack-float($in as xs:float, $octet-order as xs:string) as xs:string
Description

Most-significant-octet-first number representation is assumed unless the $octet-order parameter is specified. Acceptable values for $octet-order are described in 8.1 Number 'endianness' .

The binary representation will correspond with that of the IEEE single-precision 32-bit floating point type [IEEE 754-1985]. For more details see 8.3 Representation of floating point numbers .

back to top

binary:pack-integer

Signature
binary:pack-integer($in as xs:integer, $size as xs:integer) as xs:integer
binary:pack-integer($in as xs:integer, $size as xs:integer, $octet-order as xs:string) as xs:string
Description

Most-significant-octet-first number representation is assumed unless the $octet-order parameter is specified. Acceptable values for $octet-order are described in 8.1 Number 'endianness' .

Specifying a $size of zero yields an empty binary data.

back to top

binary:unpack-double

Signature
binary:unpack-double($in as xs:base64Binary, $offset as xs:integer) as xs:integer
binary:unpack-double($in as xs:base64Binary, $offset as xs:integer, $octet-order as xs:string) as xs:string
Description

Extract the double value stored in the 8 successive octets from the $offset octet of the binary data of $in.

Most-significant-octet-first number representation is assumed unless the $octet-order parameter is specified. Acceptable values for $octet-order are described in 8.1 Number 'endianness' .

The value of $offset must be a non-negative integer.

The $offset is zero based.

The binary representation is expected to correspond with that of the IEEE double-precision 64-bit floating point type [IEEE 754-1985]. For more details see 8.3 Representation of floating point numbers .

back to top

binary:unpack-float

Signature
binary:unpack-float($in as xs:base64Binary, $offset as xs:integer) as xs:integer
binary:unpack-float($in as xs:base64Binary, $offset as xs:integer, $octet-order as xs:string) as xs:string
Description

Extract the float value stored in the 4 successive octets from the $offset octet of the binary data of $in.

Most-significant-octet-first number representation is assumed unless the $octet-order parameter is specified. Acceptable values for $octet-order are described in 8.1 Number 'endianness' .

The value of $offset must be a non-negative integer.

The $offset is zero based.

The binary representation is expected to correspond with that of the IEEE single-precision 32-bit floating point type [IEEE 754-1985]. For more details see 8.3 Representation of floating point numbers .

back to top

binary:unpack-integer

Signature
binary:unpack-integer($in as xs:base64Binary, $offset as xs:integer, $size as xs:integer) as xs:integer
binary:unpack-integer($in as xs:base64Binary, $offset as xs:integer, $size as xs:integer, $octet-order as xs:string) as xs:string
Description

Most-significant-octet-first number representation is assumed unless the $octet-order parameter is specified. Acceptable values for $octet-order are described in 8.1 Number 'endianness' .

The values of $offset and $size must be non-negative integers.

$offset is zero based.

Specifying a $size of zero yields the integer 0.

back to top

binary:unpack-unsigned-integer

Signature
binary:unpack-unsigned-integer($in as xs:base64Binary, $offset as xs:integer, $size as xs:integer) as xs:integer
binary:unpack-unsigned-integer($in as xs:base64Binary, $offset as xs:integer, $size as xs:integer, $octet-order as xs:string) as xs:string
Description

Most-significant-octet-first number representation is assumed unless the $octet-order parameter is specified. Acceptable values for $octet-order are described in 8.1 Number 'endianness' .

The values of $offset and $size must be non-negative integers.

The $offset is zero based.

Specifying a $size of zero yields the integer 0.

back to top

binary:or

Signature
binary:or($a as xs:base64Binary?, $b as xs:base64Binary?) as xs:base64Binary?
Description

Returns "bitwise or" applied between $a and $b.

If either argument is the empty sequence, an empty sequence is returned.

back to top

binary:xor

Signature
binary:xor($a as xs:base64Binary?, $b as xs:base64Binary?) as xs:base64Binary?
Description

Returns "bitwise exclusive or" applied between $a and $b.

If either argument is the empty sequence, an empty sequence is returned.

back to top

binary:and

Signature
binary:and($a as xs:base64Binary?, $b as xs:base64Binary?) as xs:base64Binary?
Description

Returns "bitwise and" applied between $a and $b.

If either argument is the empty sequence, an empty sequence is returned.

back to top

binary:not

Signature
binary:not($in as xs:base64Binary?) as xs:base64Binary?
Description

Returns "bitwise not" applied to $in.

If the argument is the empty sequence, an empty sequence is returned.

back to top

binary:shift

Signature
binary:shift($in as xs:base64Binary?, $by as xs:integer) as xs:integer
Description

If $by is positive then bits are shifted $by times to the left.

If $by is negative then bits are shifted -$by times to the right.

If $by is zero, the result is identical to $in.

If |$by| is greater than the bit-length of $in then an all-zeros result, of the same length as $in, is returned.

|$by| can be greater than 8, implying multi-byte shifts.

The result always has the same size as $in.

The shifting is logical: zeros are placed into discarded bits.

If the value of $in is the empty sequence, the function returns an empty sequence.

back to top