Conversion Module

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

Conventions

All functions in this module are assigned to the http://basex.org/modules/convert namespace, which is statically bound to the convert prefix.
All errors are assigned to the http://basex.org/errors namespace, which is statically bound to the bxerr 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	BXCO0001: 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	BXCO0001: The input cannot be represented in the specified encoding. BXCO0002: 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	BXCO0001: The input cannot be represented in the specified encoding. BXCO0002: 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. Conversion of byte sequences is particularly cheap, as xs:base64Binary items are internally represented as byte arrays.
Errors	BXCO0001: 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. 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).

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	BXCO0004: 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	BXCO0004: The specified base is not in the range 2-36. BXCO0005: 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

Code	Description
BXCO0001	The input is an invalid XML string, or the wrong encoding has been specified.
BXCO0002	The specified encoding is invalid or not supported.
BXCO0003	The specified base is not in the range 2-36.
BXCO0004	The specified encoding is invalid or not supported.
BXCO0005	The specified digit is not valid for the given range.

Changelog

Version 8.7

• Updated: convert:bytes-to-base64, convert:bytes-to-hex: Argument type relaxed from xs:byte to xs:integer.

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.