Changes

All functions and errors in this module are assigned to the {{Code|<code><nowiki>http://expath.org/ns/binary}} </nowiki></code> namespace, which is statically bound to the {{Code|bin}} prefix.<br/>

|Returns the binary form of the set of octets written as a sequence of (ASCII) hex digits ([0-9A-Fa-f]).<br />{{Code|$in}} will be effectively zero-padded from the left to generate an integral number of octets, i.e. an even number of hexadecimal digits. If {{Code|$in}} is an empty string, then the result will be an {{Code|xs:base64Binary}} with no embedded data.<br/>Byte order in the result follows (per-octet) character order in the string.<br/>If the value of {{Code|$in}} is the empty sequence, the function returns an empty sequence.

|<code>string(bin:hex('11223F4E'))</code> yields <code>ESI/Tg==</code>.<br/><code>string(xs:hexBinary(bin:hex('FF')))</code> yields <code>FF</code>.

|Returns the binary form of the set of octets written as a sequence of (8-wise) (ASCII) binary digits ([01]).<br/><code>$in</code> will be effectively zero-padded from the left to generate an integral number of octets. If <code>$in</code> is an empty string, then the result will be an <code>xs:base64Binary</code> with no embedded data.<br/>Byte order in the result follows (per-octet) character order in the string.<br/>If the value of <code>$in</code> is the empty sequence, the function returns an empty sequence.

|<code>string(bin:bin('1101000111010101'))</code> yields <code>0dU=</code>.<br/><code>string(xs:hexBinary(bin:bin('1000111010101')))</code> yields <code>11D5</code>.

|Returns the binary form of the set of octets written as a sequence of (ASCII) octal digits ([0-7]).<br/><code>$in</code> will be effectively zero-padded from the left to generate an integral number of octets. If <code>$in</code> is an empty string, then the result will be an <code>xs:base64Binary</code> with no embedded data.<br/>Byte order in the result follows (per-octet) character order in the string.<br/>If the value of <code>$in</code> is the empty sequence, the function returns an empty sequence.

|Returns binary data as a sequence of octets.<br/>If <code>$in</code> is a zero length binary data then the empty sequence is returned.<br/>Octets are returned as integers from 0 to 255.

|Converts a sequence of octets into binary data.<br/>Octets are integers from 0 to 255.<br/>If the value of <code>$in</code> is the empty sequence, the function returns zero-sized binary data.

=Basic Operations= ==bin:length=={| 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?}}<br/>{{Func|bin:part|$in as xs:base64Binary?, $offset as xs:integer, $size as xs:integer|xs:base64Binary?}}|-| '''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.|-| '''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.|-| '''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 {{Code|$in}} is the empty sequence, the function returns an empty sequence.|-| '''Errors'''|{{Error|index-out-of-range|#Errors}} the specified offset is out of range.|} ==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 {{Code|$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 {{Code|$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 {{Code|$offset}} and the returned location are zero based. If the value of {{Code|$in}} is the empty sequence, the function returns an empty sequence.|-| '''Errors'''|{{Error|index-out-of-range|#Errors}} the specified offset + size is out of range.|} =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 {{Code|$in}} is the empty sequence, the function returns an empty sequence.|-| '''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.|-| '''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|conversion-error|#Errors}} an error or malformed input occurred during encoding the string.|} =Packing and Unpacking of Numeric Values= The functions have an optional parameter $octet-order whose string value controls the order: Least-significant-first order is indicated by any of the values {{Code|least-significant-first}}, {{Code|little-endian}}, or {{Code|LE}}. Most-significant-first order is indicated by any of the values {{Code|most-significant-first}}, {{Code|big-endian}}, or {{Code|BE}}. ==bin:pack-double=={| width='100%'|-| 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:float|xs:base64Binary}}<br/>{{Func|bin:pack-float|$in as xs:float, $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:integer, $size as xs:integer|xs:base64Binary}}<br/>{{Func|bin:pack-integer|$in as xs:integer, $size as xs:integer, $octet-order as xs:string|xs:base64Binary}}|-| '''Summary'''|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|index-out-of-range|#Errors}} the specified offset is out of range.<br/>{{Error|unknown-significance-order|#Errors}} the specified octet order is unknown.|} ==bin:unpack-float=={| width='100%'|-| 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}}|-| '''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|index-out-of-range|#Errors}} the specified offset + size is out of range.<br/>{{Error|unknown-significance-order|#Errors}} the specified octet order is unknown.|} ==bin:unpack-integer=={| width='100%'|-| 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}}|-| '''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-size|#Errors}} the specified size is negative.<br/>{{Error|index-out-of-range|#Errors}} the specified offset + size is out of range.<br/>{{Error|unknown-significance-order|#Errors}} the specified octet order is unknown.|} ==bin:unpack-unsigned-integer=={| width='100%'|-| 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}}|-| '''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-size|#Errors}} the specified size is negative.<br/>{{Error|index-out-of-range|#Errors}} the specified offset + size is out of range.<br/>{{Error|unknown-significance-order|#Errors}} the specified octet order is unknown.|} =Bitwise Operations= ==bin:or=={| width='100%'|-| width='120' | '''Signatures'''|{{Func|bin:or|$a as xs:base64Binary?, $b as xs:base64Binary?|xs:base64Binary?}}|-| '''Summary'''|Returns the "bitwise or" of two binary arguments.<br/>If either argument is the empty sequence, an empty sequence is returned.|-| '''Errors'''|{{Error|differing-length-arguments|#Errors}} the input arguments are of differing length.|} ==bin:xor=={| width='100%'|-| width='120' | '''Signatures'''|{{Func|bin:xor|$a as xs:base64Binary?, $b as xs:base64Binary?|xs:base64Binary?}}|-| '''Summary'''|Returns the "bitwise xor" of two binary arguments.<br/>If either argument is the empty sequence, an empty sequence is returned.|-| '''Errors'''|{{Error|differing-length-arguments|#Errors}} the input arguments are of differing length.|} ==bin:and=={| width='100%'|-| width='120' | '''Signatures'''|{{Func|bin:and|$a as xs:base64Binary?, $b as xs:base64Binary?|xs:base64Binary?}}|-| '''Summary'''|Returns the "bitwise and" of two binary arguments.<br/>If either argument is the empty sequence, an empty sequence is returned.|-| '''Errors'''|{{Error|differing-length-arguments|#Errors}} the input arguments are of differing length.|} ==bin:not=={| width='100%'|-| width='120' | '''Signatures'''|{{Func|bin:not|$in as xs:base64Binary?|xs:base64Binary?}}|-| '''Summary'''|Returns the "bitwise not" of a binary argument.<br/>If the argument is the empty sequence, an empty sequence is returned.|} ==bin:shift=={| width='100%'|-| width='120' | '''Signatures'''|{{Func|bin:shift|$in as xs:base64Binary?, $by as xs:integer|xs:base64Binary?}}|-| '''Summary'''|Shifts bits in binary data.<br/>If {{Code|$by}} is zero, the result is identical to {{Code|$in}}. If {{Code|$by}} is positive then bits are shifted to the left. Otherwise, bits are shifted to the right. If the absolute value of <code>$by</code> is greater than the bit-length of {{Code|$in}} then an all-zeros result is returned. The result always has the same size as {{Code|$in}}. The shifting is logical: zeros are placed into discarded bits. If the value of {{Code|$in}} is the empty sequence, the function returns an empty sequence.|} =Errors= {| class="wikitable" width="100%"! width="240"|Code|Description|-|{{Code|differing-length-arguments}} |The arguments to a bitwise operation have different lengths.|-|{{Code|index-out-of-range}}|An offset value is out of range.|-|{{Code|negative-size}}|A size value is negative.|-|{{Code|octet-out-of-range}}|An octet value lies outside the range 0-255.|-|{{Code|non-numeric-character}}|Binary data cannot be parsed as number.|-|{{Code|unknown-encoding}}|An encoding is not supported.|-|{{Code|conversion-error}}|An error or malformed input during converting a string.|-|{{Code|unknown-significance-order}}|An octet-order value is unknown.|} =Changelog= Introduced with Version 7.8.