Difference between revisions of "Binary Module"

From BaseX Documentation
Jump to navigation Jump to search
m (move comma)
 
(47 intermediate revisions by 4 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 11: Line 11:
 
==bin:hex==
 
==bin:hex==
 
{| width='100%'
 
{| width='100%'
−
|-
+
|- valign="top"
−
| width='120' | '''Signatures'''
+
| width='120' | '''Signature'''
−
|{{Func|bin:hex|$in as xs:string?|xs:base64Binary?}}
+
|<pre>bin:hex(
−
|-
+
  $in as xs:string?
 +
) as xs:base64Binary?</pre>
 +
|- valign="top"
 
| '''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.
−
|-
+
|- valign="top"
 
| '''Errors'''
 
| '''Errors'''
 
|{{Error|non-numeric-character|#Errors}} the input cannot be parsed as a hexadecimal number.
 
|{{Error|non-numeric-character|#Errors}} the input cannot be parsed as a hexadecimal number.
−
|-
+
|- valign="top"
 
| '''Examples'''
 
| '''Examples'''
−
|<code>bin:hex('11223F4E')<code> yields <code>ESI/Tg==<code>.<br/><code>xs:hexBinary(bin:hex('FF'))<code> returns <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>.
 
|}
 
|}
  
 
==bin:bin==
 
==bin:bin==
 
{| width='100%'
 
{| width='100%'
−
|-
+
|- valign="top"
−
| width='120' | '''Signatures'''
+
| width='120' | '''Signature'''
−
|{{Func|bin:bin|$in as xs:string?|xs:base64Binary?}}
+
|<pre>bin:bin(
−
|-
+
  $in as xs:string?
 +
) as xs:base64Binary?</pre>
 +
|- valign="top"
 
| '''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.
−
|-
+
|- valign="top"
 
| '''Errors'''
 
| '''Errors'''
 
|{{Error|non-numeric-character|#Errors}} the input cannot be parsed as a binary number.
 
|{{Error|non-numeric-character|#Errors}} the input cannot be parsed as a binary number.
 +
|- valign="top"
 +
| '''Examples'''
 +
|<code>string(bin:bin('1101000111010101'))</code> yields <code>0dU=</code>.<br/><code>string(xs:hexBinary(bin:bin('1000111010101')))</code> yields <code>11D5</code>.
 
|}
 
|}
  
 
==bin:octal==
 
==bin:octal==
 
{| width='100%'
 
{| width='100%'
−
|-
+
|- valign="top"
−
| width='120' | '''Signatures'''
+
| width='120' | '''Signature'''
−
|{{Func|bin:octal|$in as xs:string?|xs:base64Binary?}}
+
|<pre>bin:octal(
−
|-
+
  $in as xs:string?
 +
) as xs:base64Binary?</pre>
 +
|- valign="top"
 
| '''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.
−
|-
+
|- valign="top"
 
| '''Errors'''
 
| '''Errors'''
 
|{{Error|non-numeric-character|#Errors}} the input cannot be parsed as an octal number.
 
|{{Error|non-numeric-character|#Errors}} the input cannot be parsed as an octal number.
 +
|- valign="top"
 +
| '''Examples'''
 +
|<code>string(xs:hexBinary(bin:octal('11223047')))</code> yields <code>252627</code>.
 
|}
 
|}
  
 
==bin:to-octets==
 
==bin:to-octets==
 
{| width='100%'
 
{| width='100%'
−
|-
+
|- valign="top"
−
| width='120' | '''Signatures'''
+
| width='120' | '''Signature'''
−
|{{Func|bin:to-octets|$in as xs:base64Binary|xs:integer*}}
+
|<pre>bin:to-octets(
−
|-
+
  $in as xs:base64Binary
 +
) as xs:integer*</pre>
 +
|- valign="top"
 
| '''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.
 
|}
 
|}
  
 
==bin:from-octets==
 
==bin:from-octets==
 
{| width='100%'
 
{| width='100%'
−
|-
+
|- valign="top"
−
| width='120' | '''Signatures'''
+
| width='120' | '''Signature'''
−
|{{Func|bin:from-octets|$in as xs:integer*|xs:base64Binary}}
+
|<pre>bin:from-octets(
−
|-
+
  $in as xs:integer*
 +
) as xs:base64Binary</pre>
 +
|- valign="top"
 
| '''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.
−
|-
+
|- valign="top"
 
| '''Errors'''
 
| '''Errors'''
 
|{{Error|octet-out-of-range|#Errors}} one of the octets lies outside the range 0 - 255.
 
|{{Error|octet-out-of-range|#Errors}} one of the octets lies outside the range 0 - 255.
 
|}
 
|}
  
−
...
+
=Basic Operations=
 +
 
 +
==bin:length==
 +
{| width='100%'
 +
|- valign="top"
 +
| width='120' | '''Signature'''
 +
|<pre>bin:length(
 +
  $in  as xs:base64Binary
 +
) as xs:integer</pre>
 +
|- valign="top"
 +
| '''Summary'''
 +
|Returns the size of binary data in octets.
 +
|}
 +
 
 +
==bin:part==
 +
{| width='100%'
 +
|- valign="top"
 +
| width='120' | '''Signature'''
 +
|<pre>bin:part(
 +
  $in      as xs:base64Binary?,
 +
  $offset  as xs:integer,
 +
  $size    as xs:integer        := ()
 +
) as xs:base64Binary?</pre>
 +
|- valign="top"
 +
| '''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. The {{Code|$offset}} is zero based. If the value of {{Code|$in}} is the empty sequence, the function returns an empty sequence.
 +
|- valign="top"
 +
| '''Errors'''
 +
|{{Error|negative-size|#Errors}} the specified size is negative.<br/>{{Error|index-out-of-range|#Errors}} the specified offset + size is out of range.
 +
|- valign="top"
 +
| '''Examples'''
 +
|Test whether binary data starts with binary content consistent with a PDF file:<br/><code>bin:part($data, 0, 4) eq bin:hex("25504446")</code>.
 +
|}
 +
 
 +
==bin:join==
 +
{| width='100%'
 +
|- valign="top"
 +
| width='120' | '''Signature'''
 +
|<pre>bin:join(
 +
  $in  as xs:base64Binary*
 +
) as xs:base64Binary</pre>
 +
|- valign="top"
 +
| '''Summary'''
 +
|Returns an {{Code|xs:base64Binary}} created by concatenating the items in the sequence {{Code|$in}}, in order. If the value of {{Code|$in}} is the empty sequence, the function returns a binary item containing no data bytes.
 +
|}
 +
 
 +
==bin:insert-before==
 +
{| width='100%'
 +
|- valign="top"
 +
| width='120' | '''Signature'''
 +
|<pre>bin:insert-before(
 +
  $in      as xs:base64Binary?,
 +
  $offset  as xs:integer,
 +
  $extra  as xs:base64Binary?
 +
) as xs:base64Binary?</pre>
 +
|- valign="top"
 +
| '''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 {{Code|$in}} is the empty sequence, the function returns an empty sequence.
 +
|- valign="top"
 +
| '''Errors'''
 +
|{{Error|index-out-of-range|#Errors}} the specified offset is out of range.
 +
|}
 +
 
 +
==bin:pad-left==
 +
{| width='100%'
 +
|- valign="top"
 +
| width='120' | '''Signature'''
 +
|<pre>bin:pad-left(
 +
  $in    as xs:base64Binary?,
 +
  $size  as xs:integer,
 +
  $octet  as xs:integer        := ()
 +
) as xs:base64Binary?</pre>
 +
|- valign="top"
 +
| '''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 {{Code|$in}} is the empty sequence, the function returns an empty sequence.
 +
|- valign="top"
 +
| '''Errors'''
 +
|{{Error|negative-size|#Errors}} the specified size is negative.<br/>{{Error|octet-out-of-range|#Errors}} the specified octet lies outside the range 0-255.
 +
|}
 +
 
 +
==bin:pad-right==
 +
{| width='100%'
 +
|- valign="top"
 +
| width='120' | '''Signature'''
 +
|<pre>bin:pad-right(
 +
  $in    as xs:base64Binary?,
 +
  $size  as xs:integer,
 +
  $octet  as xs:integer        := ()
 +
) as xs:base64Binary?</pre>
 +
|- valign="top"
 +
| '''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 {{Code|$in}} is the empty sequence, the function returns an empty sequence.
 +
|- valign="top"
 +
| '''Errors'''
 +
|{{Error|negative-size|#Errors}} the specified size is negative.<br/>{{Error|octet-out-of-range|#Errors}} the specified octet lies outside the range 0-255.
 +
|}
 +
 
 +
==bin:find==
 +
{| width='100%'
 +
|- valign="top"
 +
| width='120' | '''Signature'''
 +
|<pre>bin:find(
 +
  $in      as xs:base64Binary?,
 +
  $offset  as xs:integer,
 +
  $search  as xs:base64Binary
 +
) as xs:integer?</pre>
 +
|- valign="top"
 +
| '''Summary'''
 +
|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.
 +
|- valign="top"
 +
| '''Errors'''
 +
|{{Error|index-out-of-range|#Errors}} the specified offset + size is out of range.
 +
|}
 +
 
 +
=Text Decoding and Encoding=
 +
 
 +
==bin:decode-string==
 +
{| width='100%'
 +
|- valign="top"
 +
| width='120' | '''Signature'''
 +
|<pre>bin:decode-string(
 +
  $in        as xs:base64Binary?,
 +
  $encoding  as xs:string        := 'utf-8',
 +
  $offset    as xs:integer        := (),
 +
  $size      as xs:integer        := ()
 +
) as xs:string?</pre>
 +
|- valign="top"
 +
| '''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 {{Code|$in}} is the empty sequence, the function returns an empty sequence.
 +
|- valign="top"
 +
| '''Errors'''
 +
|{{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.
 +
|- valign="top"
 +
| '''Examples'''
 +
|Tests whether the binary data starts with binary content consistent with a PDF file:<br/><code>bin:decode-string($data, 'UTF-8', 0, 4) eq '%PDF'</code>.
 +
|}
 +
 
 +
==bin:encode-string==
 +
{| width='100%'
 +
|- valign="top"
 +
| width='120' | '''Signature'''
 +
|<pre>bin:encode-string(
 +
  $in        as xs:string?,
 +
  $encoding  as xs:string    := 'utf-8'
 +
) as xs:base64Binary?</pre>
 +
|- valign="top"
 +
| '''Summary'''
 +
|Encodes a string into binary data using a given {{Code|$encoding}}.<br/>If the value of {{Code|$in}} is the empty sequence, the function returns an empty sequence.
 +
|- valign="top"
 +
| '''Errors'''
 +
|{{Error|unknown-encoding|#Errors}} the specified encoding is unknown.<br/>{{Error|conversion-error|#Errors}} 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 {{Code|least-significant-first}}, {{Code|little-endian}}, or {{Code|LE}}. Most-significant-first order is indicated by any of the values {{Code|most-significant-first}}, {{Code|big-endian}}, or {{Code|BE}}.
 +
 
 +
==bin:pack-double==
 +
{| width='100%'
 +
|- valign="top"
 +
| width='120' | '''Signature'''
 +
|<pre>bin:pack-double(
 +
  $in          as xs:double,
 +
  $octet-order  as xs:string  := ()
 +
) as xs:base64Binary</pre>
 +
|- valign="top"
 +
| '''Summary'''
 +
|Returns the 8-octet binary representation of a double value.<br/>Most-significant-octet-first number representation is assumed unless the {{Code|$octet-order}} parameter is specified.
 +
|- valign="top"
 +
| '''Errors'''
 +
|{{Error|unknown-significance-order|#Errors}} the specified octet order is unknown.
 +
|}
 +
 
 +
==bin:pack-float==
 +
{| width='100%'
 +
|- valign="top"
 +
| width='120' | '''Signature'''
 +
|<pre>bin:pack-float(
 +
  $in          as xs:float,
 +
  $octet-order  as xs:string  := ()
 +
) as xs:base64Binary</pre>
 +
|- valign="top"
 +
| '''Summary'''
 +
|Returns the 4-octet binary representation of a float value.<br/>Most-significant-octet-first number representation is assumed unless the {{Code|$octet-order}} parameter is specified.
 +
|- valign="top"
 +
| '''Errors'''
 +
|{{Error|unknown-significance-order|#Errors}} the specified octet order is unknown.
 +
|}
 +
 
 +
==bin:pack-integer==
 +
{| width='100%'
 +
|- valign="top"
 +
| width='120' | '''Signature'''
 +
|<pre>bin:pack-integer(
 +
  $in          as xs:integer,
 +
  $size        as xs:integer,
 +
  $octet-order  as xs:string  := ()
 +
) as xs:base64Binary</pre>
 +
|- valign="top"
 +
| '''Summary'''
 +
|Returns the twos-complement binary representation of an integer value treated as {{Code|$size}} octets long. Any 'excess' high-order bits are discarded.<br/>Most-significant-octet-first number representation is assumed unless the {{Code|$octet-order}} parameter is specified. Specifying a {{Code|$size}} of zero yields an empty binary data.
 +
|- valign="top"
 +
| '''Errors'''
 +
|{{Error|unknown-significance-order|#Errors}} the specified octet order is unknown.<br/>{{Error|negative-size|#Errors}} the specified size is negative.<br/>
 +
|}
 +
 
 +
==bin:unpack-double==
 +
{| width='100%'
 +
|- valign="top"
 +
| width='120' | '''Signature'''
 +
|<pre>bin:unpack-double(
 +
  $in          as xs:base64Binary,
 +
  $offset      as xs:integer,
 +
  $octet-order  as xs:string        := ()
 +
) as xs:double</pre>
 +
|- valign="top"
 +
| '''Summary'''
 +
|Extracts the double value stored at the particular offset in binary data.<br/>Most-significant-octet-first number representation is assumed unless the {{Code|$octet-order}} parameter is specified. The {{Code|$offset}} is zero based.
 +
|- valign="top"
 +
| '''Errors'''
 +
|{{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.
 +
|}
 +
 
 +
==bin:unpack-float==
 +
{| width='100%'
 +
|- valign="top"
 +
| width='120' | '''Signature'''
 +
|<pre>bin:unpack-float(
 +
  $in          as xs:base64Binary,
 +
  $offset      as xs:integer,
 +
  $octet-order  as xs:string        := ()
 +
) as xs:float</pre>
 +
|- valign="top"
 +
| '''Summary'''
 +
|Extracts the float value stored at the particular offset in binary data.<br/>Most-significant-octet-first number representation is assumed unless the {{Code|$octet-order}} parameter is specified. The {{Code|$offset}} is zero based.
 +
|- valign="top"
 +
| '''Errors'''
 +
|{{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.
 +
|}
 +
 
 +
==bin:unpack-integer==
 +
{| width='100%'
 +
|- valign="top"
 +
| width='120' | '''Signature'''
 +
|<pre>bin:unpack-integer(
 +
  $in          as xs:base64Binary,
 +
  $offset      as xs:integer,
 +
  $size        as xs:integer,
 +
  $octet-order  as xs:string        := ()
 +
) as xs:integer</pre>
 +
|- valign="top"
 +
| '''Summary'''
 +
|Returns a signed integer value represented by the {{Code|$size}} octets starting from {{Code|$offset}} in the input binary representation. Necessary sign extension is performed (i.e. the result is negative if the high order bit is '1').<br/>Most-significant-octet-first number representation is assumed unless the {{Code|$octet-order}} parameter is specified. The {{Code|$offset}} is zero based. Specifying a {{Code|$size}} of zero yields the integer {{Code|0}}.
 +
|- valign="top"
 +
| '''Errors'''
 +
|{{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.
 +
|}
 +
 
 +
==bin:unpack-unsigned-integer==
 +
{| width='100%'
 +
|- valign="top"
 +
| width='120' | '''Signature'''
 +
|<pre>bin:unpack-unsigned-integer(
 +
  $in          as xs:base64Binary,
 +
  $offset      as xs:integer,
 +
  $size        as xs:integer,
 +
  $octet-order  as xs:string        := ()
 +
) as xs:integer</pre>
 +
|- valign="top"
 +
| '''Summary'''
 +
|Returns an unsigned integer value represented by the {{Code|$size}} octets starting from {{Code|$offset}} in the input binary representation.<br/>Most-significant-octet-first number representation is assumed unless the {{Code|$octet-order}} parameter is specified. The {{Code|$offset}} is zero based. Specifying a {{Code|$size}} of zero yields the integer {{Code|0}}.
 +
|- valign="top"
 +
| '''Errors'''
 +
|{{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.
 +
|}
 +
 
 +
=Bitwise Operations=
 +
 
 +
==bin:or==
 +
{| width='100%'
 +
|- valign="top"
 +
| width='120' | '''Signature'''
 +
|<pre>bin:or(
 +
  $a  as xs:base64Binary?,
 +
  $b  as xs:base64Binary?
 +
) as xs:base64Binary?</pre>
 +
|- valign="top"
 +
| '''Summary'''
 +
|Returns the "bitwise or" of two binary arguments.<br/>If either argument is the empty sequence, an empty sequence is returned.
 +
|- valign="top"
 +
| '''Errors'''
 +
|{{Error|differing-length-arguments|#Errors}} the input arguments are of differing length.
 +
|}
 +
 
 +
==bin:xor==
 +
{| width='100%'
 +
|- valign="top"
 +
| width='120' | '''Signature'''
 +
|<pre>bin:xor(
 +
  $a  as xs:base64Binary?,
 +
  $b  as xs:base64Binary?
 +
) as xs:base64Binary?</pre>
 +
|- valign="top"
 +
| '''Summary'''
 +
|Returns the "bitwise xor" of two binary arguments.<br/>If either argument is the empty sequence, an empty sequence is returned.
 +
|- valign="top"
 +
| '''Errors'''
 +
|{{Error|differing-length-arguments|#Errors}} the input arguments are of differing length.
 +
|}
 +
 
 +
==bin:and==
 +
{| width='100%'
 +
|- valign="top"
 +
| width='120' | '''Signature'''
 +
|<pre>bin:and(
 +
  $a  as xs:base64Binary?,
 +
  $b  as xs:base64Binary?
 +
) as xs:base64Binary?</pre>
 +
|- valign="top"
 +
| '''Summary'''
 +
|Returns the "bitwise and" of two binary arguments.<br/>If either argument is the empty sequence, an empty sequence is returned.
 +
|- valign="top"
 +
| '''Errors'''
 +
|{{Error|differing-length-arguments|#Errors}} the input arguments are of differing length.
 +
|}
 +
 
 +
==bin:not==
 +
{| width='100%'
 +
|- valign="top"
 +
| width='120' | '''Signature'''
 +
|<pre>bin:not(
 +
  $in  as xs:base64Binary?
 +
) as xs:base64Binary?</pre>
 +
|- valign="top"
 +
| '''Summary'''
 +
|Returns the "bitwise not" of a binary argument.<br/>If the argument is the empty sequence, an empty sequence is returned.
 +
|}
 +
 
 +
==bin:shift==
 +
{| width='100%'
 +
|- valign="top"
 +
| width='120' | '''Signature'''
 +
|<pre>bin:shift(
 +
  $in  as xs:base64Binary?,
 +
  $by  as xs:integer
 +
) as xs:base64Binary?</pre>
 +
|- valign="top"
 +
| '''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 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.
 +
|}
 +
 
 +
=Errors=
 +
 
 +
{| class="wikitable" width="100%"
 +
! width="240"|Code
 +
|Description
 +
|- valign="top"
 +
|{{Code|differing-length-arguments}}
 +
|The arguments to a bitwise operation have different lengths.
 +
|- valign="top"
 +
|{{Code|index-out-of-range}}
 +
|An offset value is out of range.
 +
|- valign="top"
 +
|{{Code|negative-size}}
 +
|A size value is negative.
 +
|- valign="top"
 +
|{{Code|octet-out-of-range}}
 +
|An octet value lies outside the range 0-255.
 +
|- valign="top"
 +
|{{Code|non-numeric-character}}
 +
|Binary data cannot be parsed as number.
 +
|- valign="top"
 +
|{{Code|unknown-encoding}}
 +
|An encoding is not supported.
 +
|- valign="top"
 +
|{{Code|conversion-error}}
 +
|An error or malformed input during converting a string.
 +
|- valign="top"
 +
|{{Code|unknown-significance-order}}
 +
|An octet-order value is unknown.
 +
|}
 +
 
 +
=Changelog=
 +
 
 +
Introduced with Version 7.8.

Latest revision as of 15:01, 11 September 2023

Conventions[edit]

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[edit]

bin:hex[edit]

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: 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[edit]

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: 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[edit]

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

bin:to-octets[edit]

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[edit]

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

Basic Operations[edit]

bin:length[edit]

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

bin:part[edit]

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 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[edit]

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[edit]

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

bin:pad-left[edit]

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: the specified size is negative.
octet-out-of-range: the specified octet lies outside the range 0-255.

bin:pad-right[edit]

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: the specified size is negative.
octet-out-of-range: the specified octet lies outside the range 0-255.

bin:find[edit]

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

Text Decoding and Encoding[edit]

bin:decode-string[edit]

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 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[edit]

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 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[edit]

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[edit]

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: the specified octet order is unknown.

bin:pack-float[edit]

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: the specified octet order is unknown.

bin:pack-integer[edit]

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 unknown-significance-order: the specified octet order is unknown.
negative-size: the specified size is negative.

bin:unpack-double[edit]

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: the specified offset is out of range.
unknown-significance-order: the specified octet order is unknown.

bin:unpack-float[edit]

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: the specified offset + size is out of range.
unknown-significance-order: the specified octet order is unknown.

bin:unpack-integer[edit]

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 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[edit]

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 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[edit]

bin:or[edit]

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

bin:xor[edit]

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

bin:and[edit]

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

bin:not[edit]

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[edit]

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.

Errors[edit]

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[edit]

Introduced with Version 7.8.

Retrieved from "https://old.docs.basex.org/index.php?title=Binary_Module&oldid=16628"