Main Page » XQuery » Functions » Binary Functions

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.

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.

Constants and Conversions

`bin:hex`

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

non-numeric-character Binary data cannot be parsed as number.

Examples

string(bin:hex('11223F4E'))

Yields ESI/Tg==.

string(xs:hexBinary(bin:hex('FF')))

Yields FF.

`bin:bin`

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

non-numeric-character Binary data cannot be parsed as number.

Examples

string(bin:bin('1101000111010101'))

Yields 0dU=.

string(xs:hexBinary(bin:bin('1000111010101')))

Yields 11D5.

`bin:octal`

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

non-numeric-character Binary data cannot be parsed as number.

Examples

string(xs:hexBinary(bin:octal('11223047')))

Yields 252627.

`bin:to-octets`

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.

`bin:from-octets`

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

octet-out-of-range An octet value lies outside the range 0-255.

Basic Operations

`bin:length`

Signature	bin:length( $in as xs:base64Binary ) as xs:integer
Summary	Returns the size of binary data in octets.

`bin:part`

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

`index-out-of-range`	An offset value is out of range.
`negative-size`	A size value is negative.

Examples

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

Test whether binary data starts with binary content consistent with a PDF file.

`bin:join`

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.

`bin:insert-before`

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

index-out-of-range An offset value is out of range.

`bin:pad-left`

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

`negative-size`	A size value is negative.
`octet-out-of-range`	An octet value lies outside the range 0-255.

`bin:pad-right`

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

`negative-size`	A size value is negative.
`octet-out-of-range`	An octet value lies outside the range 0-255.

`bin:find`

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

index-out-of-range An offset value is out of range.

Text Decoding and Encoding

`bin:decode-string`

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

`conversion-error`	An error or malformed input during converting a string.
`index-out-of-range`	An offset value is out of range.
`negative-size`	A size value is negative.
`unknown-encoding`	An encoding is not supported.

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.

`bin:encode-string`

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

`conversion-error`	An error or malformed input during converting a string.
`unknown-encoding`	An encoding is not supported.

Packing and Unpacking of Numeric Values

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.

`bin:pack-double`

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

unknown-significance-order An octet-order value is unknown.

`bin:pack-float`

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

unknown-significance-order An octet-order value is unknown.

`bin:pack-integer`

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

`negative-size`	A size value is negative.
`unknown-significance-order`	An octet-order value is unknown.

`bin:unpack-double`

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

`index-out-of-range`	An offset value is out of range.
`unknown-significance-order`	An octet-order value is unknown.

`bin:unpack-float`

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

`index-out-of-range`	An offset value is out of range.
`unknown-significance-order`	An octet-order value is unknown.

`bin:unpack-integer`

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

`index-out-of-range`	An offset value is out of range.
`negative-size`	A size value is negative.
`unknown-significance-order`	An octet-order value is unknown.

`bin:unpack-unsigned-integer`

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

`index-out-of-range`	An offset value is out of range.
`negative-size`	A size value is negative.
`unknown-significance-order`	An octet-order value is unknown.

Bitwise Operations

`bin:or`

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

differing-length-arguments The arguments to a bitwise operation have different lengths.

`bin:xor`

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

differing-length-arguments The arguments to a bitwise operation have different lengths.

`bin:and`

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

differing-length-arguments The arguments to a bitwise operation have different lengths.

`bin:not`

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.

`bin:shift`

Signature

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.

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.

Errors

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.

Changelog

Version 7.8

Added: New module added.

⚡Generated with XQuery