This document defines an API for XPath 4.0 to handle the manipulation of binary data. It defines extension functions to process data from, and generate data for, binary resources, including extracting subparts, searching, basic binary operations and conversion between binary and structured forms of XDM numbers and strings.
The document is an update of the original
The principal semantic alteration is use of functional argument defaults available in XPath 4.0.
These functions are defined for use in
A summary of changes since published version 1.0 is provided
at
This version of the specification is work in progress. It is produced by the QT4
Working Group, officially the W3C XSLT 4.0 Extensions Community Group. Individual
functions specified in the document may be at different stages of review, reflected
in their
The publications of this community group
The purpose of this document is to define functions to manipulate binary data for
inclusion in XPath 4.0, XQuery 4.0, and XSLT 4.0. The binary data is represented by
the type xs:base64Binary as defined by
The syntax used to call these functions and operators is specified in
This document defines several classes of functions:
Functions to create constant binary values and convert between the binary forms and sequences of octets.
Functions to perform basic operations on binary values, such as joining, selecting and searching.
Functions to perform bitwise operations.
Functions to convert between binary data and numeric values.
Functions to decode or encode strings.
References to specific sections of some other specifications are indicated by
cross-document links in this document. Each such link consists of a pointer to a
specific section followed a superscript specifying the linked document. The
superscripts have the following meanings: FILE40
Error conditions are identified by a code (a QName). When such an
error condition is reached in the evaluation of an expression, a dynamic error
is thrown, with the corresponding error code (as if the standard XPath function
error() had been called).
In this specification these codes use the
http://expath.org/ns/binary namespace with a local part
in the form of a descriptive string, for example
bin:index-out-of-range. This convention is used in place of
the http://www.w3.org/2005/xqt-errors namespace and alpha-numeric local
part, e.g. err:FOCH0004 used in
Error codes are summarized in
xs:hexBinary or xs:base64Binary, but binary
function results remain of type xs:base64Binary. This should
not cause any backward incompatibilities as casting back and forth between
the two representations has been possible since at least version
2.0XML Schema, and therefore the XDM data model, defines two primitive atomic
types holding binary data: xs:base64Binary
has been chosen arbitrarily as the result type for functions that return
binary values. Where binary data is supplied as input to a function, however,
both xs:base64binary and xs:hexBinary are accepted.
xs:base64Binary or xs:hexBinary.
Conversion to and from xs:hexBinary can be performed by casting with
xs:hexBinary() and xs:base64Binary().
Internally it is likely that implementations will use the same byte array representation for both data types, and that casting will merely involve a change in the type annotation; it should not require data to be copied.
A suite of test-cases for all the functions defined in this module, in
This specification follows the general remarks on and terminology for conformance
given in
In this document, text labeled as an example or as a note is provided for explanatory purposes and is not normative.
The functions defined in this document are contained in the namespace
http://expath.org/ns/binary. The conventional
prefix for this namespace is bin.
This document uses the prefix bin to refer to this namespace.
User-written applications can choose a different prefix to refer to the
namespace, so long as it is bound to the correct URI.
Each function (or group of functions having the same name) is defined in this
specification using a standard proforma, full details of which can be found in
All the functions defined in this specification are deterministic and independent of the static and dynamic context.
All the functions described in this specification can in principle be defined
in terms of two primitives: xs:unsignedByte values (integers in the range 0 to 255).
In many cases functions are specified with reference to a formal equivalent
that defines the semantics of the function directly or indirectly in terms of these
two primitives.
Development of this specification was driven by requirements which some XML developers regularly encounter in examining or generating data which is presented in binary, or other non-textual forms. Some typical use cases include:
Getting the dimensions of an image file.
Extracting image metadata.
Processing images embedded as base64 encodings within a SOAP message.
Processing legacy text files which use different encodings in separate sections.
Generating PDF files from SVG graphical data.
As an example, the following code reads the binary form of a JPEG image file,
searches for the 'Start of Frame/DCT' segment, and unpacks the relevant binary
sections to integer-valued attributes height and width:
The result is an element such as:
The 'most-significant-first' argument could
be omitted, because it is the default. This is the numeric format used in JPEG:
for further information see
asn:) to avoid suggesting that they are part of the
supported function set.The first octet has the value 0x02 to indicate
that this is an integer.
Next, a variable-length length field to indicate the length of the payload. (This is designed to accommodate very large integers, such as those found in cryptography.)
Finally, the payload itself: the octets of the integer value in most-significant-first order.
To generate such a representation for an integer from XSLT/XPath, the following code might be used:
The function asn:int-octets returns a sequence of all the
significant octets of the integer (i.e. eliminating leading zeroes) in
most-significant order. Examples of the encoding are:
The first example requires no octets to encode zero, hence its octets are
2, 0. Both the second and third examples can be represented in
less than 128 octets (2 and 15 respectively), so length is encoded as a
single octet. The first three octets of the result for the last example,
which encodes a 900-digit integer, are: 2, 130, 1 indicating that
the data is represented by (130-128) * 256 + 1 = 513 octets and the length
required two octets to encode.
Decoding is a matter of compound use of the integer decoding function:
All numbers in ASN are 'big-endian'.
This function is the inverse of the encoding function above:
This section provides a summary of operations on binary values beyond those defined in this document.
Casting is defined:
Between xs:hexBinary and xs:base64Binary,
in either direction. Since the two types have the same value space,
conversion is lossless, and can be expected in most implementations
to have very low cost.
From xs:string to xs:hexBinary
or xs:base64Binary. The semantics correspond to the
XSD rules for validation of simple types. The two binary
types have different lexical representation, so conversion from
strings requires different input.
From xs:hexBinary
or xs:base64Binary to xs:string.
The rules are defined in
Comparison of binary values is defined using any of the value comparison
operators eq, ne, le, lt,
ge, or gt. It is therefore defined also for the
general comparison operators =, !=, <=, <,
>=, and >.
The semantics are defined in
The two types xs:hexBinary and xs:base64Binary
can be compared interchangeably.
Because binary values are ordered, sequences of binary values can be sorted
using the function xsl:sort
instruction in XSLT or the order by clause in XQuery.
Integers can be converted to a string representation using any radix
in the range 2 to 36 using the function
Conversely, strings representing an integer using any radix in the range
2 to 36 can be converted to an integer using the function
These functions do not directly involve binary values, but they can be used to convert between numbers and binary values by using a string representation as an intermediate format.
See also the functions
fn:binary-resource has been added to the list of useful
functions.This module defines no specific functions for reading and writing binary data from external resources, but other specifications provide some suitable mechanisms.
The EXPath File Module
which reads binary data from an existing file, with an optional offset and size.
which writes binary data into a new or existing file.
which appends binary data onto the end of an existing file.
The functions in this section can be used to define constant binary values or to perform simple conversions to string representations:
Constructs a binary value from a string of hexadecimal digits ([0-9A-Fa-f]*).
This function is
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.
The effect of the function is equivalent to the result of the following XPath expression, except in error cases.
$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(.
| Expression | Result |
|---|---|
bin:hex('1122_3F4E') |
|
bin:hex('122 3F4E') |
|
Constructs a binary value from a string of zeroes and ones ([01]*)
This function is
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
The effect of the function is equivalent to the result of the following XPath expression, except in error cases.
$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.
| Expression | Result |
|---|---|
bin:bin('1101_0001_1101_0101') |
|
bin:bin('1 0001 1101 0101') |
|
bin:bin(' 101 ') |
|
Constructs a binary value from a string of octal digits ([0-7]*)
This function is
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.
The effect of the function is equivalent to the result of the following XPath expression, except in error cases.
$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.
| Expression | Result |
|---|---|
bin:octal('') |
|
bin:octal('0') |
|
bin:octal('377') |
|
bin:octal('777') |
|
bin:octal('0377') |
|
bin:octal('11_223_047') |
|
xs:integer to
xs:unsignedByte. This is made possible by the more liberal
coercion rules defined in XPath 4.0.Returns binary data as a sequence of integer octets.
This function is
If $value is a
Octets are returned in sequence, as instances of
xs:unsignedByte (integers ranging from 0 to 255).
| Expression | Result |
|---|---|
bin:to-octets(bin:hex('1122AAFF') |
|
bin:to-octets(bin:hex('')) |
|
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.Converts a sequence of octets into binary data.
This function is
Octets are integers from 0 to 255.
If $values is the empty sequence, the function returns a
| Expression | Result |
|---|---|
bin:from-octets((17, 34, 170, 255)) |
|
bin:from-octets(()) |
|
find-all in the example for f:) to avoid
suggesting that it is part of the supported function set.Returns the size of a binary value, measured in octets.
This function is
Returns the number of octets in the binary value $value.
The effect of the function is equivalent to the result of the following XPath expression.
| Expression | Result |
|---|---|
bin:length(bin:hex('FFFF')) |
|
bin:length(bin:hex('')) |
|
Selects a specified range of octets from a binary value.
This function is
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.
The effect of the function is equivalent to the result of the following XPath expression, except in error cases.
$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.
| Expression: |
|
|---|---|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
This example tests whether | |
| |
Concatenates a sequence of binary values in order.
This function is
The function returns an xs:base64Binary value created by concatenating the
binary values in the sequence $values, in order.
The effect of the function is equivalent to the result of the following XPath expression.
If $values is the empty sequence, the function returns a
| Expression | Result |
|---|---|
bin:join((bin:hex('0000'), bin:hex('FFFF'), bin:hex('0000')) |
|
bin:join(()) |
|
bin:join( (1 to 4) ! bin:hex('F0') ) |
|
Inserts octets at a given point in a binary value.
This function is
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
The effect of the function is equivalent to the result of the following XPath expression, except in error cases.
$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.
| Expression | Result |
|---|---|
bin:insert-before(bin:hex('FFFF'), 1, bin:hex('00')) |
|
bin:insert-before(bin:hex('FFFF'), 0, bin:hex('00')) |
|
bin:insert-before(bin:hex('FFFF'), 2, bin:hex('00')) |
|
$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 left with $count
occurrences of $octet.
This function is
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
The effect of the function is equivalent to the result of the following XPath expression, except in error cases.
$size is
negative.
| Expression | Result |
|---|---|
bin:pad-left(bin:hex('FFFF'), 3) |
|
bin:pad-left(bin:hex('0000'), 3, 255) |
|
bin:pad-left(bin:hex(''), 8) |
|
$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.
This function is
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
The effect of the function is equivalent to the result of the following XPath expression, except in error cases.
$size is
negative.
| Expression | Result |
|---|---|
bin:pad-right(bin:hex('FFFF'), 3) |
|
bin:pad-right(bin:hex('0000'), 3, 255) |
|
bin:pad-right(bin:hex(''), 8) |
|
Returns the position of the first occurrence of $search within
$value, starting at $offset.
This function is
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.
The effect of the function is equivalent to the result of the following XPath expression, except in error cases.
$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:
| Expression | Result |
|---|---|
bin:find((bin:hex('AABBCCDD'), 0, bin:hex('DD')) |
|
bin:find((bin:hex('AABBCCDD'), 0, bin:hex('FF')) |
|
bin:find((bin:hex('AABBCCDDBBCC'), 2, bin:hex('BBCC')) |
|
bin:find((bin:hex('AABBCCDD'), 2, bin:hex('')) |
|
The functions in this section convert between binary values and text strings, by applying an encoding that maps octets to characters.
Note that encoding names such as "UTF-8"
are always compared without regard to case.
Examines a binary value that encodes a string, to determine the encoding and the start offset of the content.
This function is
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
| Expression: |
|
|---|---|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: | |
| Result: |
Decodes a binary value as a string.
This function is
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.
| Expression: |
|
|---|---|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
| Expression: |
|
| Result: |
|
The following tests whether the binary value | |
Encodes a string into a binary value using a given encoding.
This function is
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.
| Expression | Result |
|---|---|
bin:encode-string('ABC') |
|
bin:encode-string('ABC', 'UTF-16') |
|
bin:encode-string(char(0xfeff) || 'ABC', 'UTF-16LE') |
|
order parameter of relevant functions now
has an enum type rather than a string type. In consequence,
supplying an incorrect value is now a type error
(Packing and unpacking numeric values within binary data can be performed in
'most-significant-first' ('big-endian') or 'least-significant-first'
('little-endian') octet order. The default is
$order whose string value controls the
order. Least-significant-first order is indicated by any of the values
least-significant-first, little-endian or
LE. Most-significant-first order is indicated by any of the
values most-significant-first, big-endian or
BE.
The type of the order argument to the relevant function
is given as enum('least-significant-first', 'little-endian', 'LE',
'most-significant-first', 'big-endian', 'BE').
By default, functions that convert numeric values to binary use
most-significant-first ordering. This corresponds to the order
most commonly used in network protocols, and is often referred to as
Integers within binary data are represented, or assumed to be represented, as
an integral number of octets. Integers where $length is greater
than 8 octets (and thus not representable as a long) might be
expected in some situations, e.g. encryption. Whether the range of integers
is limited to ±2^63 is
When packing and unpacking floating point numbers
(xs:float and xs:double), the binary
representations are expected to correspond with those of the IEEE
single/double-precision 32/64-bit floating point types
Special float and double formats are represented in IEEE format as follows:
INF maps to
0x7f80_0000 (float), or 0x7ff0_0000_0000_0000
(double).
-INF maps to 0xff80_0000 (float),
or 0xfff0_0000_0000_0000 (double).
Negative zero maps to 0x8000_0000 (float),
or 0x8000_0000_0000_0000 (double).
NaN in the XSD and XDM type system corresponds to a
0x7fc0_0000 (float),
or 0x7ff8_0000_0000_0000 (double). These are the bit forms that
will be packed.
IEEE 0x7f80_0001 to
0x7fbf_ffff (float), or 0x7ff0_0000_0000_0001
to 0x7ff7_ffff_ffff_ffff or
0xfff0_0000_0000_0001 to 0xfff7_ffff_ffff_ffff
(double). Any such value encountered during unpacking will be replaced by a
quiet NaN. Any low-order
payload in an unpacked quiet NaN is also zeroed.
Returns the 8-octet binary representation of an xs:double value.
This function is
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
This function is
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
This function is
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.
| Expression | Result |
|---|---|
bin:pack-integer(256, 2) |
|
bin:pack-integer(256, 4) |
|
bin:pack-integer(65536, 2) |
|
bin:pack-integer(256, 2, "LE") |
|
bin:pack-integer(-1, 2) |
|
bin:pack-integer(-2, 4) |
|
bin:pack-integer(-2, 4, 'LE') |
|
Extracts an xs:double value
held in IEEE format at the given offset in a binary value.
This function is
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
This function is
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 a signed integer value represented by the $size octets starting
from $offset in the input binary value.
This function is
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
| Expression | Result |
|---|---|
bin:unpack-integer(bin:hex('0100'), 0, 2) |
|
bin:unpack-integer(bin:hex('00000100'), 0, 4) |
|
bin:unpack-integer(bin:hex('FFFF'), 0, 2) |
|
bin:unpack-integer(bin:hex('00FFFFFFFF'), 1, 4) |
|
bin:unpack-integer(bin:hex('FEFF'), 0, 2, "LE") |
|
Returns an unsigned integer value represented by the $size octets
starting from $offset in the input binary representation.
This function is
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
| Expression | Result |
|---|---|
bin:unpack-unsigned-integer(bin:hex('0100'), 0, 2) |
|
bin:unpack-unsigned-integer(bin:hex('00000100'), 0, 4) |
|
bin:unpack-unsigned-integer(bin:hex('FFFF'), 0, 2) |
|
bin:unpack-unsigned-integer(bin:hex('00FFFFFFFF'), 1, 4) |
|
bin:unpack-integer(bin:hex('FEFF'), 0, 2, "LE") |
|
Returns the bitwise OR of two binary values.
This function is
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.
The effect of the function is equivalent to the result of the following XPath expression, except in error cases.
Returns the bitwise exclusive-OR of two binary arguments.
This function is
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.
The effect of the function is equivalent to the result of the following XPath expression, except in error cases.
Returns the bitwise AND of two binary arguments.
This function is
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.
The effect of the function is equivalent to the result of the following XPath expression, except in error cases.
Returns the "bitwise not" of a binary argument.
This function is
Returns "bitwise not" applied to $value.
If the argument is the empty sequence, an empty sequence is returned.
The effect of the function is equivalent to the result of the following XPath expression, except in error cases.
Shift the bits of a binary value left or right.
This function is
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.
The effect of the function is equivalent to the result of the following XPath expression, except in error cases.
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.
| Expression: | |
|---|---|
| Result: |
The error text provided with these errors is non-normative.
The two arguments to a bitwise operation are of differing lengths.
Attempting to retrieve data outside the meaningful range of a binary data type.
Attempting to unpack a signed or unsigned integer whose length exceeds the implementation-defined maximum.
The specified encoding is invalid.
Size of binary portion, required numeric size or padding is negative.
Wrong character in binary 'numeric constructor' string.
The specified encoding is not supported.
Error in converting to/from a string.
This Appendix describes some sources of functions or operators that fall outside the scope of the function library defined in this specification. It includes both function specifications and function implementations. Inclusion of a function in this appendix does not constitute any kind of recommendation or endorsement; neither is omission from this appendix to be construed negatively. This Appendix does not attempt to give any information about licensing arrangements for these function specifications or implementations.
A number of W3C Recommendations make use of XPath, and in some cases such Recommmendations define additional functions to be made available when XPath is used in a specific host language.
Of particular interest to this specification, Comparison operators
on A function to retrieve the value of a
binary resourcexs:hexBinary and xs:base64Binary
values, defining the semantics of the eq,
ne, lt and ge operators
applied to binary data. Each returns a boolean
value.
| Function name | Availability | Notes |
|---|---|---|
|
| XPath4.0+ | Returns true if both binary values contain the same
octet sequence. |
|
| XPath4.0+ | Returns true if the first argument is less than the
second. |
|
| XPath4.0+ | Returns a resource as xs:base64Binary. |
Of particular interest to this specification, xs:base64Binary values:
| Function name | Availability | Notes |
|---|---|---|
|
| XPath4.0+ | Returns the content of a file in its Base64 representation. |
|
| XPath4.0+ | Writes a Base64 item as binary data to a file. |
|
| XPath4.0+ | Appends a Base64 item as binary data to a file. |
The function signatures of all the specified signatures now use the 'optional argument' syntax of XPath 4.0 where appropriate, rather than giving several signatures of differing arity. Other than that, no intended change to the semantics of the functions are assumed.
These changes are not highlighted in the change-marked version of the specification.
The example functions in asn:) to avoid
suggesting that they are part of the supported function set. This is in
accordance with the principle that the namespace
http://expath.org/ns/binary is reserved solely for use in
QNames for functions specified in this module.
This section summarizes the extent to which this specification is compatible with previous versions.
Version 4.0 of this function library is fully backwards compatible with version 1.0, except as noted below:
The use of optional arguments in the function signatures means that minor alterations to possible function calls, which would be invalid in 1.0, are now supported. For example:
would be invalid in 1.0, as the fourth argument $size is defined
to be of type xs:integer. It is valid for 4.0 as the empty
sequence denotes default behaviour, that is decoding all octets after
$offset
The functions
The use of the type xs:unsignedByte for octet arguments,
and of an enum type for octet order, means that invalid values
for these arguments will now result in a type error
bin namespace.
The way in which
The way in which the