Binary Module

1 Status of this document

This document is in an early draft stage. Comments are welcomed at public-expath@w3.org mailing list (archive).

2 Introduction

3 Use cases

Development of this specification was driven strictly by requirements which XML developer regularly faces.

Some typical use cases:

• Getting dimensions of an image file.

• Extracting image metadata.

• Processing images embeded and base64 encoded inside SOAP message.

• Processing legacy text file which uses several different encodings in different places.

4 Loading binary data

Summary

The bin:unparsed-binary function reads an external resource (for example, an image file) and returns a binary data of the resource.

Signature

bin:unparsed-binary($href as xs:string?) as xs:hexBinary?

Rules

The $href argument must be a string in the form of a URI reference, which must contain no fragment identifier, and must identify a resource for which a string representation is available. If the URI is a relative URI reference, then it is resolved relative to the Static Base URI property from the static context.

If the value of the $href argument is an empty sequence, the function returns an empty sequence.

The result of the function is a binary value of the resource retrieved using the URI.

Examples

Converting external images in HTML document into internal data: resources:

<xsl:template match="img[ends-with(@src, '.jpg')]">
   <xsl:copy>
      <xsl:copy-of select="@* except @src"/>
      <xsl:attribute name="src">
         <xsl:text>data:image/jpeg;base64,</xsl:text>
         <xsl:value-of select="xs:base64Binary(bin:unparsed-binary(resolve-uri(@src)))"/>
      </xsl:attribute>
   </xsl:copy>
</xsl:template>

5 Basic operations

Summary

The bin:binary-subsequence functions returns specified part of binary data.

Signature

bin:binary-subsequence($in     as xs:hexBinary,
                       $offset as xs:integer,
                       $size   as xs:integer) as xs:hexBinary

Rules

Returns part of original binary data starting at $offset. Size of returned data is $size octets.

The $offset is zero based.

The value of $offset argument must be non-negative integer.

It is dynamic error if $offset + $size is larger then size of binary data passed in $in argument.

Examples

Testing whether $data variable contains content of PDF file:

bin:binary-subsequence($data, 0, 4) eq xs:hexBinary("25504446")

25504446 is magic number for PDF files, it is US-ASCII encoded value for %PDF.

Summary

The bin:binary-length functions returns size of binary data.

Signature

bin:binary-length($in as xs:hexBinary) as xs:integer

Rules

Returns size of binary data in octets.

Summary

Returns a binary data created by concatenating the binary data items in a sequence.

Signature

bin:binary-join($in as xs:hexBinary*) as xs:hexBinary

Rules

The function returns an xs:hexBinary created by concatenating the items in the sequence $in, in order.

Notes

If the value of $in is the empty sequence, the function returns the zero-length binary data.

Summary

Returns binary data as a sequence of octets.

Signature

bin:binary-to-octets($in as xs:hexBinary) as xs:integer*

Rules

If $in is zero length binary data then empty sequence is returned.

Octets are returned as integers from 0 to 255.

Summary

Converts sequence of octets into binary data.

Signature

bin:octets-to-binary($in as xs:integer*) as xs:hexBinary

Rules

Octets are integers from 0 to 255.

6 Text decoding and encoding

Summary

Decodes binary data as a string in a given encoding.

Signature

bin:decode-string($in       as xs:hexBinary,
                  $encoding as xs:string) as xs:string

Rules

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.

Summary

Decodes chunk of binary data at a specified offset as a string in a given encoding.

Signature

bin:unpack-string($in       as xs:hexBinary,
                  $offset   as xs:integer,
                  $size     as xs:integer,
                  $encoding as xs:string) as xs:string

Rules

If $size is greater then 0 this function is identical to calling bin:decode-string(bin:binary-subsequence($in, $offset, $size), $encoding).

If $size is zero then all non-zero octets starting at $offset until first zero octet are extracted and then decoding is applied. This way zero-terminated strings can be easily decoded.

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.

Summary

Encodes string into binary data using a given encoding.

Signature

bin:encode-string($in       as xs:string,
                  $encoding as xs:string) as xs:hexBinary

Rules

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.

7 Packing and unpacking of encoded numeric values

Summary

Extract double value stored at the particular offset in binary data.

Signatures

bin:unpack-double($in     as xs:hexBinary,
                  $offset as xs:integer) as xs:double

bin:unpack-double($in        as xs:hexBinary,
                  $offset    as xs:integer,
                  $bigendian as xs:boolean) as xs:double

Rules

Little endian number representation is assumed unless $bigendian parameter is specified and has true() value.

The $offset is zero based.

Summary

Extract float value stored at the particular offset in binary data.

Signatures

bin:unpack-float($in     as xs:hexBinary,
                 $offset as xs:integer) as xs:float

bin:unpack-float($in        as xs:hexBinary,
                 $offset    as xs:integer,
                 $bigendian as xs:boolean) as xs:float

Rules

Little endian number representation is assumed unless $bigendian parameter is specified and has true() value.

The $offset is zero based.

Summary

Extract long (64-bit signed integer) value stored at the particular offset in binary data.

Signatures

bin:unpack-long($in     as xs:hexBinary,
                $offset as xs:integer) as xs:long

bin:unpack-long($in        as xs:hexBinary,
                $offset    as xs:integer,
                $bigendian as xs:boolean) as xs:long

Rules

Little endian number representation is assumed unless $bigendian parameter is specified and has true() value.

The $offset is zero based.

Summary

Extract unsignedLong (64-bit unsigned integer) value stored at the particular offset in binary data.

Signatures

bin:unpack-unsignedLong($in     as xs:hexBinary,
                        $offset as xs:integer) as xs:unsignedLong

bin:unpack-unsignedLong($in        as xs:hexBinary,
                        $offset    as xs:integer,
                        $bigendian as xs:boolean) as xs:unsignedLong

Rules

Little endian number representation is assumed unless $bigendian parameter is specified and has true() value.

The $offset is zero based.

Summary

Extract int (32-bit signed integer) value stored at the particular offset in binary data.

Signatures

bin:unpack-int($in     as xs:hexBinary,
               $offset as xs:integer) as xs:int

bin:unpack-int($in        as xs:hexBinary,
               $offset    as xs:integer,
               $bigendian as xs:boolean) as xs:int

Rules

Little endian number representation is assumed unless $bigendian parameter is specified and has true() value.

The $offset is zero based.

Summary

Extract unsignedInt (32-bit unsigned integer) value stored at the particular offset in binary data.

Signatures

bin:unpack-unsignedInt($in     as xs:hexBinary,
                       $offset as xs:integer) as xs:unsignedInt

bin:unpack-unsignedInt($in        as xs:hexBinary,
                       $offset    as xs:integer,
                       $bigendian as xs:boolean) as xs:unsignedInt

Rules

Little endian number representation is assumed unless $bigendian parameter is specified and has true() value.

The $offset is zero based.

Summary

Extract short (16-bit signed integer) value stored at the particular offset in binary data.

Signatures

bin:unpack-short($in     as xs:hexBinary,
                 $offset as xs:integer) as xs:short

bin:unpack-short($in        as xs:hexBinary,
                 $offset    as xs:integer,
                 $bigendian as xs:boolean) as xs:short

Rules

Little endian number representation is assumed unless $bigendian parameter is specified and has true() value.

The $offset is zero based.

Summary

Extract unsignedShort (16-bit unsigned integer) value stored at the particular offset in binary data.

Signatures

bin:unpack-unsignedShort($in     as xs:hexBinary,
                         $offset as xs:integer) as xs:unsignedShort

bin:unpack-unsignedShort($in        as xs:hexBinary,
                         $offset    as xs:integer,
                         $bigendian as xs:boolean) as xs:unsignedShort

Rules

Little endian number representation is assumed unless $bigendian parameter is specified and has true() value.

The $offset is zero based.

Summary

Extract byte (8-bit signed integer) value stored at the particular offset in binary data.

Signature

bin:unpack-byte($in     as xs:hexBinary,
                $offset as xs:integer) as xs:byte

Rules

The $offset is zero based.

Summary

Extract unsignedByte (8-bit unsigned integer) value stored at the particular offset in binary data.

Signature

bin:unpack-unsignedByte($in     as xs:hexBinary,
                        $offset as xs:integer) as xs:unsignedByte

Rules

The $offset is zero based.

Summary

Returns binary representation of a double value.

Signatures

bin:pack-double($in as xs:double) as xs:hexBinary

bin:pack-double($in        as xs:double,
                $bigendian as xs:boolean) as xs:hexBinary

Rules

Little endian number representation is assumed unless $bigendian parameter is specified and has true() value.

Summary

Returns binary representation of a float value.

Signatures

bin:pack-float($in as xs:float) as xs:hexBinary

bin:pack-float($in        as xs:float,
               $bigendian as xs:boolean) as xs:hexBinary

Rules

Little endian number representation is assumed unless $bigendian parameter is specified and has true() value.

Summary

Returns binary representation of a long value.

Signatures

bin:pack-long($in as xs:long) as xs:hexBinary

bin:pack-long($in        as xs:long,
              $bigendian as xs:boolean) as xs:hexBinary

Rules

Little endian number representation is assumed unless $bigendian parameter is specified and has true() value.

Summary

Returns binary representation of an unsignedLong (64-bit unsigned integer) value.

Signatures

bin:pack-unsignedLong($in as xs:unsignedLong) as xs:hexBinary

bin:pack-unsignedLong($in        as xs:unsignedLong,
                      $bigendian as xs:boolean) as xs:hexBinary

Rules

Little endian number representation is assumed unless $bigendian parameter is specified and has true() value.

Summary

Returns binary representation of an int (32-bit signed integer) value.

Signatures

bin:pack-int($in as xs:int) as xs:hexBinary

bin:pack-int($in        as xs:int,
             $bigendian as xs:boolean) as xs:hexBinary

Rules

Little endian number representation is assumed unless $bigendian parameter is specified and has true() value.

Summary

Returns binary representation of an unsignedInt (32-bit unsigned integer) value.

Signatures

bin:pack-unsignedInt($in as xs:unsignedInt) as xs:hexBinary

bin:pack-unsignedInt($in        as xs:unsignedInt,
                     $bigendian as xs:boolean) as xs:hexBinary

Rules

Little endian number representation is assumed unless $bigendian parameter is specified and has true() value.

Summary

Returns binary representation of a short (16-bit signed integer) value.

Signatures

bin:pack-short($in as xs:short) as xs:hexBinary

bin:pack-short($in        as xs:short,
               $bigendian as xs:boolean) as xs:hexBinary

Rules

Little endian number representation is assumed unless $bigendian parameter is specified and has true() value.

Summary

Returns binary representation of an unsignedShort (16-bit unsigned integer) value.

Signatures

bin:pack-unsignedShort($in as xs:unsignedShort) as xs:hexBinary

bin:pack-unsignedShort($in        as xs:unsignedShort,
                       $bigendian as xs:boolean) as xs:hexBinary

Rules

Little endian number representation is assumed unless $bigendian parameter is specified and has true() value.

Summary

Returns binary representation of a byte (8-bit signed integer) value.

Signature

bin:pack-byte($in as xs:byte) as xs:hexBinary

Rules

Summary

Returns binary representation of an unsignedByte (8-bit unsigned integer) value.

Signature

bin:pack-unsignedByte($in as xs:unsignedByte) as xs:hexBinary

Rules

8 Bitwise operations

Summary

Returns "bitwise or" applied on arguments.

Signature

bin:binary-or($a as xs:hexBinary,
              $b as xs:hexBinary) as xs:hexBinary

Rules

Returns "bitwise or" applied on $a and $b.

If $a and $b do not have same length then shorter is padded with zero octets to match size of a longer argument.

Summary

Returns "bitwise xor" applied on arguments.

Signature

bin:binary-xor($a as xs:hexBinary,
               $b as xs:hexBinary) as xs:hexBinary

Rules

Returns "bitwise exclusive or" applied on $a and $b.

If $a and $b do not have same length then shorter is padded with zero octets to match size of a longer argument.

Summary

Returns "bitwise and" applied on arguments.

Signature

bin:binary-and($a as xs:hexBinary,
               $b as xs:hexBinary) as xs:hexBinary

Rules

Returns "bitwise and" applied on $a and $b.

If $a and $b do not have same length then shorter is padded with zero octets to match size of a longer argument.

Summary

Returns "bitwise not" of an argument.

Signature

bin:binary-and($in as xs:hexBinary) as xs:hexBinary

Rules

Returns "bitwise not" applied on $in argument.

Summary

Shift bits in binary data.

Signature

bin:binary-shift($in as xs:hexBinary,
                 $by as xs:integer) as xs:hexBinary

Rules

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 result is identical to $in argument.

Result has always the same size as $in argument.

Shift is logical, zeros are placed into discarded bits.

9 Serialization

New serialization method bin:binary is defined. It can serialize sequence containing only items of type xs:hexBinary or xs:base64Binary. Such sequence is turned into one block of binary data using bin:binary-join and written out to the specified location.

Examples

Joining several blobs of data into a single file:

<xsl:result-document href="image.png" method="bin:binary">
   <xsl:sequence select="$image-header"/>
   <xsl:sequence select="$image-data"/>
</xsl:result-document>

Template for extracting HTML images represented as data: URI scheme into separate external image files:

<xsl:template match="img[starts-with(@src, 'data:image/png;base64,')]">
   <xsl:copy>
      <xsl:copy-of select="@* except @src"/>
      <xsl:attribute name="src" select="concat(generate-id(), '.png')"/>
      <xsl:result-document href="{generate-id()}.png" method="bin:binary">
         <xsl:sequence select="xs:base64Binary(substring-after(@src, 'data:image/png;base64,'))"/>
      </xsl:result-document>
   </xsl:copy>
</xsl:template>