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:binarytostring
Signatures

convert:binarytostring($bytes as xs:anyAtomicType) as xs:string
convert:binarytostring($bytes as xs:anyAtomicType, $encoding as xs:string) as xs:string
convert:binarytostring($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 UTF8 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:binarytostring(xs:hexBinary('48656c6c6f576f726c64')) yields HelloWorld .

convert:stringtobase64
Signatures

convert:stringtobase64($input as xs:string) as xs:base64Binary
convert:stringtobase64($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 UTF8 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:stringtobase64('HelloWorld')) yields SGVsbG9Xb3JsZA== .

convert:stringtohex
Signatures

convert:stringtohex($input as xs:string) as xs:hexBinary
convert:stringtohex($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 UTF8 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:stringtohex('HelloWorld')) yields 48656C6C6F576F726C64 .

Binary Data
convert:bytestobase64
Updated with Version 8.7: Argument type relaxed from xs:byte
to xs:integer
.
Signatures

convert:bytestobase64($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

BXCO0001 : The input cannot be represented in the specified encoding.
BXCO0002 : The specified encoding is invalid or not supported.

convert:bytestohex
Updated with Version 8.7: Argument type relaxed from xs:byte
to xs:integer
.
Signatures

convert:bytestohex($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:binarytobytes
Signatures

convert:binarytobytes($bin as xs:anyAtomicType) as xs:byte*

Summary

Returns the specified binary data (xs:base64Binary, xs:hexBinary) as a sequence of bytes.

Examples

convert:binarytobytes(xs:base64Binary('QmFzZVggaXMgY29vbA==')) yields the sequence (66, 97, 115, 101, 88, 32, 105, 115, 32, 99, 111, 111, 108) .
convert:binarytobytes(xs:hexBinary("4261736558")) yields the sequence (66 97 115 101 88) .

convert:binarytobytes
Introduced with Version 8.7:
Signatures

convert:binarytointeger($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:binarytointeger(xs:hexBinary('FF')) yields 255 .

Numbers
convert:integertobase
Signatures

convert:integertobase($num as xs:integer, $base as xs:integer) as xs:string

Summary

Converts $num to base $base , interpreting it as a 64bit 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 236.

Examples

convert:integertobase(1, 16) yields 'ffffffffffffffff' .
convert:integertobase(22, 5) yields '42' .

convert:integerfrombase
Signatures

convert:integerfrombase($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 236.
BXCO0005 : The specified digit is not valid for the given range.

Examples

convert:integerfrombase('ffffffffffffffff', 16) yields 1 .
convert:integerfrombase('CAFEBABE', 16) yields 3405691582 .
convert:integerfrombase('42', 5) yields 22 .
convert:integerfrombase(convert:integertobase(123, 7), 7) yields 123 .

Dates and Durations
convert:integertodateTime
Signatures

convert:integertodateTime($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:integertodateTime(0) yields 19700101T00:00:00Z .
convert:integertodateTime(1234567890123) yields 20090213T23:31:30.123Z .
convert:integertodateTime(prof:currentms()) returns the current miliseconds in the xs:dateTime format.

convert:dateTimetointeger
Signatures

convert:dateTimetointeger($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:dateTimetointeger(xs:dateTime('19700101T00:00:00Z')) yields 0 .

convert:integertodayTime
Signatures

convert:integertodayTime($ms as xs:integer) as xs:dayTimeDuration

Summary

Converts the specified number of milliseconds to an item of type xs:dayTimeDuration.

Examples

convert:integertodayTime(1234) yields PT1.234S .

convert:dayTimetointeger
Signatures

convert:dayTimetointeger($dayTime as xs:dayTimeDuration) as xs:integer

Summary

Converts the specified item of type xs:dayTimeDuration to milliseconds represented by an integer.

Examples

convert:dayTimetointeger(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 236.

BXCO0004

The specified encoding is invalid or not supported.

BXCO0005

The specified digit is not valid for the given range.

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