Binary Functions
This 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.
Thanks to the enhanced conversion rules of XQuery 4.0, all functions that expect xs:base64Binary
can now be fed with xs:hexBinary
items.
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.
Signature | 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 [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. If $in is an empty string, then the result will be an 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. |
---|
Errors | |
---|
Examples | string(bin:hex('11223F4E')) Yields ESI/Tg== .
string(xs:hexBinary(bin:hex('FF'))) Yields FF . |
---|
Signature | bin:bin(
$in as xs:string?
) as xs:base64Binary? |
---|
Summary | 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. If $in is an empty string, then the result will be an 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. |
---|
Errors | |
---|
Examples | string(bin:bin('1101000111010101')) Yields 0dU= .
string(xs:hexBinary(bin:bin('1000111010101'))) Yields 11D5 . |
---|
Signature | 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 [0-7] . $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 an 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. |
---|
Errors | |
---|
Examples | string(xs:hexBinary(bin:octal('11223047'))) Yields 252627 . |
---|
Signature | bin:to-octets(
$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. |
---|
Signature | bin:from-octets(
$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 zero-sized binary data. |
---|
Errors | |
---|
Signature | bin:length(
$in as xs:base64Binary
) as xs:integer |
---|
Summary | Returns the size of binary data in octets. |
---|
Signature | 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 | |
---|
Examples | bin:part($data, 0, 4) eq bin:hex("25504446") Test whether binary data starts with binary content consistent with a PDF file. |
---|
Signature | 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. |
---|
Signature | bin:insert-before(
$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 | |
---|
Signature | bin:pad-left(
$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 | |
---|
Signature | bin:pad-right(
$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 | |
---|
Signature | 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 | |
---|
Signature | bin:decode-string(
$in as xs:base64Binary?,
$encoding as xs:string? := 'utf-8',
$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 | |
---|
Examples | bin:decode-string($data, 'UTF-8', 0, 4) eq '%PDF' Tests whether the binary data starts with binary content consistent with a PDF file. |
---|
Signature | bin:encode-string(
$in as xs:string?,
$encoding as xs:string? := 'utf-8'
) 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 | |
---|
The functions have an optional parameter $octet-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
.
Signature | bin:pack-double(
$in as xs:double,
$octet-order as xs:string := ()
) as xs:base64Binary |
---|
Summary | 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. |
---|
Errors | |
---|
Signature | bin:pack-float(
$in as xs:float,
$octet-order as xs:string := ()
) as xs:base64Binary |
---|
Summary | 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. |
---|
Errors | |
---|
Signature | bin:pack-integer(
$in as xs:integer,
$size as xs:integer,
$octet-order as xs:string := ()
) as xs:base64Binary |
---|
Summary | 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. Specifying a $size of zero yields an empty binary data. |
---|
Errors | |
---|
Signature | bin:unpack-double(
$in as xs:base64Binary,
$offset as xs:integer,
$octet-order as xs:string := ()
) as xs:double |
---|
Summary | Extracts the double value stored at the particular offset in binary data. Most-significant-octet-first number representation is assumed unless the $octet-order parameter is specified. The $offset is zero based. |
---|
Errors | |
---|
Signature | bin:unpack-float(
$in as xs:base64Binary,
$offset as xs:integer,
$octet-order as xs:string := ()
) as xs:float |
---|
Summary | Extracts the float value stored at the particular offset in binary data. Most-significant-octet-first number representation is assumed unless the $octet-order parameter is specified. The $offset is zero based. |
---|
Errors | |
---|
Signature | bin:unpack-integer(
$in as xs:base64Binary,
$offset as xs:integer,
$size as xs:integer,
$octet-order 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'). Most-significant-octet-first number representation is assumed unless the $octet-order parameter is specified. The $offset is zero based. Specifying a $size of zero yields the integer 0 . |
---|
Errors | |
---|
Signature | bin:unpack-unsigned-integer(
$in as xs:base64Binary,
$offset as xs:integer,
$size as xs:integer,
$octet-order 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. Most-significant-octet-first number representation is assumed unless the $octet-order parameter is specified. The $offset is zero based. Specifying a $size of zero yields the integer 0 . |
---|
Errors | |
---|
Signature | 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 | |
---|
Signature | 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 | |
---|
Signature | 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 | |
---|
Signature | 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. |
---|
Signature | 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 bit-length of $in then an all-zeros 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. |
---|
Code | Description |
---|
conversion-error | An error or malformed input during converting a string. |
differing-length-arguments | The arguments to a bitwise operation have different lengths. |
index-out-of-range | An offset value is out of range. |
negative-size | A size value is negative. |
non-numeric-character | Binary data cannot be parsed as number. |
octet-out-of-range | An octet value lies outside the range 0-255. |
unknown-encoding | An encoding is not supported. |
unknown-significance-order | An octet-order value is unknown. |
Version 7.8
⚡Generated with XQuery