deterministic context-independent focus-independent

Returns binary data as a sequence of integer octets.

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

Octets are returned as integers from 0 to 255.

 deterministic context-independent focus-independent

Converts a sequence of octets into binary data.

Octets are integers from 0 to 255.

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

is raised if one of the octets lies outside the range 0 – 255.

deterministic context-independent focus-independent

Returns the binary form of the set of octets written as a sequence of (ASCII) hex digits ([0-9A-Fa-f]).

$in will be effectively zero-padded from the left to generate an integral number of octets, i.e. an even number of hexadecimal digits.

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

If $in is an empty string, then the result will be a xs:base64Binary with no embedded data.

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

is raised if $in cannot be parsed as a hexadecimal number.

When the input string has an even number of characters, this function behaves similarly to the double cast xs:base64Binary(xs:hexBinary($string)).

 bin:hex('11223F4E') → "ESI/Tg==" bin:hex('1223F4E') → "ASI/Tg==" deterministic context-independent focus-independent

Returns the binary form of the set of octets written as a sequence of (8-wise) (ASCII) binary digits ([01]).

$in will be effectively zero-padded from the left to generate an integral number of octets (i.e. the number of characters in $in will be a multiple of 8).

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

If $in is an empty string, then the result will be a xs:base64Binary with no embedded data.

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

is raised if $in cannot be parsed as a binary number.

 bin:bin('1101000111010101') → "0dU=" bin:bin('1000111010101') → "EdU=" deterministic context-independent focus-independent

Returns the binary form of the set of octets written as a sequence of (ASCII) octal digits ([0-7]).

$in will be effectively zero-padded from the left to generate an integral number of octets.

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

If $in is an empty string, then the result will be a xs:base64Binary with no embedded data.

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

is raised if $in cannot be parsed as an octal number.

 bin:octal('11223047') → "JSYn" deterministic context-independent focus-independent

Returns a specified part of binary data.

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.

is raised if $offset is negative or $offset + $size is larger than the size of the binary data of $in.

is raised if $size is negative.

Note that fn:subsequence() and fn:substring() both use xs:double for offset and size – this is a legacy from XPath 1.0.

Testing whether $data variable starts with binary content consistent with a PDF file:

bin:part($data, 0, 4) eq bin:hex("25504446")

25504446 is the magic number for PDF files: it is the US-ASCII encoded hexadecimal value for %PDF. bin:encode-string can be used to convert a string to its binary representation.

 deterministic context-independent focus-independent

Inserts additional binary data at a given point in other binary data.

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

is raised if $offset is negative or $offset is larger than the size of the binary data of $in.

Note that when $offset gt 0 and $offset lt bin:size($in) the function is equivalent to:

bin:join((bin:part($in,0,$offset - 1),$extra,bin:part($in,$offset))) deterministic context-independent focus-independent

Returns the size of binary data, measured in octets.

Returns the size of binary data in octets.

 count(bin:to-octets($in)) deterministic context-independent focus-independent

Returns the binary data created by concatenating the binary data items in a sequence.

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.

 bin:from-octets($in ! bin:to-octets(.)) deterministic context-independent focus-independent

Returns the binary data created by padding $in with $size octets from the left. The padding octet values are $octet or zero if omitted.

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.

is raised if $size is negative.

is raised if $octet lies outside the range 0 – 255.

bin:join((bin:from-octets((1 to $size) ! $octet), $in)) deterministic context-independent focus-independent

Returns the binary data created by padding $in with $size blank octets from the right. The padding octet values are $octet or zero if omitted.

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.

is raised if $size is negative.

is raised if $octet lies outside the range 0 – 255.

bin:join((bin:from-octets($in,(1 to $size) ! $octet))) deterministic context-independent focus-independent

Returns the first location in $in of $search, starting at the $offset octet.

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.

is raised if $offset is negative or $offset is larger than the size of the binary data of $in.

Finding all the matches can be accomplished with simple recursive application:

]]> deterministic context-independent focus-independent

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, 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 omitted, 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.

is raised if $offset is negative or $offset + $size is larger than the size of the binary data of $in.

is raised if $size is negative.

is raised if $encoding is invalid or not supported by the implementation.

is raised if there is an error or malformed input during decoding the string. Additional information about the error may be passed through suitable error reporting mechanisms – this is implementation-dependant.

Testing whether $data variable starts with binary content consistent with a PDF file:

bin:decode-string($data, 'UTF-8', 0, 4) eq '%PDF'

The first four characters of a PDF file are '%PDF'.

 deterministic context-independent focus-independent

Encodes a string into binary data using a given encoding.

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 omitted, utf-8 encoding is assumed.

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

is raised if $encoding is invalid or not supported by the implementation.

is raised if there is an error or malformed input during encoding the string. Additional information about the error may be passed through suitable error reporting mechanisms – this is implementation-dependant.

 deterministic context-independent focus-independent

Returns the twos-complement binary representation of an integer value treated as $size octets long. Any 'excess' high-order bits are discarded.

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

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

is raised if the value $octet-order is unrecognized.

is raised if $size is negative.

If the integer being packed has a maximum precision of $size octets, then signed/unsigned versions are not necessary. If the data is considered unsigned, then the most significant bit of the bottom $size octets has a normal positive (2^(8 *$size - 1)) meaning. If it is considered to be a signed value, then the MSB and all the higher order, discarded bits will be '1' for a negative value and '0' for a positive or zero. If this function were to check the 'sizing' of the supplied integer against the packing size, then any values of MSB and the discarded higher order bits other than 'all 1' or 'all 0' would constitute an error. This function does not perform such checking.

 deterministic context-independent focus-independent

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').

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

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

$offset is zero based.

Specifying a $size of zero yields the integer 0.

is raised if $offset is negative or $offset + $size is larger than the size of the binary data of $in.

is raised if $size is negative.

is raised if the value $octet-order is unrecognized.

For discussion on integer range see .

 deterministic context-independent focus-independent

Returns an unsigned integer value represented by the $size octets starting from $offset in the input binary representation.

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

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.

is raised if $offset is negative or $offset + $size is larger than the size of the binary data of $in.

is raised if $size is negative.

is raised if the value $octet-order is unrecognized.

For discussion on integer range see .

 deterministic context-independent focus-independent

Extract double value stored at the particular offset in binary data.

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 .

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 . For more details see .

is raised if $offset is negative or $offset + 8 (octet-length of xs:double) is larger than the size of the binary data of $in.

is raised if the value $octet-order is unrecognized.

 deterministic context-independent focus-independent

Extract float value stored at the particular offset in binary data.

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 .

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 . For more details see .

is raised if $offset is negative or $offset + 4 (octet-length of xs:float) is larger than the size of the binary data of $in.

is raised if the value $octet-order is unrecognized.

 deterministic context-independent focus-independent

Returns the 8-octet binary representation of a double value.

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

The binary representation will correspond with that of the IEEE double-precision 64-bit floating point type . For more details see .

is raised if the value $octet-order is unrecognized.

 deterministic context-independent focus-independent

Returns the 4-octet binary representation of a float value.

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

The binary representation will correspond with that of the IEEE single-precision 32-bit floating point type . For more details see .

is raised if the value $octet-order is unrecognized.

 deterministic context-independent focus-independent

Returns the "bitwise or" of two binary arguments.

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

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

is raised if the input arguments are of differing length.

 deterministic context-independent focus-independent

Returns the "bitwise xor" of two binary arguments.

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

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

is raised if the input arguments are of differing length.

 deterministic context-independent focus-independent

Returns the "bitwise and" of two binary arguments.

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

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

is raised if the input arguments are of differing length.

 deterministic context-independent focus-independent

Returns the "bitwise not" of a binary argument.

Returns "bitwise not" applied to $in.

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

 deterministic context-independent focus-independent

Shift bits in binary data.

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.

Bit shifting across byte boundaries implies 'big-endian' treatment, i.e. the leftmost (high-order) bit when shifted left becomes the low-order bit of the preceding byte.

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