Bureaucrats, editor, reviewer, Administrators
13,550
edits
Changes
Jump to navigation
Jump to search
no edit summary
| '''Errors'''
|{{Error|octet-out-of-range|#Errors}} one of the octets lies outside the range 0 - 255.
|}
=Basic Operations=
==bin:hex==
{| width='100%'
|-
| width='120' | '''Signatures'''
|{{Func|bin:length|$in as xs:base64Binary|xs:integer}}
|-
| '''Summary'''
|Returns the size of binary data in octets.
|}
==bin:part==
{| width='100%'
|-
| width='120' | '''Signatures'''
|{{Func|bin:part|$in as xs:base64Binary?, $offset as xs:integer|xs:base64Binary}}
|-
| '''Summary'''
|Returns a section of binary data starting at the {{Code|$offset}} octet.<br/>If {{Code|$size}} is defined, the size of the returned binary data is {{Code|$size}} octets. If {{Code|$size}} is absent, all remaining data from {{Code|$offset}} is returned.<br/>The {{Code|$offset}} is zero based.<br/>If the value of {{Code|$in}} is the empty sequence, the function returns an empty sequence.
|-
| '''Errors'''
|{{Error|negative-offset|#Errors}} the specified offset is negative.<br/>{{Error|negative-size|#Errors}} the specified size is negative.<br/>{{Error|offset-beyond-end|#Errors}} the specified offset + size extends beyond the binary data.
|-
| '''Examples'''
|Test whether binary data starts with binary content consistent with a PDF file:<br/><code>bin:part($data, 0, 4) eq bin:hex("25504446")</code>.
|}
==bin:join==
{| width='100%'
|-
| width='120' | '''Signatures'''
|{{Func|bin:join|$in as xs:base64Binary*|xs:base64Binary}}
|-
| '''Summary'''
|Returns an {{Code|xs:base64Binary}} created by concatenating the items in the sequence {{Code|$in}}, in order. If the value of {{Code|$in}} is the empty sequence, the function returns a binary item containing no data bytes.
|}
==bin:insert-before==
{| width='100%'
|-
| width='120' | '''Signatures'''
|{{Func|bin:insert-before|$in as xs:base64Binary?, $offset as xs:integer, $extra as xs:base64Binary?|xs:base64Binary?}}
|-
| '''Summary'''
|Returns binary data consisting sequentially of the data from {{Code|$in}} up to and including the {{Code|$offset - 1}} octet, followed by all the data from {{Code|$extra}}, and then the remaining data from {{Code|$in}}.<br/>The {{Code|$offset}} is zero based. If the value of $in is the empty sequence, the function returns an empty sequence. If the value of $extra is the empty sequence, the function returns $in.
|-
|{{Error|negative-offset|#Errors}} the specified offset is negative.<br/>{{Error|offset-beyond-end|#Errors}} the specified offset extends beyond the binary data.
|}
==bin:pad-left==
{| width='100%'
|-
| 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?}}
|-
| '''Summary'''
|Returns an {{Code|xs:base64Binary}} created by padding the input with {{Code|$size}} octets in front of the input. If {{Code|$octet}} is specified, the padding octets each have that value, otherwise they are zero.<br/>If the value of $in is the empty sequence, the function returns an empty sequence.
|-
| '''Errors'''
|{{Error|negative-size|#Errors}} the specified size is negative.<br/>{{Error|octet-out-of-range|#Errors}} the specified octet lies outside the range 0-255.
|}
==bin:pad-right==
{| width='100%'
|-
| 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?}}
|-
| '''Summary'''
|Returns an {{Code|xs:base64Binary}} created by padding the input with {{Code|$size}} octets after the input. If {{Code|$octet}} is specified, the padding octets each have that value, otherwise they are zero.<br/>If the value of $in is the empty sequence, the function returns an empty sequence.
|-
| '''Errors'''
|{{Error|negative-size|#Errors}} the specified size is negative.<br/>{{Error|octet-out-of-range|#Errors}} the specified octet lies outside the range 0-255.
|}
==bin:find==
{| width='100%'
|-
| width='120' | '''Signatures'''
|{{Func|bin:find|$in as xs:base64Binary?, $offset as xs:integer, $search as xs:base64Binary|xs:integer?}}
|-
| '''Summary'''
|Returns the first location of the binary search sequence in the input, or if not found, the empty sequence.<br/>The $offset and the returned location are zero based. If the value of $in is the empty sequence, the function returns an empty sequence.
|-
| '''Errors'''
|{{Error|negative-offset|#Errors}} the specified offset is negative.<br/>{{Error|offset-beyond-end|#Errors}} the specified offset extends beyond the binary data.<br/>{{Error|empty-search-item|#Errors}} the specified search data is empty.
|}
=Text Decoding and Encoding=
==bin:decode-string==
{| width='100%'
|-
| 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/>
|-
| '''Summary'''
|Decodes binary data as a string in a given {{Code|$encoding}}.<br/>If {{Code|$offset}} and {{Code|$size}} are provided, the {{Code|$size}} octets from {{Code|$offset}} are decoded. If {{Code|$offset}} alone is provided, octets from {{Code|$offset}} to the end are decoded.If the value of $in is the empty sequence, the function returns an empty sequence.
|-
| '''Errors'''
|{{Error|negative-offset|#Errors}} the specified offset is negative.<br/>{{Error|negative-size|#Errors}} the specified size is negative.<br/>{{Error|offset-beyond-end|#Errors}} the specified offset + size extends beyond the binary data.<br/>{{Error|unknown-encoding|#Errors}} the specified encoding is unknown.<br/>{{Error|decoding-error|#Errors}} an error or malformed input occurred during decoding the string.
|-
| '''Examples'''
|Tests whether the binary data starts with binary content consistent with a PDF file:<br/><code>bin:decode-string($data, 'UTF-8', 0, 4) eq '%PDF'</code>.
|}
==bin:encode-string==
{| width='100%'
|-
| width='120' | '''Signatures'''
|{{Func|bin:encode-string|$in as xs:string?, $encoding as xs:string|xs:base64Binary?}}
|-
| '''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.
|-
| '''Errors'''
|{{Error|unknown-encoding|#Errors}} the specified encoding is unknown.<br/>{{Error|encoding-error|#Errors}} an error or malformed input occurred during encoding the string.
|}
=Packing and Unpacking of Numeric Values=
The functions have an optional parameter $octet-order whose string value controls the order: Least-significant-first order is indicated by any of the values {{Code|least-significant-first}}, {{Code|little-endian}}, or {{Code|LE}}. Most-significant-first order is indicated by any of the values {{Code|most-significant-first}}, {{Code|big-endian}}, or {{Code|BE}}.
==bin:pack-double==
{| width='100%'
|-
| 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}}
|-
| '''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.
|-
| '''Errors'''
|{{Error|unknown-significance-order|#Errors}} the specified octet order is unknown.
|}
==bin:pack-float==
{| width='100%'
|-
| width='120' | '''Signatures'''
|{{Func|bin:pack-float|$in as xs:double|xs:base64Binary}}<br/>{{Func|bin:pack-float|$in as xs:double, $octet-order as xs:string|xs:base64Binary}}
|-
| '''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.
|-
| '''Errors'''
|{{Error|unknown-significance-order|#Errors}} the specified octet order is unknown.
|}
==bin:pack-integer==
{| width='100%'
|-
| width='120' | '''Signatures'''
|{{Func|bin:pack-integer|$in as xs:double, $size as xs:integer|xs:base64Binary}}<br/>{{Func|bin:pack-float|$in as xs:double, $size as xs:integer, $octet-order as xs:string|xs:base64Binary}}
|-
| '''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.
|-
| '''Errors'''
|{{Error|unknown-significance-order|#Errors}} the specified octet order is unknown.<br/>{{Error|negative-size|#Errors}} the specified size is negative.<br/>
|}
==bin:unpack-double==
{| width='100%'
|-
| 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}}
|-
| '''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.
|-
| '''Errors'''
|{{Error|negative-offset|#Errors}} the specified offset is negative.<br/>{{Error|offset-beyond-end|#Errors}} the specified offset + 8 extends beyond the binary data.<br/>{{Error|unknown-significance-order|#Errors}} the specified octet order is unknown.
|}
==bin:unpack-float==
{| width='100%'
|-
| width='120' | '''Signatures'''
|{{Func|bin:unpack-float|$in as xs:base64Binary, $offset as xs:integer|xs:double}}<br/>{{Func|bin:unpack-float|$in as xs:base64Binary, $offset as xs:integer, $octet-order as xs:string|xs:float}}
|-
| '''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.
|-
| '''Errors'''
|{{Error|negative-offset|#Errors}} the specified offset is negative.<br/>{{Error|offset-beyond-end|#Errors}} the specified offset + 4 extends beyond the binary data.<br/>{{Error|unknown-significance-order|#Errors}} the specified octet order is unknown.
|}
==bin:unpack-integer==
{| width='100%'
|-
| width='120' | '''Signatures'''
|{{Func|bin:unpack-integer|$in as xs:base64Binary, $offset as xs:integer|xs:double}}<br/>{{Func|bin:unpack-integer|$in as xs:base64Binary, $offset as xs:integer, $octet-order as xs:string|xs:float}}
|-
| '''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}}.
|-
| '''Errors'''
|{{Error|negative-offset|#Errors}} the specified offset is negative.<br/>{{Error|negative-size|#Errors}} the specified size is negative.<br/>{{Error|offset-beyond-end|#Errors}} the specified offset + 4 extends beyond the binary data.<br/>{{Error|unknown-significance-order|#Errors}} the specified octet order is unknown.
|}
==bin:unpack-unsigned-integer==
{| width='100%'
|-
| width='120' | '''Signatures'''
|{{Func|bin:unpack-unsigned-integer|$in as xs:base64Binary, $offset as xs:integer|xs:double}}<br/>{{Func|bin:unpack-unsigned-integer|$in as xs:base64Binary, $offset as xs:integer, $octet-order as xs:string|xs:float}}
|-
| '''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}}.
|-
| '''Errors'''
|{{Error|negative-offset|#Errors}} the specified offset is negative.<br/>{{Error|negative-size|#Errors}} the specified size is negative.<br/>{{Error|offset-beyond-end|#Errors}} the specified offset + 4 extends beyond the binary data.<br/>{{Error|unknown-significance-order|#Errors}} the specified octet order is unknown.
|}
...
==bin:==
{| width='100%'
|-
| width='120' | '''Signatures'''
|{{Func|bin:|$in as |xs:}}
|-
| '''Summary'''
|
|-
| '''Errors'''
|{{Error|non-numeric-character|#Errors}}
|-
| '''Examples'''
|<code>bin:hex('11223F4E')</code> yields <code>ESI/Tg==</code>.
|}
