From BaseX Documentation
This XQuery Module contains functions to process binary data, including extracting subparts, searching, basic binary operations and conversion between binary and structured forms.
This module is based on the EXPath Binary Module.
[edit] Conventions
All functions and errors in this module are assigned to the http://expath.org/ns/binary
namespace, which is statically bound to the bin
prefix.
[edit] Constants and Conversions
[edit] bin:hex
Signatures
 bin:hex($in as xs:string?) as xs:base64Binary?

Summary
 Returns the binary form of the set of octets written as a sequence of (ASCII) hex digits ([09AFaf]).
$in will be effectively zeropadded 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 an xs:base64Binary with no embedded data. Byte order in the result follows (peroctet) character order in the string. If the value of $in is the empty sequence, the function returns an empty sequence.

Errors
 nonnumericcharacter : the input cannot be parsed as a hexadecimal number.

Examples
 string(bin:hex('11223F4E')) yields ESI/Tg== .
string(xs:hexBinary(bin:hex('FF'))) yields FF .

[edit] bin:bin
Signatures
 bin:bin($in as xs:string?) as xs:base64Binary?

Summary
 Returns the binary form of the set of octets written as a sequence of (8wise) (ASCII) binary digits ([01]).
$in will be effectively zeropadded from the left to generate an integral number of octets. If $in is an empty string, then the result will be an xs:base64Binary with no embedded data. Byte order in the result follows (peroctet) character order in the string. If the value of $in is the empty sequence, the function returns an empty sequence.

Errors
 nonnumericcharacter : the input cannot be parsed as a binary number.

Examples
 string(bin:bin('1101000111010101')) yields 0dU= .
string(xs:hexBinary(bin:bin('1000111010101'))) yields 11D5 .

[edit] bin:octal
Signatures
 bin:octal($in as xs:string?) as xs:base64Binary?

Summary
 Returns the binary form of the set of octets written as a sequence of (ASCII) octal digits ([07]).
$in will be effectively zeropadded from the left to generate an integral number of octets. If $in is an empty string, then the result will be an xs:base64Binary with no embedded data. Byte order in the result follows (peroctet) character order in the string. If the value of $in is the empty sequence, the function returns an empty sequence.

Errors
 nonnumericcharacter : the input cannot be parsed as an octal number.

Examples
 string(xs:hexBinary(bin:octal('11223047'))) yields 252627 .

[edit] bin:tooctets
Signatures
 bin:tooctets($in as xs:base64Binary) as xs:integer*

Summary
 Returns binary data as a sequence of octets. If $in is a zero length binary data then the empty sequence is returned. Octets are returned as integers from 0 to 255.

[edit] bin:fromoctets
Signatures
 bin:fromoctets($in as xs:integer*) as xs:base64Binary

Summary
 Converts a sequence of octets into binary data. Octets are integers from 0 to 255. If the value of $in is the empty sequence, the function returns zerosized binary data.

Errors
 octetoutofrange : one of the octets lies outside the range 0  255.

[edit] Basic Operations
[edit] bin:length
Signatures
 bin:length($in as xs:base64Binary) as xs:integer

Summary
 Returns the size of binary data in octets.

[edit] bin:part
Signatures
 bin:part($in as xs:base64Binary?, $offset as xs:integer) as xs:base64Binary?
bin:part($in as xs:base64Binary?, $offset as xs:integer, $size as xs:integer) as xs:base64Binary?

Summary
 Returns a section of binary data starting at the $offset octet. If $size is specified, 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. If the value of $in is the empty sequence, the function returns an empty sequence.

Errors
 negativesize : the specified size is negative.
indexoutofrange : the specified offset + size is out of range.

Examples
 Test whether binary data starts with binary content consistent with a PDF file:
bin:part($data, 0, 4) eq bin:hex("25504446") .

[edit] bin:join
Signatures
 bin:join($in as xs:base64Binary*) as xs:base64Binary

Summary
 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.

[edit] bin:insertbefore
Signatures
 bin:insertbefore($in as xs:base64Binary?, $offset as xs:integer, $extra as xs:base64Binary?) as xs:base64Binary?

Summary
 Returns binary data consisting sequentially of the data from $in up to 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. If the value of $in is the empty sequence, the function returns an empty sequence.

Errors
 indexoutofrange : the specified offset is out of range.

[edit] bin:padleft
Signatures
 bin:padleft($in as xs:base64Binary?, $size as xs:integer) as xs:base64Binary?
bin:padleft($in as xs:base64Binary?, $size as xs:integer, $octet as xs:integer) as xs:base64Binary?

Summary
 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 zero. If the value of $in is the empty sequence, the function returns an empty sequence.

Errors
 negativesize : the specified size is negative.
octetoutofrange : the specified octet lies outside the range 0255.

[edit] bin:padright
Signatures
 bin:padright($in as xs:base64Binary?, $size as xs:integer) as xs:base64Binary?
bin:padright($in as xs:base64Binary?, $size as xs:integer, $octet as xs:integer) as xs:base64Binary?

Summary
 Returns an xs:base64Binary created by padding the input with $size octets after the input. If $octet is specified, the padding octets each have that value, otherwise they are zero. If the value of $in is the empty sequence, the function returns an empty sequence.

Errors
 negativesize : the specified size is negative.
octetoutofrange : the specified octet lies outside the range 0255.

[edit] bin:find
Signatures
 bin:find($in as xs:base64Binary?, $offset as xs:integer, $search as xs:base64Binary) as xs:integer?

Summary
 Returns the first location of the binary search sequence in the input, or if not found, the empty sequence. The $offset and the returned location are zero based. If the value of $in is the empty sequence, the function returns an empty sequence.

Errors
 indexoutofrange : the specified offset + size is out of range.

[edit] Text Decoding and Encoding
[edit] bin:decodestring
Signatures
 bin:decodestring($in as xs:base64Binary?, $encoding as xs:string) as xs:string?
bin:decodestring($in as xs:base64Binary?, $encoding as xs:string, $offset as xs:integer) as xs:string?
bin:decodestring($in as xs:base64Binary?, $encoding as xs:string, $offset as xs:integer, $size as xs:integer) as xs:string?

Summary
 Decodes binary data as a string in a given $encoding . 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.If the value of $in is the empty sequence, the function returns an empty sequence.

Errors
 negativesize : the specified size is negative.
indexoutofrange : the specified offset + size is out of range.
unknownencoding : the specified encoding is unknown.
conversionerror : an error or malformed input occurred during decoding the string.

Examples
 Tests whether the binary data starts with binary content consistent with a PDF file:
bin:decodestring($data, 'UTF8', 0, 4) eq '%PDF' .

[edit] bin:encodestring
Signatures
 bin:encodestring($in as xs:string?, $encoding as xs:string) as xs:base64Binary?

Summary
 Encodes a string into binary data using a given $encoding . If the value of $in is the empty sequence, the function returns an empty sequence.

Errors
 unknownencoding : the specified encoding is unknown.
conversionerror : an error or malformed input occurred during encoding the string.

[edit] Packing and Unpacking of Numeric Values
The functions have an optional parameter $octetorder whose string value controls the order: Leastsignificantfirst order is indicated by any of the values leastsignificantfirst
, littleendian
, or LE
. Mostsignificantfirst order is indicated by any of the values mostsignificantfirst
, bigendian
, or BE
.
[edit] bin:packdouble
Signatures
 bin:packdouble($in as xs:double) as xs:base64Binary
bin:packdouble($in as xs:double, $octetorder as xs:string) as xs:base64Binary

Summary
 Returns the 8octet binary representation of a double value. Mostsignificantoctetfirst number representation is assumed unless the $octetorder parameter is specified.

Errors
 unknownsignificanceorder : the specified octet order is unknown.

[edit] bin:packfloat
Signatures
 bin:packfloat($in as xs:float) as xs:base64Binary
bin:packfloat($in as xs:float, $octetorder as xs:string) as xs:base64Binary

Summary
 Returns the 4octet binary representation of a float value. Mostsignificantoctetfirst number representation is assumed unless the $octetorder parameter is specified.

Errors
 unknownsignificanceorder : the specified octet order is unknown.

[edit] bin:packinteger
Signatures
 bin:packinteger($in as xs:integer, $size as xs:integer) as xs:base64Binary
bin:packinteger($in as xs:integer, $size as xs:integer, $octetorder as xs:string) as xs:base64Binary

Summary
 Returns the twoscomplement binary representation of an integer value treated as $size octets long. Any 'excess' highorder bits are discarded. Mostsignificantoctetfirst number representation is assumed unless the $octetorder parameter is specified. Specifying a $size of zero yields an empty binary data.

Errors
 unknownsignificanceorder : the specified octet order is unknown.
negativesize : the specified size is negative.

[edit] bin:unpackdouble
Signatures
 bin:unpackdouble($in as xs:base64Binary, $offset as xs:integer) as xs:double
bin:unpackdouble($in as xs:base64Binary, $offset as xs:integer, $octetorder as xs:string) as xs:double

Summary
 Extracts the double value stored at the particular offset in binary data. Mostsignificantoctetfirst number representation is assumed unless the $octetorder parameter is specified. The $offset is zero based.

Errors
 indexoutofrange : the specified offset is out of range.
unknownsignificanceorder : the specified octet order is unknown.

[edit] bin:unpackfloat
Signatures
 bin:unpackfloat($in as xs:base64Binary, $offset as xs:integer) as xs:float
bin:unpackfloat($in as xs:base64Binary, $offset as xs:integer, $octetorder as xs:string) as xs:float

Summary
 Extracts the float value stored at the particular offset in binary data. Mostsignificantoctetfirst number representation is assumed unless the $octetorder parameter is specified. The $offset is zero based.

Errors
 indexoutofrange : the specified offset + size is out of range.
unknownsignificanceorder : the specified octet order is unknown.

[edit] bin:unpackinteger
Signatures
 bin:unpackinteger($in as xs:base64Binary, $offset as xs:integer, $size as xs:integer) as xs:integer
bin:unpackinteger($in as xs:base64Binary, $offset as xs:integer, $size as xs:integer, $octetorder as xs:string) as xs:integer

Summary
 Returns a signed integer value represented by the $size octets starting from $offset in the input binary representation. Necessary sign extension is performed (i.e. the result is negative if the high order bit is '1'). Mostsignificantoctetfirst number representation is assumed unless the $octetorder parameter is specified. The $offset is zero based. Specifying a $size of zero yields the integer 0 .

Errors
 negativesize : the specified size is negative.
indexoutofrange : the specified offset + size is out of range.
unknownsignificanceorder : the specified octet order is unknown.

[edit] bin:unpackunsignedinteger
Signatures
 bin:unpackunsignedinteger($in as xs:base64Binary, $offset as xs:integer, $size as xs:integer) as xs:integer
bin:unpackunsignedinteger($in as xs:base64Binary, $offset as xs:integer, $size as xs:integer, $octetorder as xs:string) as xs:integer

Summary
 Returns an unsigned integer value represented by the $size octets starting from $offset in the input binary representation. Mostsignificantoctetfirst number representation is assumed unless the $octetorder parameter is specified. The $offset is zero based. Specifying a $size of zero yields the integer 0 .

Errors
 negativesize : the specified size is negative.
indexoutofrange : the specified offset + size is out of range.
unknownsignificanceorder : the specified octet order is unknown.

[edit] Bitwise Operations
[edit] bin:or
Signatures
 bin:or($a as xs:base64Binary?, $b as xs:base64Binary?) as xs:base64Binary?

Summary
 Returns the "bitwise or" of two binary arguments. If either argument is the empty sequence, an empty sequence is returned.

Errors
 differinglengtharguments : the input arguments are of differing length.

[edit] bin:xor
Signatures
 bin:xor($a as xs:base64Binary?, $b as xs:base64Binary?) as xs:base64Binary?

Summary
 Returns the "bitwise xor" of two binary arguments. If either argument is the empty sequence, an empty sequence is returned.

Errors
 differinglengtharguments : the input arguments are of differing length.

[edit] bin:and
Signatures
 bin:and($a as xs:base64Binary?, $b as xs:base64Binary?) as xs:base64Binary?

Summary
 Returns the "bitwise and" of two binary arguments. If either argument is the empty sequence, an empty sequence is returned.

Errors
 differinglengtharguments : the input arguments are of differing length.

[edit] bin:not
Signatures
 bin:not($in as xs:base64Binary?) as xs:base64Binary?

Summary
 Returns the "bitwise not" of a binary argument. If the argument is the empty sequence, an empty sequence is returned.

[edit] bin:shift
Signatures
 bin:shift($in as xs:base64Binary?, $by as xs:integer) as xs:base64Binary?

Summary
 Shifts bits in binary data. If $by is zero, the result is identical to $in . If $by is positive then bits are shifted to the left. Otherwise, bits are shifted to the right. If the absolute value of $by is greater than the bitlength of $in then an allzeros result is returned. 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.

[edit] Errors
Code
 Description

differinglengtharguments
 The arguments to a bitwise operation have different lengths.

indexoutofrange
 An offset value is out of range.

negativesize
 A size value is negative.

octetoutofrange
 An octet value lies outside the range 0255.

nonnumericcharacter
 Binary data cannot be parsed as number.

unknownencoding
 An encoding is not supported.

conversionerror
 An error or malformed input during converting a string.

unknownsignificanceorder
 An octetorder value is unknown.

[edit] Changelog
Introduced with Version 7.8.