Difference between revisions of "Binary Module"
Jump to navigation
Jump to search
Line 11: | Line 11: | ||
==bin:hex== | ==bin:hex== | ||
{| width='100%' | {| width='100%' | ||
− | |- | + | |- valign="top" |
| width='120' | '''Signatures''' | | width='120' | '''Signatures''' | ||
|{{Func|bin:hex|$in as xs:string?|xs:base64Binary?}} | |{{Func|bin:hex|$in as xs:string?|xs:base64Binary?}} | ||
− | |- | + | |- 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 27: | ||
==bin:bin== | ==bin:bin== | ||
{| width='100%' | {| width='100%' | ||
− | |- | + | |- valign="top" |
| width='120' | '''Signatures''' | | width='120' | '''Signatures''' | ||
|{{Func|bin:bin|$in as xs:string?|xs:base64Binary?}} | |{{Func|bin:bin|$in as xs:string?|xs:base64Binary?}} | ||
− | |- | + | |- 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>string(bin:bin('1101000111010101'))</code> yields <code>0dU=</code>.<br/><code>string(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 43: | Line 43: | ||
==bin:octal== | ==bin:octal== | ||
{| width='100%' | {| width='100%' | ||
− | |- | + | |- valign="top" |
| width='120' | '''Signatures''' | | width='120' | '''Signatures''' | ||
|{{Func|bin:octal|$in as xs:string?|xs:base64Binary?}} | |{{Func|bin:octal|$in as xs:string?|xs:base64Binary?}} | ||
− | |- | + | |- 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 59: | ||
==bin:to-octets== | ==bin:to-octets== | ||
{| width='100%' | {| width='100%' | ||
− | |- | + | |- valign="top" |
| width='120' | '''Signatures''' | | width='120' | '''Signatures''' | ||
|{{Func|bin:to-octets|$in as xs:base64Binary|xs:integer*}} | |{{Func|bin:to-octets|$in as xs:base64Binary|xs:integer*}} | ||
− | |- | + | |- 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 69: | ||
==bin:from-octets== | ==bin:from-octets== | ||
{| width='100%' | {| width='100%' | ||
− | |- | + | |- valign="top" |
| width='120' | '''Signatures''' | | width='120' | '''Signatures''' | ||
|{{Func|bin:from-octets|$in as xs:integer*|xs:base64Binary}} | |{{Func|bin:from-octets|$in as xs:integer*|xs:base64Binary}} | ||
− | |- | + | |- 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 84: | ||
==bin:length== | ==bin:length== | ||
{| width='100%' | {| width='100%' | ||
− | |- | + | |- valign="top" |
| width='120' | '''Signatures''' | | width='120' | '''Signatures''' | ||
|{{Func|bin:length|$in as xs:base64Binary|xs:integer}} | |{{Func|bin:length|$in as xs:base64Binary|xs:integer}} | ||
− | |- | + | |- valign="top" |
| '''Summary''' | | '''Summary''' | ||
|Returns the size of binary data in octets. | |Returns the size of binary data in octets. | ||
Line 94: | Line 94: | ||
==bin:part== | ==bin:part== | ||
{| width='100%' | {| width='100%' | ||
− | |- | + | |- valign="top" |
| 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?}} | ||
− | |- | + | |- 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 110: | ||
==bin:join== | ==bin:join== | ||
{| width='100%' | {| width='100%' | ||
− | |- | + | |- valign="top" |
| width='120' | '''Signatures''' | | width='120' | '''Signatures''' | ||
|{{Func|bin:join|$in as xs:base64Binary*|xs:base64Binary}} | |{{Func|bin:join|$in as xs:base64Binary*|xs:base64Binary}} | ||
− | |- | + | |- 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 120: | ||
==bin:insert-before== | ==bin:insert-before== | ||
{| width='100%' | {| width='100%' | ||
− | |- | + | |- valign="top" |
| width='120' | '''Signatures''' | | width='120' | '''Signatures''' | ||
|{{Func|bin:insert-before|$in as xs:base64Binary?, $offset as xs:integer, $extra as xs:base64Binary?|xs:base64Binary?}} | |{{Func|bin:insert-before|$in as xs:base64Binary?, $offset as xs:integer, $extra as xs:base64Binary?|xs:base64Binary?}} | ||
− | |- | + | |- 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 133: | ||
==bin:pad-left== | ==bin:pad-left== | ||
{| width='100%' | {| width='100%' | ||
− | |- | + | |- valign="top" |
| width='120' | '''Signatures''' | | width='120' | '''Signatures''' | ||
|{{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?}} | |{{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?}} | ||
− | |- | + | |- 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 146: | ||
==bin:pad-right== | ==bin:pad-right== | ||
{| width='100%' | {| width='100%' | ||
− | |- | + | |- valign="top" |
| width='120' | '''Signatures''' | | width='120' | '''Signatures''' | ||
|{{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?}} | |{{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?}} | ||
− | |- | + | |- 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 159: | ||
==bin:find== | ==bin:find== | ||
{| width='100%' | {| width='100%' | ||
− | |- | + | |- valign="top" |
| width='120' | '''Signatures''' | | width='120' | '''Signatures''' | ||
|{{Func|bin:find|$in as xs:base64Binary?, $offset as xs:integer, $search as xs:base64Binary|xs:integer?}} | |{{Func|bin:find|$in as xs:base64Binary?, $offset as xs:integer, $search as xs:base64Binary|xs:integer?}} | ||
− | |- | + | |- 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 174: | ||
==bin:decode-string== | ==bin:decode-string== | ||
{| width='100%' | {| width='100%' | ||
− | |- | + | |- valign="top" |
| width='120' | '''Signatures''' | | width='120' | '''Signatures''' | ||
|{{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/> | |{{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/> | ||
− | |- | + | |- 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 190: | ||
==bin:encode-string== | ==bin:encode-string== | ||
{| width='100%' | {| width='100%' | ||
− | |- | + | |- valign="top" |
| width='120' | '''Signatures''' | | width='120' | '''Signatures''' | ||
|{{Func|bin:encode-string|$in as xs:string?, $encoding as xs:string|xs:base64Binary?}} | |{{Func|bin:encode-string|$in as xs:string?, $encoding as xs:string|xs:base64Binary?}} | ||
− | |- | + | |- 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 207: | ||
==bin:pack-double== | ==bin:pack-double== | ||
{| width='100%' | {| width='100%' | ||
− | |- | + | |- valign="top" |
| width='120' | '''Signatures''' | | width='120' | '''Signatures''' | ||
|{{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}} | |{{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}} | ||
− | |- | + | |- 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 220: | ||
==bin:pack-float== | ==bin:pack-float== | ||
{| width='100%' | {| width='100%' | ||
− | |- | + | |- valign="top" |
| width='120' | '''Signatures''' | | width='120' | '''Signatures''' | ||
|{{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}} | |{{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}} | ||
− | |- | + | |- 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 233: | ||
==bin:pack-integer== | ==bin:pack-integer== | ||
{| width='100%' | {| width='100%' | ||
− | |- | + | |- valign="top" |
| width='120' | '''Signatures''' | | width='120' | '''Signatures''' | ||
|{{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}} | |{{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}} | ||
− | |- | + | |- 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 246: | ||
==bin:unpack-double== | ==bin:unpack-double== | ||
{| width='100%' | {| width='100%' | ||
− | |- | + | |- valign="top" |
| width='120' | '''Signatures''' | | width='120' | '''Signatures''' | ||
|{{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}} | |{{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}} | ||
− | |- | + | |- 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 259: | ||
==bin:unpack-float== | ==bin:unpack-float== | ||
{| width='100%' | {| width='100%' | ||
− | |- | + | |- valign="top" |
| width='120' | '''Signatures''' | | width='120' | '''Signatures''' | ||
|{{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}} | |{{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}} | ||
− | |- | + | |- 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 272: | ||
==bin:unpack-integer== | ==bin:unpack-integer== | ||
{| width='100%' | {| width='100%' | ||
− | |- | + | |- valign="top" |
| width='120' | '''Signatures''' | | width='120' | '''Signatures''' | ||
|{{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}} | |{{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}} | ||
− | |- | + | |- 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 285: | ||
==bin:unpack-unsigned-integer== | ==bin:unpack-unsigned-integer== | ||
{| width='100%' | {| width='100%' | ||
− | |- | + | |- valign="top" |
| width='120' | '''Signatures''' | | width='120' | '''Signatures''' | ||
|{{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}} | |{{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}} | ||
− | |- | + | |- 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 300: | ||
==bin:or== | ==bin:or== | ||
{| width='100%' | {| width='100%' | ||
− | |- | + | |- valign="top" |
| width='120' | '''Signatures''' | | width='120' | '''Signatures''' | ||
|{{Func|bin:or|$a as xs:base64Binary?, $b as xs:base64Binary?|xs:base64Binary?}} | |{{Func|bin:or|$a as xs:base64Binary?, $b as xs:base64Binary?|xs:base64Binary?}} | ||
− | |- | + | |- 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 313: | ||
==bin:xor== | ==bin:xor== | ||
{| width='100%' | {| width='100%' | ||
− | |- | + | |- valign="top" |
| width='120' | '''Signatures''' | | width='120' | '''Signatures''' | ||
|{{Func|bin:xor|$a as xs:base64Binary?, $b as xs:base64Binary?|xs:base64Binary?}} | |{{Func|bin:xor|$a as xs:base64Binary?, $b as xs:base64Binary?|xs:base64Binary?}} | ||
− | |- | + | |- 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 326: | ||
==bin:and== | ==bin:and== | ||
{| width='100%' | {| width='100%' | ||
− | |- | + | |- valign="top" |
| width='120' | '''Signatures''' | | width='120' | '''Signatures''' | ||
|{{Func|bin:and|$a as xs:base64Binary?, $b as xs:base64Binary?|xs:base64Binary?}} | |{{Func|bin:and|$a as xs:base64Binary?, $b as xs:base64Binary?|xs:base64Binary?}} | ||
− | |- | + | |- 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 339: | ||
==bin:not== | ==bin:not== | ||
{| width='100%' | {| width='100%' | ||
− | |- | + | |- valign="top" |
| width='120' | '''Signatures''' | | width='120' | '''Signatures''' | ||
|{{Func|bin:not|$in as xs:base64Binary?|xs:base64Binary?}} | |{{Func|bin:not|$in as xs:base64Binary?|xs:base64Binary?}} | ||
− | |- | + | |- 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 349: | ||
==bin:shift== | ==bin:shift== | ||
{| width='100%' | {| width='100%' | ||
− | |- | + | |- valign="top" |
| width='120' | '''Signatures''' | | width='120' | '''Signatures''' | ||
|{{Func|bin:shift|$in as xs:base64Binary?, $by as xs:integer|xs:base64Binary?}} | |{{Func|bin:shift|$in as xs:base64Binary?, $by as xs:integer|xs:base64Binary?}} | ||
− | |- | + | |- 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 362: | ||
! 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. |
Revision as of 13:16, 20 July 2022
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.
Contents
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.