Changes

=Conventions=

=Constants and Conversions=

==bin:hex==

{| width='100%'

| '''Summary'''

| '''Errors'''

|{{Error|non-numeric-character|#Errors}} the input cannot be parsed as a hexadecimal number.

| '''Examples'''

|}

==bin:bin==

{| width='100%'

| '''Summary'''

| '''Errors'''

|{{Error|non-numeric-character|#Errors}} the input cannot be parsed as a binary number.

| '''Examples'''

|}

==bin:octal==

{| width='100%'

| '''Summary'''

| '''Errors'''

|{{Error|non-numeric-character|#Errors}} the input cannot be parsed as an octal number.

| '''Examples'''

|}

==bin:to-octets==

{| width='100%'

| '''Summary'''

|}

==bin:from-octets==

{| width='100%'

| '''Summary'''

| '''Errors'''

|{{Error|octet-out-of-range|#Errors}} one of the octets lies outside the range 0 - 255.

=Basic Operations=

{| width='100%'

| '''Summary'''

|Returns the size of binary data in octets.

==bin:part==

{| width='100%'

| '''Summary'''

| '''Errors'''

| '''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%'

| '''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%'

| '''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'''

|}

==bin:pad-left==

{| width='100%'

| '''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%'

| '''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%'

| '''Summary'''

| '''Errors'''

|}

==bin:decode-string==

{| width='100%'

| '''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'''

| '''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%'

| '''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'''

|}

==bin:pack-double==

{| width='100%'

| '''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%'

| '''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%'

| '''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%'

| '''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'''

|}

==bin:unpack-float==

{| width='100%'

| '''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'''

|}

==bin:unpack-integer==

{| width='100%'

| '''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'''

|}

==bin:unpack-unsigned-integer==

{| width='100%'

| '''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'''

|}

==bin:or==

{| width='100%'

| '''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%'

| '''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%'

| '''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%'

| '''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%'

| '''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.

! width="240"|Code

|Description

|{{Code|differing-length-arguments}}

|The arguments to a bitwise operation have different lengths.

|{{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|unknown-significance-order}}

|An octet-order value is unknown.

Introduced with Version 7.8.