# http://expath.org/ns/binary

This module is statically bound to the prefix "binary".

- Description
- Extension functions to process data from binary files, including extracting subparts, searching, basic binary operations and conversion between binary and structured forms.
- Functions

### binary:hex

- Signature
`binary:hex($in as xs:string?) as xs:string?`

- Description
`$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 a`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.

### binary:binary

- Signature
`binary:binary($in as xs:string?) as xs:string?`

- Description
`$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 a`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.

### binary:octal

- Signature
`binary:octal($in as xs:string?) as xs:string?`

- Description
`$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 a`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.

### binary:to-octets

- Signature
`binary:to-octets($in as xs:base64Binary) as xs:base64Binary`

- Description
If

`$in`

is a zero length binary data then the empty sequence is returned.Octets are returned as integers from 0 to 255.

### binary:from-octets

- Signature
`binary:from-octets($in as xs:integer*) as xs:integer*`

- Description
Octets are integers from 0 to 255.

If the value of

`$in`

is the empty sequence, the function returns zero-sized binary data.

### binary:length

- Signature
`binary:length($in as xs:base64Binary) as xs:base64Binary`

- Description
Returns the size of binary data in octets.

### binary:part

- Signature
`binary:part($in as xs:base64Binary?, $offset as xs:integer) as xs:integer`

binary:part($in as xs:base64Binary?, $offset as xs:integer, $size as xs:integer) as xs:integer- Description
Returns a section of binary data starting at the

`$offset`

octet. If`$size`

is defined, 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.The values of

`$offset`

and`$size`

**must**be non-negative integers.It is a dynamic error if

`$offset`

+`$size`

is larger than the size of the binary data in`$in`

.If the value of

`$in`

is the empty sequence, the function returns an empty sequence.

### binary:join

- Signature
`binary:join($in as xs:base64Binary*) as xs:base64Binary*`

- Description
The function 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.

### binary:insert-before

- Signature
`binary:insert-before($in as xs:base64Binary?, $offset as xs:integer, $extra as xs:base64Binary?) as xs:base64Binary?`

- Description
Returns binary data consisting sequentially of the data from

`$in`

upto 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.The value of

`$offset`

**must**be a non-negative integer.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`

.If

`$offset eq 0`

the result is the binary concatenation of`$extra`

and`$in`

, i.e. equivalent to`bin:join(($extra,$in))`

.

### binary:pad-left

- Signature
`binary:pad-left($in as xs:base64Binary?, $size as xs:integer) as xs:integer`

binary:pad-left($in as xs:base64Binary?, $size as xs:integer, $octet as xs:integer) as xs:integer- Description
The function 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 initialized to 0.`$size`

**must**be a non-negative integer.If the value of

`$in`

is the empty sequence, the function returns an empty sequence.

### binary:pad-right

- Signature
`binary:pad-right($in as xs:base64Binary?, $size as xs:integer) as xs:integer`

binary:pad-right($in as xs:base64Binary?, $size as xs:integer, $octet as xs:integer) as xs:integer- Description
The function returns an

`xs:base64Binary`

created by padding the input with`$size`

blank octets*after*the input. If`$octet`

is specified, the padding octets each have that value, otherwise they are initialized to 0.`$size`

**must**be a non-negative integer.If the value of

`$in`

is the empty sequence, the function returns an empty sequence.

### binary:index-of

- Signature
`binary:index-of($in as xs:base64Binary?, $offset as xs:integer, $search as xs:base64Binary) as xs:base64Binary`

- Description
The function returns the first location of the binary search sequence in the input, or if not found, the empty sequence.

If

`$search`

is empty`$offset`

is returned.The value of

`$offset`

**must**be a non-negative integer.The

`$offset`

is zero based.The returned location is zero based.

If the value of

`$in`

is the empty sequence, the function returns an empty sequence.

### binary:decode-string

- Signature
`binary:decode-string($in as xs:base64Binary?) as xs:base64Binary?`

binary:decode-string($in as xs:base64Binary?, $encoding as xs:string) as xs:string

binary:decode-string($in as xs:base64Binary?, $encoding as xs:string, $offset as xs:integer) as xs:integer

binary:decode-string($in as xs:base64Binary?, $encoding as xs:string, $offset as xs:integer, $size as xs:integer) as xs:integer- Description
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, otherwise the entire octet sequence is used.The

`$encoding`

argument is the name of an encoding. The values for this attribute follow the same rules as for the`encoding`

attribute in an XML declaration. The only values which every implementation is**required**to recognize are`utf-8`

and`utf-16`

.If

`$encoding`

is ommitted,`utf-8`

encoding is assumed.The values of

`$offset`

and`$size`

**must**be non-negative integers.If the value of

`$in`

is the empty sequence, the function returns an empty sequence.`$offset`

is zero based.

### binary:encode-string

- Signature
`binary:encode-string($in as xs:string?) as xs:string?`

binary:encode-string($in as xs:string?, $encoding as xs:string) as xs:string- Description
The

`$encoding`

argument is the name of an encoding. The values for this attribute follow the same rules as for the`encoding`

attribute in an XML declaration. The only values which every implementation is**required**to recognize are`utf-8`

and`utf-16`

.If

`$encoding`

is ommitted,`utf-8`

encoding is assumed.If the value of

`$in`

is the empty sequence, the function returns an empty sequence.

### binary:pack-double

- Signature
`binary:pack-double($in as xs:double) as xs:double`

binary:pack-double($in as xs:double, $octet-order as xs:string) as xs:string- Description
Most-significant-octet-first number representation is assumed unless the

`$octet-order`

parameter is specified. Acceptable values for`$octet-order`

are described in**8.1 Number 'endianness'**.The binary representation will correspond with that of the IEEE double-precision 64-bit floating point type [IEEE 754-1985]. For more details see

**8.3 Representation of floating point numbers**.

### binary:pack-float

- Signature
`binary:pack-float($in as xs:float) as xs:float`

binary:pack-float($in as xs:float, $octet-order as xs:string) as xs:string- Description
Most-significant-octet-first number representation is assumed unless the

`$octet-order`

parameter is specified. Acceptable values for`$octet-order`

are described in**8.1 Number 'endianness'**.The binary representation will correspond with that of the IEEE single-precision 32-bit floating point type [IEEE 754-1985]. For more details see

**8.3 Representation of floating point numbers**.

### binary:pack-integer

- Signature
`binary:pack-integer($in as xs:integer, $size as xs:integer) as xs:integer`

binary:pack-integer($in as xs:integer, $size as xs:integer, $octet-order as xs:string) as xs:string- Description
Most-significant-octet-first number representation is assumed unless the

`$octet-order`

parameter is specified. Acceptable values for`$octet-order`

are described in**8.1 Number 'endianness'**.Specifying a

`$size`

of zero yields an empty binary data.

### binary:unpack-double

- Signature
`binary:unpack-double($in as xs:base64Binary, $offset as xs:integer) as xs:integer`

binary:unpack-double($in as xs:base64Binary, $offset as xs:integer, $octet-order as xs:string) as xs:string- Description
Extract the double value stored in the 8 successive octets from the

`$offset`

octet of the binary data of`$in`

.`$octet-order`

parameter is specified. Acceptable values for`$octet-order`

are described in**8.1 Number 'endianness'**.The value of

`$offset`

**must**be a non-negative integer.The

`$offset`

is zero based.The binary representation is expected to correspond with that of the IEEE double-precision 64-bit floating point type [IEEE 754-1985]. For more details see

**8.3 Representation of floating point numbers**.

### binary:unpack-float

- Signature
`binary:unpack-float($in as xs:base64Binary, $offset as xs:integer) as xs:integer`

binary:unpack-float($in as xs:base64Binary, $offset as xs:integer, $octet-order as xs:string) as xs:string- Description
Extract the float value stored in the 4 successive octets from the

`$offset`

octet of the binary data of`$in`

.`$octet-order`

parameter is specified. Acceptable values for`$octet-order`

are described in**8.1 Number 'endianness'**.The value of

`$offset`

**must**be a non-negative integer.The

`$offset`

is zero based.The binary representation is expected to correspond with that of the IEEE single-precision 32-bit floating point type [IEEE 754-1985]. For more details see

**8.3 Representation of floating point numbers**.

### binary:unpack-integer

- Signature
`binary:unpack-integer($in as xs:base64Binary, $offset as xs:integer, $size as xs:integer) as xs:integer`

binary:unpack-integer($in as xs:base64Binary, $offset as xs:integer, $size as xs:integer, $octet-order as xs:string) as xs:string- Description
`$octet-order`

parameter is specified. Acceptable values for`$octet-order`

are described in**8.1 Number 'endianness'**.The values of

`$offset`

and`$size`

**must**be non-negative integers.`$offset`

is zero based.Specifying a

`$size`

of zero yields the integer`0`

.

### binary:unpack-unsigned-integer

- Signature
`binary:unpack-unsigned-integer($in as xs:base64Binary, $offset as xs:integer, $size as xs:integer) as xs:integer`

binary:unpack-unsigned-integer($in as xs:base64Binary, $offset as xs:integer, $size as xs:integer, $octet-order as xs:string) as xs:string- Description
`$octet-order`

parameter is specified. Acceptable values for`$octet-order`

are described in**8.1 Number 'endianness'**.The values of

`$offset`

and`$size`

**must**be non-negative integers.The

`$offset`

is zero based.Specifying a

`$size`

of zero yields the integer`0`

.

### binary:or

- Signature
`binary:or($a as xs:base64Binary?, $b as xs:base64Binary?) as xs:base64Binary?`

- Description
Returns "bitwise or" applied between

`$a`

and`$b`

.If either argument is the empty sequence, an empty sequence is returned.

### binary:xor

- Signature
`binary:xor($a as xs:base64Binary?, $b as xs:base64Binary?) as xs:base64Binary?`

- Description
Returns "bitwise exclusive or" applied between

`$a`

and`$b`

.If either argument is the empty sequence, an empty sequence is returned.

### binary:and

- Signature
`binary:and($a as xs:base64Binary?, $b as xs:base64Binary?) as xs:base64Binary?`

- Description
Returns "bitwise and" applied between

`$a`

and`$b`

.If either argument is the empty sequence, an empty sequence is returned.

### binary:not

- Signature
`binary:not($in as xs:base64Binary?) as xs:base64Binary?`

- Description
Returns "bitwise not" applied to

`$in`

.If the argument is the empty sequence, an empty sequence is returned.

### binary:shift

- Signature
`binary:shift($in as xs:base64Binary?, $by as xs:integer) as xs:integer`

- Description
If

`$by`

is positive then bits are shifted`$by`

times to the left.If

`$by`

is negative then bits are shifted`-$by`

times to the right.If

`$by`

is zero, the result is identical to`$in`

.If

`|$by|`

is greater than the bit-length of`$in`

then an all-zeros result, of the same length as`$in`

, is returned.`|$by|`

can be greater than 8, implying multi-byte shifts.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.