Difference between revisions of "Binary Module"

From BaseX Documentation
Jump to navigation Jump to search
m (move comma)
 
(7 intermediate revisions by 2 users not shown)
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. 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.
 
|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>string(bin:hex('11223F4E'))</code> yields <code>ESI/Tg==</code>.<br/><code>string(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 27: Line 29:
 
==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. 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.
 
|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'''
 
| '''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>.
 
|}
 
|}
  
 
==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. 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.
 
|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'''
 
| '''Examples'''
 
|<code>string(xs:hexBinary(bin:octal('11223047')))</code> yields <code>252627</code>.
 
|<code>string(xs:hexBinary(bin:octal('11223047')))</code> yields <code>252627</code>.
Line 59: Line 65:
 
==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. 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 69: Line 77:
 
==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. 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.
Line 84: Line 94:
 
==bin:length==
 
==bin:length==
 
{| width='100%'
 
{| width='100%'
−
|-
+
|- valign="top"
−
| width='120' | '''Signatures'''
+
| width='120' | '''Signature'''
−
|{{Func|bin:length|$in as xs:base64Binary|xs:integer}}
+
|<pre>bin:length(
−
|-
+
  $in as xs:base64Binary
 +
) as xs:integer</pre>
 +
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
 
|Returns the size of binary data in octets.
 
|Returns the size of binary data in octets.
Line 94: Line 106:
 
==bin:part==
 
==bin:part==
 
{| width='100%'
 
{| width='100%'
−
|-
+
|- valign="top"
−
| width='120' | '''Signatures'''
+
| width='120' | '''Signature'''
−
|{{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?}}
+
|<pre>bin:part(
−
|-
+
  $in     as xs:base64Binary?,
 +
  $offset as xs:integer,
 +
  $size   as xs:integer       := ()
 +
) as xs:base64Binary?</pre>
 +
|- valign="top"
 
| '''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. The {{Code|$offset}} is zero based. 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.
−
|-
+
|- valign="top"
 
| '''Errors'''
 
| '''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.
 
|{{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'''
 
| '''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>.
 
|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>.
Line 110: Line 126:
 
==bin:join==
 
==bin:join==
 
{| width='100%'
 
{| width='100%'
−
|-
+
|- valign="top"
−
| width='120' | '''Signatures'''
+
| width='120' | '''Signature'''
−
|{{Func|bin:join|$in as xs:base64Binary*|xs:base64Binary}}
+
|<pre>bin:join(
−
|-
+
  $in as xs:base64Binary*
 +
) as xs:base64Binary</pre>
 +
|- valign="top"
 
| '''Summary'''
 
| '''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.
 
|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.
Line 120: Line 138:
 
==bin:insert-before==
 
==bin:insert-before==
 
{| width='100%'
 
{| width='100%'
−
|-
+
|- valign="top"
−
| width='120' | '''Signatures'''
+
| width='120' | '''Signature'''
−
|{{Func|bin:insert-before|$in as xs:base64Binary?, $offset as xs:integer, $extra as xs:base64Binary?|xs:base64Binary?}}
+
|<pre>bin:insert-before(
−
|-
+
  $in     as xs:base64Binary?,
 +
  $offset as xs:integer,
 +
  $extra   as xs:base64Binary?
 +
) as xs:base64Binary?</pre>
 +
|- valign="top"
 
| '''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 {{Code|$in}} is the empty sequence, the function returns an empty sequence.
 
|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'''
 
| '''Errors'''
 
|{{Error|index-out-of-range|#Errors}} the specified offset is out of range.
 
|{{Error|index-out-of-range|#Errors}} the specified offset is out of range.
Line 133: Line 155:
 
==bin:pad-left==
 
==bin:pad-left==
 
{| width='100%'
 
{| width='100%'
−
|-
+
|- valign="top"
−
| width='120' | '''Signatures'''
+
| width='120' | '''Signature'''
−
|{{Func|bin:pad-left|$in as xs:base64Binary?, $size as xs:integer|xs:base64Binary?}}<br/>{{Func|bin:pad-left|$in as xs:base64Binary?, $size as xs:integer, $octet as xs:integer|xs:base64Binary?}}
+
|<pre>bin:pad-left(
−
|-
+
  $in     as xs:base64Binary?,
 +
  $size   as xs:integer,
 +
  $octet as xs:integer       := ()
 +
) as xs:base64Binary?</pre>
 +
|- valign="top"
 
| '''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 {{Code|$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.
−
|-
+
|- valign="top"
 
| '''Errors'''
 
| '''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.
 
|{{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.
Line 146: Line 172:
 
==bin:pad-right==
 
==bin:pad-right==
 
{| width='100%'
 
{| width='100%'
−
|-
+
|- valign="top"
−
| width='120' | '''Signatures'''
+
| width='120' | '''Signature'''
−
|{{Func|bin:pad-right|$in as xs:base64Binary?, $size as xs:integer|xs:base64Binary?}}<br/>{{Func|bin:pad-right|$in as xs:base64Binary?, $size as xs:integer, $octet as xs:integer|xs:base64Binary?}}
+
|<pre>bin:pad-right(
−
|-
+
  $in     as xs:base64Binary?,
 +
  $size   as xs:integer,
 +
  $octet as xs:integer       := ()
 +
) as xs:base64Binary?</pre>
 +
|- valign="top"
 
| '''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 {{Code|$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.
−
|-
+
|- valign="top"
 
| '''Errors'''
 
| '''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.
 
|{{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.
Line 159: Line 189:
 
==bin:find==
 
==bin:find==
 
{| width='100%'
 
{| width='100%'
−
|-
+
|- valign="top"
−
| width='120' | '''Signatures'''
+
| width='120' | '''Signature'''
−
|{{Func|bin:find|$in as xs:base64Binary?, $offset as xs:integer, $search as xs:base64Binary|xs:integer?}}
+
|<pre>bin:find(
−
|-
+
  $in     as xs:base64Binary?,
 +
  $offset as xs:integer,
 +
  $search as xs:base64Binary
 +
) as xs:integer?</pre>
 +
|- valign="top"
 
| '''Summary'''
 
| '''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.
 
|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'''
 
| '''Errors'''
 
|{{Error|index-out-of-range|#Errors}} the specified offset + size is out of range.
 
|{{Error|index-out-of-range|#Errors}} the specified offset + size is out of range.
Line 174: Line 208:
 
==bin:decode-string==
 
==bin:decode-string==
 
{| width='100%'
 
{| width='100%'
−
|-
+
|- valign="top"
−
| width='120' | '''Signatures'''
+
| width='120' | '''Signature'''
−
|{{Func|bin:decode-string|$in as xs:base64Binary?, $encoding as xs:string|xs:string?}}<br/>{{Func|bin:decode-string|$in as xs:base64Binary?, $encoding as xs:string, $offset as xs:integer|xs:string?}}<br/>{{Func|bin:decode-string|$in as xs:base64Binary?, $encoding as xs:string, $offset as xs:integer, $size as xs:integer|xs:string?}}<br/>
+
|<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'''
 
| '''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.
 
|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'''
 
| '''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.
 
|{{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'''
 
| '''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>.
 
|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>.
Line 190: Line 229:
 
==bin:encode-string==
 
==bin:encode-string==
 
{| width='100%'
 
{| width='100%'
−
|-
+
|- valign="top"
−
| width='120' | '''Signatures'''
+
| width='120' | '''Signature'''
−
|{{Func|bin:encode-string|$in as xs:string?, $encoding as xs:string|xs:base64Binary?}}
+
|<pre>bin:encode-string(
−
|-
+
  $in       as xs:string?,
 +
  $encoding as xs:string   := 'utf-8'
 +
) as xs:base64Binary?</pre>
 +
|- valign="top"
 
| '''Summary'''
 
| '''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.
 
|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'''
 
| '''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.
 
|{{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 207: Line 249:
 
==bin:pack-double==
 
==bin:pack-double==
 
{| width='100%'
 
{| width='100%'
−
|-
+
|- valign="top"
−
| width='120' | '''Signatures'''
+
| width='120' | '''Signature'''
−
|{{Func|bin:pack-double|$in as xs:double|xs:base64Binary}}<br/>{{Func|bin:pack-double|$in as xs:double, $octet-order as xs:string|xs:base64Binary}}
+
|<pre>bin:pack-double(
−
|-
+
  $in           as xs:double,
 +
  $octet-order as xs:string := ()
 +
) as xs:base64Binary</pre>
 +
|- valign="top"
 
| '''Summary'''
 
| '''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.
 
|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'''
 
| '''Errors'''
 
|{{Error|unknown-significance-order|#Errors}} the specified octet order is unknown.
 
|{{Error|unknown-significance-order|#Errors}} the specified octet order is unknown.
Line 220: Line 265:
 
==bin:pack-float==
 
==bin:pack-float==
 
{| width='100%'
 
{| width='100%'
−
|-
+
|- valign="top"
−
| width='120' | '''Signatures'''
+
| width='120' | '''Signature'''
−
|{{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}}
+
|<pre>bin:pack-float(
−
|-
+
  $in           as xs:float,
 +
  $octet-order as xs:string := ()
 +
) as xs:base64Binary</pre>
 +
|- valign="top"
 
| '''Summary'''
 
| '''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.
 
|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'''
 
| '''Errors'''
 
|{{Error|unknown-significance-order|#Errors}} the specified octet order is unknown.
 
|{{Error|unknown-significance-order|#Errors}} the specified octet order is unknown.
Line 233: Line 281:
 
==bin:pack-integer==
 
==bin:pack-integer==
 
{| width='100%'
 
{| width='100%'
−
|-
+
|- valign="top"
−
| width='120' | '''Signatures'''
+
| width='120' | '''Signature'''
−
|{{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}}
+
|<pre>bin:pack-integer(
−
|-
+
  $in           as xs:integer,
 +
  $size         as xs:integer,
 +
  $octet-order as xs:string   := ()
 +
) as xs:base64Binary</pre>
 +
|- valign="top"
 
| '''Summary'''
 
| '''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.
 
|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'''
 
| '''Errors'''
 
|{{Error|unknown-significance-order|#Errors}} the specified octet order is unknown.<br/>{{Error|negative-size|#Errors}} the specified size is negative.<br/>
 
|{{Error|unknown-significance-order|#Errors}} the specified octet order is unknown.<br/>{{Error|negative-size|#Errors}} the specified size is negative.<br/>
Line 246: Line 298:
 
==bin:unpack-double==
 
==bin:unpack-double==
 
{| width='100%'
 
{| width='100%'
−
|-
+
|- valign="top"
−
| width='120' | '''Signatures'''
+
| width='120' | '''Signature'''
−
|{{Func|bin:unpack-double|$in as xs:base64Binary, $offset as xs:integer|xs:double}}<br/>{{Func|bin:unpack-double|$in as xs:base64Binary, $offset as xs:integer, $octet-order as xs:string|xs:double}}
+
|<pre>bin:unpack-double(
−
|-
+
  $in           as xs:base64Binary,
 +
  $offset       as xs:integer,
 +
  $octet-order as xs:string       := ()
 +
) as xs:double</pre>
 +
|- valign="top"
 
| '''Summary'''
 
| '''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.
 
|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'''
 
| '''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.
 
|{{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 259: Line 315:
 
==bin:unpack-float==
 
==bin:unpack-float==
 
{| width='100%'
 
{| width='100%'
−
|-
+
|- valign="top"
−
| width='120' | '''Signatures'''
+
| width='120' | '''Signature'''
−
|{{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}}
+
|<pre>bin:unpack-float(
−
|-
+
  $in           as xs:base64Binary,
 +
  $offset       as xs:integer,
 +
  $octet-order as xs:string       := ()
 +
) as xs:float</pre>
 +
|- valign="top"
 
| '''Summary'''
 
| '''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.
 
|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'''
 
| '''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.
 
|{{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 272: Line 332:
 
==bin:unpack-integer==
 
==bin:unpack-integer==
 
{| width='100%'
 
{| width='100%'
−
|-
+
|- valign="top"
−
| width='120' | '''Signatures'''
+
| width='120' | '''Signature'''
−
|{{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}}
+
|<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'''
 
| '''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}}.
 
|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'''
 
| '''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.
 
|{{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 285: Line 350:
 
==bin:unpack-unsigned-integer==
 
==bin:unpack-unsigned-integer==
 
{| width='100%'
 
{| width='100%'
−
|-
+
|- valign="top"
−
| width='120' | '''Signatures'''
+
| width='120' | '''Signature'''
−
|{{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}}
+
|<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'''
 
| '''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}}.
 
|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'''
 
| '''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.
 
|{{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 300: Line 370:
 
==bin:or==
 
==bin:or==
 
{| width='100%'
 
{| width='100%'
−
|-
+
|- valign="top"
−
| width='120' | '''Signatures'''
+
| width='120' | '''Signature'''
−
|{{Func|bin:or|$a as xs:base64Binary?, $b as xs:base64Binary?|xs:base64Binary?}}
+
|<pre>bin:or(
−
|-
+
  $a as xs:base64Binary?,
 +
  $b as xs:base64Binary?
 +
) as xs:base64Binary?</pre>
 +
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
 
|Returns the "bitwise or" of two binary arguments.<br/>If either argument is the empty sequence, an empty sequence is returned.
 
|Returns the "bitwise or" of two binary arguments.<br/>If either argument is the empty sequence, an empty sequence is returned.
−
|-
+
|- valign="top"
 
| '''Errors'''
 
| '''Errors'''
 
|{{Error|differing-length-arguments|#Errors}} the input arguments are of differing length.
 
|{{Error|differing-length-arguments|#Errors}} the input arguments are of differing length.
Line 313: Line 386:
 
==bin:xor==
 
==bin:xor==
 
{| width='100%'
 
{| width='100%'
−
|-
+
|- valign="top"
−
| width='120' | '''Signatures'''
+
| width='120' | '''Signature'''
−
|{{Func|bin:xor|$a as xs:base64Binary?, $b as xs:base64Binary?|xs:base64Binary?}}
+
|<pre>bin:xor(
−
|-
+
  $a as xs:base64Binary?,
 +
  $b as xs:base64Binary?
 +
) as xs:base64Binary?</pre>
 +
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
 
|Returns the "bitwise xor" of two binary arguments.<br/>If either argument is the empty sequence, an empty sequence is returned.
 
|Returns the "bitwise xor" of two binary arguments.<br/>If either argument is the empty sequence, an empty sequence is returned.
−
|-
+
|- valign="top"
 
| '''Errors'''
 
| '''Errors'''
 
|{{Error|differing-length-arguments|#Errors}} the input arguments are of differing length.
 
|{{Error|differing-length-arguments|#Errors}} the input arguments are of differing length.
Line 326: Line 402:
 
==bin:and==
 
==bin:and==
 
{| width='100%'
 
{| width='100%'
−
|-
+
|- valign="top"
−
| width='120' | '''Signatures'''
+
| width='120' | '''Signature'''
−
|{{Func|bin:and|$a as xs:base64Binary?, $b as xs:base64Binary?|xs:base64Binary?}}
+
|<pre>bin:and(
−
|-
+
  $a as xs:base64Binary?,
 +
  $b as xs:base64Binary?
 +
) as xs:base64Binary?</pre>
 +
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
 
|Returns the "bitwise and" of two binary arguments.<br/>If either argument is the empty sequence, an empty sequence is returned.
 
|Returns the "bitwise and" of two binary arguments.<br/>If either argument is the empty sequence, an empty sequence is returned.
−
|-
+
|- valign="top"
 
| '''Errors'''
 
| '''Errors'''
 
|{{Error|differing-length-arguments|#Errors}} the input arguments are of differing length.
 
|{{Error|differing-length-arguments|#Errors}} the input arguments are of differing length.
Line 339: Line 418:
 
==bin:not==
 
==bin:not==
 
{| width='100%'
 
{| width='100%'
−
|-
+
|- valign="top"
−
| width='120' | '''Signatures'''
+
| width='120' | '''Signature'''
−
|{{Func|bin:not|$in as xs:base64Binary?|xs:base64Binary?}}
+
|<pre>bin:not(
−
|-
+
  $in as xs:base64Binary?
 +
) as xs:base64Binary?</pre>
 +
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
 
|Returns the "bitwise not" of a binary argument.<br/>If the argument is the empty sequence, an empty sequence is returned.
 
|Returns the "bitwise not" of a binary argument.<br/>If the argument is the empty sequence, an empty sequence is returned.
Line 349: Line 430:
 
==bin:shift==
 
==bin:shift==
 
{| width='100%'
 
{| width='100%'
−
|-
+
|- valign="top"
−
| width='120' | '''Signatures'''
+
| width='120' | '''Signature'''
−
|{{Func|bin:shift|$in as xs:base64Binary?, $by as xs:integer|xs:base64Binary?}}
+
|<pre>bin:shift(
−
|-
+
  $in as xs:base64Binary?,
 +
  $by as xs:integer
 +
) as xs:base64Binary?</pre>
 +
|- valign="top"
 
| '''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 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.
 
|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 362: Line 446:
 
! width="240"|Code
 
! width="240"|Code
 
|Description
 
|Description
−
|-
+
|- valign="top"
 
|{{Code|differing-length-arguments}}  
 
|{{Code|differing-length-arguments}}  
 
|The arguments to a bitwise operation have different lengths.
 
|The arguments to a bitwise operation have different lengths.
−
|-
+
|- valign="top"
 
|{{Code|index-out-of-range}}
 
|{{Code|index-out-of-range}}
 
|An offset value is out of range.
 
|An offset value is out of range.
−
|-
+
|- valign="top"
 
|{{Code|negative-size}}
 
|{{Code|negative-size}}
 
|A size value is negative.
 
|A size value is negative.
−
|-
+
|- valign="top"
 
|{{Code|octet-out-of-range}}
 
|{{Code|octet-out-of-range}}
 
|An octet value lies outside the range 0-255.
 
|An octet value lies outside the range 0-255.
−
|-
+
|- valign="top"
 
|{{Code|non-numeric-character}}
 
|{{Code|non-numeric-character}}
 
|Binary data cannot be parsed as number.
 
|Binary data cannot be parsed as number.
−
|-
+
|- valign="top"
 
|{{Code|unknown-encoding}}
 
|{{Code|unknown-encoding}}
 
|An encoding is not supported.
 
|An encoding is not supported.
−
|-
+
|- valign="top"
 
|{{Code|conversion-error}}
 
|{{Code|conversion-error}}
 
|An error or malformed input during converting a string.
 
|An error or malformed input during converting a string.
−
|-
+
|- valign="top"
 
|{{Code|unknown-significance-order}}
 
|{{Code|unknown-significance-order}}
 
|An octet-order value is unknown.
 
|An octet-order value is unknown.

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 "http://docs.basex.org/index.php?title=Binary_Module&oldid=16628"