Returns binary data as a sequence of integer octets.
If $value is a
Octets are returned in sequence, as instances of
xs:unsignedByte (integers ranging from 0 to 255).
The result type is changed from xs:integer to
xs:unsignedByte. This is made possible by the more liberal
coercion rules defined in XPath 4.0.
Converts a sequence of octets into binary data.
Octets are integers from 0 to 255.
If $values is the empty sequence, the function returns a
The argument type is changed from xs:integer to
xs:unsignedByte. This is made possible by the more liberal
coercion rules defined in XPath 4.0. A consequence of the change
is that supplying an out-of-range integer value is now a type error
with the standard error code XPTY0004, rather than the
custom error code bin:octet-out-of-range previously used.
Constructs a binary value from a string of hexadecimal digits ([0-9A-Fa-f]*).
If $value is the empty sequence, the function returns an empty
sequence.
Any whitespace and underscore characters are stripped from $value.
If the length of of the resulting string is an odd number, then
a single "0" digit is prepended to the value, so that it contains an
even number of hexadecimal digits.
The resulting string is then cast to type xs:hexBinary,
which is then cast to xs:base64Binary.
$value
cannot be parsed as a hexadecimal number.
The order of octets in the result follows the order of characters in the string.
If $value is an empty string, the result will be a
xs:base64Binary value.
When the input string has an even number of characters, this function delivers the same
result as the expression
xs:base64Binary(xs:hexBinary(.
The input string is now allowed to include embedded underscores and whitespace.
Constructs a binary value from a string of zeroes and ones ([01]*)
If $value is the empty sequence, the function returns an empty
sequence.
Any whitespace and underscore characters are stripped from $value.
As many zero digits ($value to make its string length a multiple of 8.
The string is then partitioned into substrings of length 8, and each such
substring B is converted to an integer in the range 0 to 255
by applying the function fn:parse-integer(B, 2).
The resulting sequence of integers is then converted to a
$value
cannot be parsed as a binary number.
The order of octets in the result follows the order of characters in the string.
If $value is an empty string, the result will be a
xs:base64Binary value.
The input string is now allowed to include embedded underscores and whitespace.
Constructs a binary value from a string of octal digits ([0-7]*)
If $value is the empty sequence, the function returns an empty
sequence.
Otherwise:
Any whitespace and underscore characters are stripped from $value.
Each octal digit in $value is replaced by its binary equivalent
("0" → "000", "1" → "001",
"2" → "010", "3" → "011",
"4" → "100",
"5" → "101", "6" → "110",
"7" → "111").
A maximum of two leading zero digits are stripped.
The resulting string
is converted to a
The order of octets in the result follows the order of characters in the string.
$value
cannot be parsed as an octal number.
The order of octets in the result follows the order of characters in the string.
If $value is a zero-length string, the result will be a
xs:base64Binary value.
The rule for padding to a whole number of octets ensures that leading zeroes are significant in determining the length of the final binary value, while also allowing a value of any length to be constructed. For example (underscores added for readability):
An input of "0" translates first to the string "000"; two
leading zeros are removed producing "0", which bin:hex("00").
An input of "155" translates to the
binary string "001_101_101". The first two zeroes
are removed, and bin:hex("6D")
An input of "355" translates to the
binary string "011_101_101". The first zero is removed,
and bin:hex("ED").
An input of "555" translates to the
string "101_101_101", which bin:hex("016D").
An input of "0155" translates to the
string "000_001_101_101". The first two zeros are
stripped giving "0_001_101_101", which bin:hex("006D").
The result of the expression bin:octal("177 177 177 177")
is the 5-octet value bin:hex("03 F9 FC FE 7F") and not (as some
users might imagine) the 4-octet value bin:hex("7F 7F 7F 7F").
To achieve the latter result, the expression $value => tokenize() =>
bin:octal() => bin:join() can be used.
The input string is now allowed to include embedded underscores and whitespace.
The way in which the value is adjusted to a whole number of octets has been clarified. The rules have been made more precise, and might not match the interpretation adopted by existing implementations.
Selects a specified range of octets from a binary value.
If the value of $value is the empty sequence, the function returns an empty
sequence.
Otherwise, the function returns a section of binary data starting
at $offset. The offset is zero-based. If
$size is present and non-empty, the size of the returned binary data is
$size octets. If $size is absent or empty,
all remaining data from $offset is returned.
The $offset is zero based.
The values of $offset and $size
It is a dynamic error if $offset + $size is larger than the
size of the binary data in $value.
$offset is
negative or $offset + $size is larger than the size of the binary data
of $value.
$size is
negative.
The function differs in several ways from
The $offset and $size are supplied
as integers, not doubles.
The $offset is zero-based, not one-based.
An error is raised if the selection goes outside the bounds of the value.
This example tests whether $data starts with binary content consistent
with a PDF file:
25504446 is the magic number for PDF files: it is the hexadecimal
representation of the result of encoding the string "%PDF"
in UTF-8 (or US-ASCII). Note that the function
Inserts octets at a given point in a binary value.
If the value of $value is the empty sequence, the function returns an empty
sequence.
If the value of $extra is the empty sequence, the function returns
$value.
Otherwise, the function returns a binary value formed
by concatenating the bin:part($value, 0, $offset), then
$extra, then bin:part($value, $offset)
$extra, and then the remaining data from $value.
The $offset is zero based, and
$offset is
negative or $offset is larger than the size of the binary data of
$value.
If $offset is zero, the result is the binary concatenation of
$extra and $value.
Returns the size of a binary value, measured in octets.
Returns the number of octets in the binary value $value.
Concatenates a sequence of binary values in order.
The function returns an xs:base64Binary value created by concatenating the
binary values in the sequence $values, in order.
If $values is the empty sequence, the function returns a
Returns a binary value created by padding $value on the left with $count
occurrences of $octet.
If the value of $value is the empty sequence, the function returns an empty
sequence.
Otherwise, the function returns a binary value consisting of
$count instances of $octet, followed by $value.
The default for $octet is zero (0).
$size
$size is
negative.
The argument type for $octet is changed from xs:integer to
xs:unsignedByte. This is made possible by the more liberal
coercion rules defined in XPath 4.0. A consequence of the change
is that supplying an out-of-range integer value is now a type error
with the standard error code XPTY0004, rather than the
custom error code bin:octet-out-of-range previously used.
Returns a binary value created by padding $value on the
right with $count occurrences of $octet.
If the value of $value is the empty sequence, the function returns an empty
sequence.
Otherwise, the function returns a binary value consisting of
$value, followed by $count instances of $octet.
The default for $octet is zero (0).
$size
$size is
negative.
The argument type for $octet is changed from xs:integer to
xs:unsignedByte. This is made possible by the more liberal
coercion rules defined in XPath 4.0. A consequence of the change
is that supplying an out-of-range integer value is now a type error
with the standard error code XPTY0004, rather than the
custom error code bin:octet-out-of-range previously used.
Returns the position of the first occurrence of $search within
$value, starting at $offset.
If the value of $value is the empty sequence, the function returns an empty
sequence.
Otherwise, the function returns the lowest value of P that is greater than
or equal to $offset,
such that bin:part($value, P, bin:length($search)) eq P.
If there is no such value (that is, if $search is not found),
the function returns the empty sequence.
If $search is $offset is returned.
The value of $offset
The $offset is zero based.
The returned location is zero based.
$offset is
negative or $offset is larger than the size of the binary data of
$value.
Finding all the matches can be accomplished with simple recursive application:
Examines a binary value that encodes a string, to determine the encoding and the start offset of the content.
The value for the encoding candidate E is
fn:upper-case($encoding), or an empty sequence if no encoding
is supplied.
The effective encoding is determined as follows:
UTF-8 if E is
UTF-8 or absent, and if the initial octets are xEF,
xBB and xBF; otherwise,
UTF-16LE if E is
UTF-16, UTF-16LE or absent, and if the initial octets are
xFF and xFE; otherwise,
UTF-16BE if E is
UTF-16, UTF-16BE or absent, and if the initial octets are
xFE and xFF; otherwise,
UTF-16BE if E is
UTF-16; otherwise,
the original value of $encoding if E is present;
otherwise,
UTF-8, or a value that results from
implementation-defined heuristics.
The effective start position is zero, unless the initial octets represent a byte order mark that has been evaluated by the above rules, in which case the effective start position is the zero-based offset (counting in octets) at which the byte order mark ends.
The function returns a record with two fields:
encoding contains the effective encoding.
offset contains the effective start position.
$encoding is
invalid or not supported by the implementation.
The function is designed to be used in conjunction with
Unlike functions such as
New in 4.0
Decodes a binary value as a string.
If the value of $value is the empty sequence, the function returns an
empty sequence.
If $offset or $size is non-empty, the effective value is
computed by invoking bin:part($value, $offset otherwise 0, $size).
Otherwise, it is $value.
The $encoding argument, if present, follows the same rules as for the
encoding attribute in an XML declaration. The values which an
implementation is UTF-8,
UTF-16, UTF-16LE, and UTF-16BE.
The effective encoding and start position is determined by invoking
$encoding.
The result of the function is a string representation of the effective value, starting at the effective offset, and decoded according to the effective encoding.
$offset is
negative or $offset + $size is larger than the size of the binary data
of $value.
$encoding is
invalid for the given input.
$size is
negative.
$encoding is
invalid or not supported by the implementation.
The following tests whether the binary value $data starts
with four octets that decode to the string "%PDF"
(which always appears at the start of a PDF file).
The revised encoding rules take byte order marks into account.
Encodes a string into a binary value using a given encoding.
If the value of $value is the empty sequence, the function returns an empty
sequence.
The $encoding argument is the name of an encoding. The values for
$encoding follow the same rules as for the
encoding attribute in an XML
declaration. The only values which every implementation is
UTF-8,
UTF-16, UTF-16BE, and UTF-16LE.
The encoding UTF-16 is interpreted as UTF-16BE (that is,
most significant byte first).
The function returns the binary value obtained by encoding the string $value using
the specified $encoding name.
If $encoding is omitted, UTF-8 encoding is assumed.
The function does not add a byte order mark to the data.
But if $value includes a byte order mark (
$encoding is
invalid or not supported by the implementation.
The handling of byte order marks has been clarified. This may differ from the interpretation adopted by existing implementations.
Returns the
The function produces a binary value containing the twos-complement
representation of $value mod math:pow(256, $size), padded on the
left to $size octets with zero bits if the value is positive,
or one bits if it is negative.
The order of octets in the result is most-significant-first unless
$order specifies otherwise.
Acceptable values for $order are described in
Specifying a $size of zero yields a
$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.
Least-significant-first byte ordering simply reverses the octets in the result.
Returns a signed integer value represented by the $size octets starting
from $offset in the input binary value.
The function produces an integer represented by the binary value
bin:part($value, $offset, $size). This is interpreted
as a twos-complement representation of a signed integer, with the most significant
octet first unless the $order option specifies otherwise.
Acceptable values for $order are described in
The values of $offset and $size
$offset is zero based.
Specifying a $size of zero yields the integer 0.
$offset is
negative or $offset + $size is larger than the size of the binary data
of $value.
$size is
negative.
$size is
too large for the implementation-defined maximum integer size.
For discussion on integer range see
Returns an unsigned integer value represented by the $size octets
starting from $offset in the input binary representation.
The function produces an integer represented by the binary value
bin:part($value, $offset, $size). This is interpreted
as a representation of an unsigned integer, with the most significant
octet first unless the $order option specifies otherwise.
Acceptable values for $order are described in
The values of $offset and $size
$offset is zero based.
Specifying a $size of zero yields the integer 0.
$offset is
negative or $offset + $size is larger than the size of the binary data
of $value.
$size is
negative.
$size is
too large for the implementation-defined maximum integer size.
For discussion on integer range see
Extracts an xs:double value
held in IEEE format at the given offset in a binary value.
Extract the $offset octet of the binary
data of $value.
Most-significant-first number representation is assumed unless the
$order parameter specifies otherwise. Acceptable values for
$order are described in
The value of $offset
The $offset is zero based.
The binary representation is expected to correspond with that of the IEEE
double-precision 64-bit floating point type
$offset is
negative or $offset + 8 (octet-length of xs:double) is
larger than the size of the binary data of $value.
Extract
Extract the $offset octet of the binary
data of $value.
Most-significant-octet-first number representation is assumed unless the
$order parameter specifies otherwise. Acceptable values for
$order are described in
The value of $offset
The $offset is zero based.
The binary representation is expected to correspond with that of the IEEE
single-precision 32-bit floating point type
$offset is
negative or $offset + 4 (octet-length of xs:float) is
larger than the size of the binary data of $value.
Returns the 8-octet binary representation of an xs:double value.
Most-significant-octet-first number representation is assumed unless the
$order parameter specifies otherwise. Acceptable values for
$order are described in
The binary representation will correspond with that of the IEEE double-precision
64-bit floating point type
Returns the 4-octet binary representation of a
Most-significant-octet-first number representation is assumed unless the
$order parameter is specified. Acceptable values for
$order are described in
The binary representation will correspond with that of the IEEE single-precision
32-bit floating point type
Returns the bitwise OR of two binary values.
If either argument is the empty sequence, an empty sequence is returned.
Otherwise, $value1 and $value2 must have the same length.
The function converts $value1 and $value2 to sequences
of bits A and B, and returns a binary value in which
the Nth bit is set to 1 if either or both of the Nth bit of A
and the Nth bit of B are 1, and is set to 0 otherwise.
Returns the bitwise exclusive-OR of two binary arguments.
If either argument is the empty sequence, an empty sequence is returned.
Otherwise, $value1 and $value2 must have the same length.
The function converts $value1 and $value2 to sequences
of bits A and B, and returns a binary value in which
the Nth bit is set to 1 if the Nth bit of A
differs from the Nth bit of B, and is set to 0 if they are
the same.
Returns the bitwise AND of two binary arguments.
If either argument is the empty sequence, an empty sequence is returned.
Otherwise, $value1 and $value2 must have the same length.
The function converts $value1 and $value2 to sequences
of bits A and B, and returns a binary value in which
the Nth bit is set to 1 if both the Nth bit of A
and the Nth bit of B are 1, and is set to 0 otherwise.
Returns the "bitwise not" of a binary argument.
Returns "bitwise not" applied to $value.
If the argument is the empty sequence, an empty sequence is returned.
Shift the bits of a binary value left or right.
If the value of $value is the empty sequence, the function returns an empty
sequence.
In other cases the length of the result is always the same as the
length of $value.
If $by is positive then bits are shifted $by times to the
left. The first $by bits are discarded, and $by
zero bits are injected at the end.
If $by is negative then bits are shifted -$by times to the
right. The last -$by bits are discarded, and -$by
zero bits are injected at the start.
If $by is zero, the result is identical to $value.
If abs($by) is greater than the bit-length of $value then an
all-zeros result, of the same length as $value, is returned.
abs($by) can be greater than 8, implying multi-byte shifts.
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.