Difference between revisions of "Binary Module"

From BaseX Documentation
Jump to navigation Jump to search
(30 intermediate revisions by 3 users not shown)
Line 5: Line 5:
 
=Conventions=
 
=Conventions=
  
All functions and errors in this module are assigned to the {{Code|http://expath.org/ns/binary}} namespace, which is statically bound to the {{Code|bin}} prefix.<br/>
+
All functions and errors in this module are assigned to the <code><nowiki>http://expath.org/ns/binary</nowiki></code> namespace, which is statically bound to the {{Code|bin}} prefix.<br/>
  
 
=Constants and Conversions=
 
=Constants and Conversions=
Line 16: Line 16:
 
|-
 
|-
 
| '''Summary'''
 
| '''Summary'''
|Returns the binary form of the set of octets written as a sequence of (ASCII) hex digits ([0-9A-Fa-f]).<br />{{Code|$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 {{Code|$in}} is an empty string, then the result will be an {{Code|xs:base64Binary}} with no embedded data.<br/>Byte order in the result follows (per-octet) character order in the string.<br/>If the value of {{Code|$in}} is the empty sequence, the function returns an empty sequence.
+
|Returns the binary form of the set of octets written as a sequence of (ASCII) hex digits ([0-9A-Fa-f]).<br/>{{Code|$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 {{Code|$in}} is an empty string, then the result will be an {{Code|xs:base64Binary}} with no embedded data. Byte order in the result follows (per-octet) character order in the string. If the value of {{Code|$in}} is the empty sequence, the function returns an empty sequence.
 
|-
 
|-
 
| '''Errors'''
 
| '''Errors'''
Line 22: Line 22:
 
|-
 
|-
 
| '''Examples'''
 
| '''Examples'''
|<code>bin:hex('11223F4E')</code> yields <code>ESI/Tg==</code>.<br/><code>xs:hexBinary(bin:hex('FF'))</code> yields <code>FF</code>.
+
|<code>string(bin:hex('11223F4E'))</code> yields <code>ESI/Tg==</code>.<br/><code>string(xs:hexBinary(bin:hex('FF')))</code> yields <code>FF</code>.
 
|}
 
|}
  
Line 32: Line 32:
 
|-
 
|-
 
| '''Summary'''
 
| '''Summary'''
|Returns the binary form of the set of octets written as a sequence of (8-wise) (ASCII) binary digits ([01]).<br/><code>$in</code> will be effectively zero-padded from the left to generate an integral number of octets. If <code>$in</code> is an empty string, then the result will be an <code>xs:base64Binary</code> with no embedded data.<br/>Byte order in the result follows (per-octet) character order in the string.<br/>If the value of <code>$in</code> is the empty sequence, the function returns an empty sequence.
+
|Returns the binary form of the set of octets written as a sequence of (8-wise) (ASCII) binary digits ([01]).<br/><code>$in</code> will be effectively zero-padded from the left to generate an integral number of octets. If <code>$in</code> is an empty string, then the result will be an <code>xs:base64Binary</code> with no embedded data. Byte order in the result follows (per-octet) character order in the string. If the value of <code>$in</code> is the empty sequence, the function returns an empty sequence.
 
|-
 
|-
 
| '''Errors'''
 
| '''Errors'''
Line 38: Line 38:
 
|-
 
|-
 
| '''Examples'''
 
| '''Examples'''
|<code>bin:bin('1101000111010101')</code> yields <code>0dU=</code>.<br/><code>xs:hexBinary(bin:bin('1000111010101'))</code> yields <code>11D5</code>.
+
|<code>string(bin:bin('1101000111010101'))</code> yields <code>0dU=</code>.<br/><code>string(xs:hexBinary(bin:bin('1000111010101')))</code> yields <code>11D5</code>.
 
|}
 
|}
  
Line 48: Line 48:
 
|-
 
|-
 
| '''Summary'''
 
| '''Summary'''
|Returns the binary form of the set of octets written as a sequence of (ASCII) octal digits ([0-7]).<br/><code>$in</code> will be effectively zero-padded from the left to generate an integral number of octets. If <code>$in</code> is an empty string, then the result will be an <code>xs:base64Binary</code> with no embedded data.<br/>Byte order in the result follows (per-octet) character order in the string.<br/>If the value of <code>$in</code> is the empty sequence, the function returns an empty sequence.
+
|Returns the binary form of the set of octets written as a sequence of (ASCII) octal digits ([0-7]).<br/><code>$in</code> will be effectively zero-padded from the left to generate an integral number of octets. If <code>$in</code> is an empty string, then the result will be an <code>xs:base64Binary</code> with no embedded data. Byte order in the result follows (per-octet) character order in the string. If the value of <code>$in</code> is the empty sequence, the function returns an empty sequence.
 
|-
 
|-
 
| '''Errors'''
 
| '''Errors'''
Line 54: Line 54:
 
|-
 
|-
 
| '''Examples'''
 
| '''Examples'''
|<code>xs:hexBinary(bin:octal('11223047'))</code> yields <code>252627</code>.
+
|<code>string(xs:hexBinary(bin:octal('11223047')))</code> yields <code>252627</code>.
 
|}
 
|}
  
Line 64: Line 64:
 
|-
 
|-
 
| '''Summary'''
 
| '''Summary'''
|Returns binary data as a sequence of octets.<br/>If <code>$in</code> is a zero length binary data then the empty sequence is returned.<br/>Octets are returned as integers from 0 to 255.
+
|Returns binary data as a sequence of octets.<br/>If <code>$in</code> is a zero length binary data then the empty sequence is returned. Octets are returned as integers from 0 to 255.
 
|}
 
|}
  
Line 74: Line 74:
 
|-
 
|-
 
| '''Summary'''
 
| '''Summary'''
|Converts a sequence of octets into binary data.<br/>Octets are integers from 0 to 255.<br/>If the value of <code>$in</code> is the empty sequence, the function returns zero-sized binary data.
+
|Converts a sequence of octets into binary data.<br/>Octets are integers from 0 to 255. If the value of <code>$in</code> is the empty sequence, the function returns zero-sized binary data.
 
|-
 
|-
 
| '''Errors'''
 
| '''Errors'''
Line 82: Line 82:
 
=Basic Operations=
 
=Basic Operations=
  
==bin:hex==
+
==bin:length==
 
{| width='100%'
 
{| width='100%'
 
|-
 
|-
Line 96: Line 96:
 
|-
 
|-
 
| width='120' | '''Signatures'''
 
| width='120' | '''Signatures'''
|{{Func|bin:part|$in as xs:base64Binary?, $offset as xs:integer|xs:base64Binary}}<br/>{{Func|bin:part|$in as xs:base64Binary?, $offset as xs:integer, $size as xs:integer|xs:base64Binary?}}
+
|{{Func|bin:part|$in as xs:base64Binary?, $offset as xs:integer|xs:base64Binary?}}<br/>{{Func|bin:part|$in as xs:base64Binary?, $offset as xs:integer, $size as xs:integer|xs:base64Binary?}}
 
|-
 
|-
 
| '''Summary'''
 
| '''Summary'''
|Returns a section of binary data starting at the {{Code|$offset}} octet.<br/>If {{Code|$size}} is specified, the size of the returned binary data is {{Code|$size}} octets. If {{Code|$size}} is absent, all remaining data from {{Code|$offset}} is returned.<br/>The {{Code|$offset}} is zero based.<br/>If the value of {{Code|$in}} is the empty sequence, the function returns an empty sequence.
+
|Returns a section of binary data starting at the {{Code|$offset}} octet.<br/>If {{Code|$size}} is specified, the size of the returned binary data is {{Code|$size}} octets. If {{Code|$size}} is absent, all remaining data from {{Code|$offset}} is returned. The {{Code|$offset}} is zero based. If the value of {{Code|$in}} is the empty sequence, the function returns an empty sequence.
 
|-
 
|-
 
| '''Errors'''
 
| '''Errors'''
|{{Error|negative-offset|#Errors}} the specified offset is negative.<br/>{{Error|negative-size|#Errors}} the specified size is negative.<br/>{{Error|offset-beyond-end|#Errors}} the specified offset + size extends beyond the binary data.
+
|{{Error|negative-size|#Errors}} the specified size is negative.<br/>{{Error|index-out-of-range|#Errors}} the specified offset + size is out of range.
 
|-
 
|-
 
| '''Examples'''
 
| '''Examples'''
Line 125: Line 125:
 
|-
 
|-
 
| '''Summary'''
 
| '''Summary'''
|Returns binary data consisting sequentially of the data from {{Code|$in}} up to and including the {{Code|$offset - 1}} octet, followed by all the data from {{Code|$extra}}, and then the remaining data from {{Code|$in}}.<br/>The {{Code|$offset}} is zero based. 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.
+
|Returns binary data consisting sequentially of the data from {{Code|$in}} up to and including the {{Code|$offset - 1}} octet, followed by all the data from {{Code|$extra}}, and then the remaining data from {{Code|$in}}.<br/>The {{Code|$offset}} is zero based. If the value of {{Code|$in}} is the empty sequence, the function returns an empty sequence.
 
|-
 
|-
 
| '''Errors'''
 
| '''Errors'''
|{{Error|negative-offset|#Errors}} the specified offset is negative.<br/>{{Error|offset-beyond-end|#Errors}} the specified offset extends beyond the binary data.
+
|{{Error|index-out-of-range|#Errors}} the specified offset is out of range.
 
|}
 
|}
  
Line 138: Line 138:
 
|-
 
|-
 
| '''Summary'''
 
| '''Summary'''
|Returns an {{Code|xs:base64Binary}} created by padding the input with {{Code|$size}} octets in front of the input. If {{Code|$octet}} is specified, the padding octets each have that value, otherwise they are zero.<br/>If the value of $in is the empty sequence, the function returns an empty sequence.
+
|Returns an {{Code|xs:base64Binary}} created by padding the input with {{Code|$size}} octets in front of the input. If {{Code|$octet}} is specified, the padding octets each have that value, otherwise they are zero.<br/>If the value of {{Code|$in}} is the empty sequence, the function returns an empty sequence.
 
|-
 
|-
 
| '''Errors'''
 
| '''Errors'''
Line 151: Line 151:
 
|-
 
|-
 
| '''Summary'''
 
| '''Summary'''
|Returns an {{Code|xs:base64Binary}} created by padding the input with {{Code|$size}} octets after the input. If {{Code|$octet}} is specified, the padding octets each have that value, otherwise they are zero.<br/>If the value of $in is the empty sequence, the function returns an empty sequence.
+
|Returns an {{Code|xs:base64Binary}} created by padding the input with {{Code|$size}} octets after the input. If {{Code|$octet}} is specified, the padding octets each have that value, otherwise they are zero.<br/>If the value of {{Code|$in}} is the empty sequence, the function returns an empty sequence.
 
|-
 
|-
 
| '''Errors'''
 
| '''Errors'''
Line 164: Line 164:
 
|-
 
|-
 
| '''Summary'''
 
| '''Summary'''
|Returns the first location of the binary search sequence in the input, or if not found, the empty sequence.<br/>The $offset and the returned location are zero based. If the value of $in is the empty sequence, the function returns an empty sequence.
+
|Returns the first location of the binary search sequence in the input, or if not found, the empty sequence.<br/>The {{Code|$offset}} and the returned location are zero based. If the value of {{Code|$in}} is the empty sequence, the function returns an empty sequence.
 
|-
 
|-
 
| '''Errors'''
 
| '''Errors'''
|{{Error|negative-offset|#Errors}} the specified offset is negative.<br/>{{Error|offset-beyond-end|#Errors}} the specified offset extends beyond the binary data.<br/>{{Error|empty-search-item|#Errors}} the specified search data is empty.
+
|{{Error|index-out-of-range|#Errors}} the specified offset + size is out of range.
 
|}
 
|}
  
Line 179: Line 179:
 
|-
 
|-
 
| '''Summary'''
 
| '''Summary'''
|Decodes binary data as a string in a given {{Code|$encoding}}.<br/>If {{Code|$offset}} and {{Code|$size}} are provided, the {{Code|$size}} octets from {{Code|$offset}} are decoded. If {{Code|$offset}} alone is provided, octets from {{Code|$offset}} to the end are decoded.If the value of $in is the empty sequence, the function returns an empty sequence.
+
|Decodes binary data as a string in a given {{Code|$encoding}}.<br/>If {{Code|$offset}} and {{Code|$size}} are provided, the {{Code|$size}} octets from {{Code|$offset}} are decoded. If {{Code|$offset}} alone is provided, octets from {{Code|$offset}} to the end are decoded.If the value of {{Code|$in}} is the empty sequence, the function returns an empty sequence.
 
|-
 
|-
 
| '''Errors'''
 
| '''Errors'''
|{{Error|negative-offset|#Errors}} the specified offset is negative.<br/>{{Error|negative-size|#Errors}} the specified size is negative.<br/>{{Error|offset-beyond-end|#Errors}} the specified offset + size extends beyond the binary data.<br/>{{Error|unknown-encoding|#Errors}} the specified encoding is unknown.<br/>{{Error|decoding-error|#Errors}} an error or malformed input occurred during decoding the string.
+
|{{Error|negative-size|#Errors}} the specified size is negative.<br/>{{Error|index-out-of-range|#Errors}} the specified offset + size is out of range.<br/>{{Error|unknown-encoding|#Errors}} the specified encoding is unknown.<br/>{{Error|conversion-error|#Errors}} an error or malformed input occurred during decoding the string.
 
|-
 
|-
 
| '''Examples'''
 
| '''Examples'''
Line 198: Line 198:
 
|-
 
|-
 
| '''Errors'''
 
| '''Errors'''
|{{Error|unknown-encoding|#Errors}} the specified encoding is unknown.<br/>{{Error|encoding-error|#Errors}} an error or malformed input occurred during encoding the string.
+
|{{Error|unknown-encoding|#Errors}} the specified encoding is unknown.<br/>{{Error|conversion-error|#Errors}} an error or malformed input occurred during encoding the string.
 
|}
 
|}
  
Line 222: Line 222:
 
|-
 
|-
 
| width='120' | '''Signatures'''
 
| width='120' | '''Signatures'''
|{{Func|bin:pack-float|$in as xs:double|xs:base64Binary}}<br/>{{Func|bin:pack-float|$in as xs:double, $octet-order as xs:string|xs:base64Binary}}
+
|{{Func|bin:pack-float|$in as xs:float|xs:base64Binary}}<br/>{{Func|bin:pack-float|$in as xs:float, $octet-order as xs:string|xs:base64Binary}}
 
|-
 
|-
 
| '''Summary'''
 
| '''Summary'''
Line 235: Line 235:
 
|-
 
|-
 
| width='120' | '''Signatures'''
 
| width='120' | '''Signatures'''
|{{Func|bin:pack-integer|$in as xs:double, $size as xs:integer|xs:base64Binary}}<br/>{{Func|bin:pack-float|$in as xs:double, $size as xs:integer, $octet-order as xs:string|xs:base64Binary}}
+
|{{Func|bin:pack-integer|$in as xs:integer, $size as xs:integer|xs:base64Binary}}<br/>{{Func|bin:pack-integer|$in as xs:integer, $size as xs:integer, $octet-order as xs:string|xs:base64Binary}}
 
|-
 
|-
 
| '''Summary'''
 
| '''Summary'''
Line 254: Line 254:
 
|-
 
|-
 
| '''Errors'''
 
| '''Errors'''
|{{Error|negative-offset|#Errors}} the specified offset is negative.<br/>{{Error|offset-beyond-end|#Errors}} the specified offset + 8 extends beyond the binary data.<br/>{{Error|unknown-significance-order|#Errors}} the specified octet order is unknown.
+
|{{Error|index-out-of-range|#Errors}} the specified offset is out of range.<br/>{{Error|unknown-significance-order|#Errors}} the specified octet order is unknown.
 
|}
 
|}
  
Line 261: Line 261:
 
|-
 
|-
 
| width='120' | '''Signatures'''
 
| width='120' | '''Signatures'''
|{{Func|bin:unpack-float|$in as xs:base64Binary, $offset as xs:integer|xs:double}}<br/>{{Func|bin:unpack-float|$in as xs:base64Binary, $offset as xs:integer, $octet-order as xs:string|xs:float}}
+
|{{Func|bin:unpack-float|$in as xs:base64Binary, $offset as xs:integer|xs:float}}<br/>{{Func|bin:unpack-float|$in as xs:base64Binary, $offset as xs:integer, $octet-order as xs:string|xs:float}}
 
|-
 
|-
 
| '''Summary'''
 
| '''Summary'''
Line 267: Line 267:
 
|-
 
|-
 
| '''Errors'''
 
| '''Errors'''
|{{Error|negative-offset|#Errors}} the specified offset is negative.<br/>{{Error|offset-beyond-end|#Errors}} the specified offset + 4 extends beyond the binary data.<br/>{{Error|unknown-significance-order|#Errors}} the specified octet order is unknown.
+
|{{Error|index-out-of-range|#Errors}} the specified offset + size is out of range.<br/>{{Error|unknown-significance-order|#Errors}} the specified octet order is unknown.
 
|}
 
|}
  
Line 274: Line 274:
 
|-
 
|-
 
| width='120' | '''Signatures'''
 
| width='120' | '''Signatures'''
|{{Func|bin:unpack-integer|$in as xs:base64Binary, $offset as xs:integer|xs:double}}<br/>{{Func|bin:unpack-integer|$in as xs:base64Binary, $offset as xs:integer, $octet-order as xs:string|xs:float}}
+
|{{Func|bin:unpack-integer|$in as xs:base64Binary, $offset as xs:integer, $size as xs:integer|xs:integer}}<br/>{{Func|bin:unpack-integer|$in as xs:base64Binary, $offset as xs:integer, $size as xs:integer, $octet-order as xs:string|xs:integer}}
 
|-
 
|-
 
| '''Summary'''
 
| '''Summary'''
Line 280: Line 280:
 
|-
 
|-
 
| '''Errors'''
 
| '''Errors'''
|{{Error|negative-offset|#Errors}} the specified offset is negative.<br/>{{Error|negative-size|#Errors}} the specified size is negative.<br/>{{Error|offset-beyond-end|#Errors}} the specified offset + 4 extends beyond the binary data.<br/>{{Error|unknown-significance-order|#Errors}} the specified octet order is unknown.
+
|{{Error|negative-size|#Errors}} the specified size is negative.<br/>{{Error|index-out-of-range|#Errors}} the specified offset + size is out of range.<br/>{{Error|unknown-significance-order|#Errors}} the specified octet order is unknown.
 
|}
 
|}
  
Line 287: Line 287:
 
|-
 
|-
 
| width='120' | '''Signatures'''
 
| width='120' | '''Signatures'''
|{{Func|bin:unpack-unsigned-integer|$in as xs:base64Binary, $offset as xs:integer|xs:double}}<br/>{{Func|bin:unpack-unsigned-integer|$in as xs:base64Binary, $offset as xs:integer, $octet-order as xs:string|xs:float}}
+
|{{Func|bin:unpack-unsigned-integer|$in as xs:base64Binary, $offset as xs:integer, $size as xs:integer|xs:integer}}<br/>{{Func|bin:unpack-unsigned-integer|$in as xs:base64Binary, $offset as xs:integer, $size as xs:integer, $octet-order as xs:string|xs:integer}}
 
|-
 
|-
 
| '''Summary'''
 
| '''Summary'''
Line 293: Line 293:
 
|-
 
|-
 
| '''Errors'''
 
| '''Errors'''
|{{Error|negative-offset|#Errors}} the specified offset is negative.<br/>{{Error|negative-size|#Errors}} the specified size is negative.<br/>{{Error|offset-beyond-end|#Errors}} the specified offset + 4 extends beyond the binary data.<br/>{{Error|unknown-significance-order|#Errors}} the specified octet order is unknown.
+
|{{Error|negative-size|#Errors}} the specified size is negative.<br/>{{Error|index-out-of-range|#Errors}} the specified offset + size is out of range.<br/>{{Error|unknown-significance-order|#Errors}} the specified octet order is unknown.
 
|}
 
|}
  
Line 354: Line 354:
 
|-
 
|-
 
| '''Summary'''
 
| '''Summary'''
|Shifts bits in binary data.<br/>If {{Code|$by}} is zero, the result is identical to {{Code|$in}}. If {{Code|$by}} is positive then bits are shifted to the left. Otherwise, bits are shifted to the right. If <code>|$by|</code> is greater than the bit-length of {{Code|$in}} then an all-zeros result is returned. The result always has the same size as {{Code|$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.
+
|Shifts bits in binary data.<br/>If {{Code|$by}} is zero, the result is identical to {{Code|$in}}. If {{Code|$by}} is positive then bits are shifted to the left. Otherwise, bits are shifted to the right. If the absolute value of <code>$by</code> is greater than the bit-length of {{Code|$in}} then an all-zeros result is returned. The result always has the same size as {{Code|$in}}. The shifting is logical: zeros are placed into discarded bits. If the value of {{Code|$in}} is the empty sequence, the function returns an empty sequence.
 
|}
 
|}
  
Line 360: Line 360:
  
 
{| class="wikitable" width="100%"
 
{| class="wikitable" width="100%"
! width="110"|Code
+
! width="240"|Code
 
|Description
 
|Description
 
|-
 
|-
Line 366: Line 366:
 
|The arguments to a bitwise operation have different lengths.
 
|The arguments to a bitwise operation have different lengths.
 
|-
 
|-
|{{Code|negative-offset}}
+
|{{Code|index-out-of-range}}
|An offset value is negative.
+
|An offset value is out of range.
|-
 
|{{Code|offset-beyond-end}}
 
|An offset value extends beyond the binary data.
 
 
|-
 
|-
 
|{{Code|negative-size}}
 
|{{Code|negative-size}}
 
|A size value is negative.
 
|A size value is negative.
|-
 
|{{Code|empty-search-item}}
 
|Binary search data is empty.
 
 
|-
 
|-
 
|{{Code|octet-out-of-range}}
 
|{{Code|octet-out-of-range}}
Line 387: Line 381:
 
|An encoding is not supported.
 
|An encoding is not supported.
 
|-
 
|-
|{{Code|decoding-error}}
+
|{{Code|conversion-error}}
|An error or malformed input during decoding a string.
+
|An error or malformed input during converting a string.
|-
 
|{{Code|decoding-error}}
 
|An error or malformed input during encoding a string.
 
 
|-
 
|-
 
|{{Code|unknown-significance-order}}
 
|{{Code|unknown-significance-order}}
Line 400: Line 391:
  
 
Introduced with Version 7.8.
 
Introduced with Version 7.8.
 
[[Category:XQuery]]
 

Revision as of 12:18, 16 September 2016

This XQuery 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.

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

Signatures 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: the input cannot be parsed as a hexadecimal number.
Examples string(bin:hex('11223F4E')) yields ESI/Tg==.
string(xs:hexBinary(bin:hex('FF'))) yields FF.

bin:bin

Signatures 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: the input cannot be parsed as a binary number.
Examples string(bin:bin('1101000111010101')) yields 0dU=.
string(xs:hexBinary(bin:bin('1000111010101'))) yields 11D5.

bin:octal

Signatures 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: the input cannot be parsed as an octal number.
Examples string(xs:hexBinary(bin:octal('11223047'))) yields 252627.

bin:to-octets

Signatures 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

Signatures 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: one of the octets lies outside the range 0 - 255.

Basic Operations

bin:length

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

bin:part

Signatures bin:part($in as xs:base64Binary?, $offset as xs:integer) as xs:base64Binary?
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 negative-size: the specified size is negative.
index-out-of-range: the specified offset + size is out of range.
Examples Test whether binary data starts with binary content consistent with a PDF file:
bin:part($data, 0, 4) eq bin:hex("25504446").

bin:join

Signatures 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

Signatures 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: the specified offset is out of range.

bin:pad-left

Signatures bin:pad-left($in as xs:base64Binary?, $size as xs:integer) as xs:base64Binary?
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: the specified size is negative.
octet-out-of-range: the specified octet lies outside the range 0-255.

bin:pad-right

Signatures bin:pad-right($in as xs:base64Binary?, $size as xs:integer) as xs:base64Binary?
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: the specified size is negative.
octet-out-of-range: the specified octet lies outside the range 0-255.

bin:find

Signatures 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: the specified offset + size is out of range.

Text Decoding and Encoding

bin:decode-string

Signatures bin:decode-string($in as xs:base64Binary?, $encoding as xs:string) as xs:string?
bin:decode-string($in as xs:base64Binary?, $encoding as xs:string, $offset as xs:integer) as xs:string?
bin:decode-string($in as xs:base64Binary?, $encoding as xs:string, $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 negative-size: the specified size is negative.
index-out-of-range: the specified offset + size is out of range.
unknown-encoding: the specified encoding is unknown.
conversion-error: an error or malformed input occurred during decoding the string.
Examples Tests whether the binary data starts with binary content consistent with a PDF file:
bin:decode-string($data, 'UTF-8', 0, 4) eq '%PDF'.

bin:encode-string

Signatures bin:encode-string($in as xs:string?, $encoding as xs:string) 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 unknown-encoding: the specified encoding is unknown.
conversion-error: an error or malformed input occurred during encoding the string.

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

Signatures bin:pack-double($in as xs:double) as xs:base64Binary
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: the specified octet order is unknown.

bin:pack-float

Signatures bin:pack-float($in as xs:float) as xs:base64Binary
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: the specified octet order is unknown.

bin:pack-integer

Signatures bin:pack-integer($in as xs:integer, $size as xs:integer) as xs:base64Binary
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 unknown-significance-order: the specified octet order is unknown.
negative-size: the specified size is negative.

bin:unpack-double

Signatures bin:unpack-double($in as xs:base64Binary, $offset as xs:integer) as xs:double
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: the specified offset is out of range.
unknown-significance-order: the specified octet order is unknown.

bin:unpack-float

Signatures bin:unpack-float($in as xs:base64Binary, $offset as xs:integer) as xs:float
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: the specified offset + size is out of range.
unknown-significance-order: the specified octet order is unknown.

bin:unpack-integer

Signatures bin:unpack-integer($in as xs:base64Binary, $offset as xs:integer, $size as xs:integer) as xs:integer
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 negative-size: the specified size is negative.
index-out-of-range: the specified offset + size is out of range.
unknown-significance-order: the specified octet order is unknown.

bin:unpack-unsigned-integer

Signatures bin:unpack-unsigned-integer($in as xs:base64Binary, $offset as xs:integer, $size as xs:integer) as xs:integer
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 negative-size: the specified size is negative.
index-out-of-range: the specified offset + size is out of range.
unknown-significance-order: the specified octet order is unknown.

Bitwise Operations

bin:or

Signatures 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 input arguments are of differing length.

bin:xor

Signatures 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 input arguments are of differing length.

bin:and

Signatures 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 input arguments are of differing length.

bin:not

Signatures 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

Signatures 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
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.
octet-out-of-range An octet value lies outside the range 0-255.
non-numeric-character Binary data cannot be parsed as number.
unknown-encoding An encoding is not supported.
conversion-error An error or malformed input during converting a string.
unknown-significance-order An octet-order value is unknown.

Changelog

Introduced with Version 7.8.