Conversion Module

This XQuery Module contains functions to convert data between different formats.

Conventions

Template:Mark:

All functions and errors in this module are assigned to the http://basex.org/modules/convert namespace, which is statically bound to the convert prefix.

Strings

convert:binary-to-string

Signatures	convert:binary-to-string($bytes as xs:anyAtomicType) as xs:string convert:binary-to-string($bytes as xs:anyAtomicType, $encoding as xs:string) as xs:string convert:binary-to-string($bytes as xs:anyAtomicType, $encoding as xs:string, $fallback as xs:boolean) as xs:string
Summary	Converts the specifed binary data (xs:base64Binary, xs:hexBinary) to a string: The UTF-8 default encoding can be overwritten with the optional $encoding argument. By default, invalid characters will be rejected. If $fallback is set to true, these characters will be replaced with the Unicode replacement character FFFD (�).
Errors	string: The input is an invalid XML string, or the wrong encoding has been specified. BXCO0002: The specified encoding is invalid or not supported.
Examples	convert:binary-to-string(xs:hexBinary('48656c6c6f576f726c64')) yields HelloWorld.

convert:string-to-base64

Signatures	convert:string-to-base64($input as xs:string) as xs:base64Binary convert:string-to-base64($input as xs:string, $encoding as xs:string) as xs:base64Binary
Summary	Converts the specified string to a xs:base64Binary item. If the default encoding is chosen, conversion will be cheap, as both xs:string and xs:base64Binary items are internally represented as byte arrays. The UTF-8 default encoding can be overwritten with the optional $encoding argument.
Errors	binary: The input cannot be represented in the specified encoding. encoding: The specified encoding is invalid or not supported.
Examples	string(convert:string-to-base64('HelloWorld')) yields SGVsbG9Xb3JsZA==.

convert:string-to-hex

Signatures	convert:string-to-hex($input as xs:string) as xs:hexBinary convert:string-to-hex($input as xs:string, $encoding as xs:string) as xs:hexBinary
Summary	Converts the specified string to a xs:hexBinary item. If the default encoding is chosen, conversion will be cheap, as both xs:string and xs:hexBinary items are internally represented as byte arrays. The UTF-8 default encoding can be overwritten with the optional $encoding argument.
Errors	binary: The input cannot be represented in the specified encoding. encoding: The specified encoding is invalid or not supported.
Examples	string(convert:string-to-hex('HelloWorld')) yields 48656C6C6F576F726C64.

Binary Data

convert:bytes-to-base64

Template:Mark: Argument type relaxed from xs:byte to xs:integer.

Signatures	convert:bytes-to-base64($input as xs:integer*) as xs:base64Binary
Summary	Converts the specified integer sequence to a xs:base64Binary item: Only the first 8 bits of the supplied integer values will be considered. Conversion of byte sequences is particularly cheap, as xs:base64Binary items are internally represented as byte arrays.
Errors	binary: The input cannot be represented in the specified encoding. BXCO0002: The specified encoding is invalid or not supported.

convert:bytes-to-hex

Template:Mark: Argument type relaxed from xs:byte to xs:integer.

Signatures	convert:bytes-to-hex($input as xs:integer*) as xs:hexBinary
Summary	Converts the specified integer sequence to a xs:hexBinary item: Only the first 8 bits of the supplied integer values will be considered. Conversion of byte sequences is particularly cheap, as xs:hexBinary items are internally represented as byte arrays.

convert:binary-to-bytes

Signatures	convert:binary-to-bytes($bin as xs:anyAtomicType) as xs:byte*
Summary	Returns the specified binary data (xs:base64Binary, xs:hexBinary) as a sequence of bytes.
Examples	convert:binary-to-bytes(xs:base64Binary('QmFzZVggaXMgY29vbA==')) yields the sequence (66, 97, 115, 101, 88, 32, 105, 115, 32, 99, 111, 111, 108). convert:binary-to-bytes(xs:hexBinary("4261736558")) yields the sequence (66 97 115 101 88).

convert:binary-to-integer

Template:Mark:

Signatures	convert:binary-to-integer($bin as xs:anyAtomicType) as xs:integer*
Summary	Returns the specified binary data (xs:base64Binary, xs:hexBinary) as a sequence of unsigned integers (octets).
Examples	convert:binary-to-integer(xs:hexBinary('FF')) yields 255.

Numbers

convert:integer-to-base

Signatures	convert:integer-to-base($num as xs:integer, $base as xs:integer) as xs:string
Summary	Converts $num to base $base, interpreting it as a 64-bit unsigned integer. The first $base elements of the sequence '0',..,'9','a',..,'z' are used as digits. Valid bases are 2, .., 36.
Errors	base: The specified base is not in the range 2-36.
Examples	convert:integer-to-base(-1, 16) yields 'ffffffffffffffff'. convert:integer-to-base(22, 5) yields '42'.

convert:integer-from-base

Signatures	convert:integer-from-base($str as xs:string, $base as xs:integer) as xs:integer
Summary	Decodes an xs:integer from $str, assuming that it's encoded in base $base. The first $base elements of the sequence '0',..,'9','a',..,'z' are allowed as digits, case doesn't matter. Valid bases are 2 - 36. If $str contains more than 64 bits of information, the result is truncated arbitarily.
Errors	base: The specified base is not in the range 2-36. integer: The specified digit is not valid for the given range.
Examples	convert:integer-from-base('ffffffffffffffff', 16) yields -1. convert:integer-from-base('CAFEBABE', 16) yields 3405691582. convert:integer-from-base('42', 5) yields 22. convert:integer-from-base(convert:integer-to-base(123, 7), 7) yields 123.

Dates and Durations

convert:integer-to-dateTime

Signatures	convert:integer-to-dateTime($ms as xs:integer) as xs:dateTime
Summary	Converts the specified number of milliseconds since 1 Jan 1970 to an item of type xs:dateTime.
Examples	convert:integer-to-dateTime(0) yields 1970-01-01T00:00:00Z. convert:integer-to-dateTime(1234567890123) yields 2009-02-13T23:31:30.123Z. convert:integer-to-dateTime(prof:current-ms()) returns the current miliseconds in the xs:dateTime format.

convert:dateTime-to-integer

Signatures	convert:dateTime-to-integer($dateTime as xs:dateTime) as xs:integer
Summary	Converts the specified item of type xs:dateTime to the number of milliseconds since 1 Jan 1970.
Examples	convert:dateTime-to-integer(xs:dateTime('1970-01-01T00:00:00Z')) yields 0.

convert:integer-to-dayTime

Signatures	convert:integer-to-dayTime($ms as xs:integer) as xs:dayTimeDuration
Summary	Converts the specified number of milliseconds to an item of type xs:dayTimeDuration.
Examples	convert:integer-to-dayTime(1234) yields PT1.234S.

convert:dayTime-to-integer

Signatures	convert:dayTime-to-integer($dayTime as xs:dayTimeDuration) as xs:integer
Summary	Converts the specified item of type xs:dayTimeDuration to milliseconds represented by an integer.
Examples	convert:dayTime-to-integer(xs:dayTimeDuration('PT1S')) yields 1000.

Errors

Template:Mark:

Code	Description
string	The input is an invalid XML string, or the wrong encoding has been specified.
binary	The input cannot be converted to a binary representation.
encoding	The specified encoding is invalid or not supported.
base	The specified base is not in the range 2-36.
integer	The specified digit is not valid for the given range.

Changelog

Version 9.0

• Added: convert:bytes-to-integer.
• Updated: convert:bytes-to-base64, convert:bytes-to-hex: Argument type relaxed from xs:byte to xs:integer.
• Updated: error codes updates; errors now use the module namespace

Version 8.5

• Updated: convert:binary-to-string: $fallback argument added.

Version 7.5

• Added: convert:integer-to-dateTime, convert:dateTime-to-integer, convert:integer-to-dayTime, convert:dayTime-to-integer.

The module was introduced with Version 7.3. Some of the functions have been adopted from the obsolete Utility Module.