Main Page » XQuery » Functions » Conversion Functions

Conversion Functions

This module contains functions to convert data between different formats.

Conventions

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

Signature
convert:binary-to-string(
  $bytes     as xs:anyAtomicType,
  $encoding  as xs:string?        := (),
  $fallback  as xs:boolean?       := false()
) as xs:string
SummaryConverts the specifed $bytes (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
encodingThe specified encoding is invalid or not supported.
stringThe input is an invalid XML string, or the wrong encoding has been specified.
Examples
convert:binary-to-string(xs:hexBinary('48656c6c6f576f726c64'))
Result: 'HelloWorld'

convert:string-to-base64

Signature
convert:string-to-base64(
  $string    as xs:string,
  $encoding  as xs:string?  := ()
) as xs:base64Binary
SummaryConverts the specified $string to an xs:base64Binary item. If the default encoding is chosen, conversion will be cheap, as strings and binaries are both internally represented as byte arrays. The UTF-8 default encoding can be overwritten with the optional $encoding argument.
Errors
binaryThe input cannot be converted to a binary representation.
encodingThe specified encoding is invalid or not supported.
Examples
string(convert:string-to-base64('HelloWorld'))
Result: 'SGVsbG9Xb3JsZA=='

convert:string-to-hex

Signature
convert:string-to-hex(
  $string    as xs:string,
  $encoding  as xs:string?  := ()
) as xs:hexBinary
SummaryConverts the specified $string to an xs:hexBinary item. If the default encoding is chosen, conversion will be cheap, as strings and binaries are both internally represented as byte arrays. The UTF-8 default encoding can be overwritten with the optional $encoding argument.
Errors
binaryThe input cannot be converted to a binary representation.
encodingThe specified encoding is invalid or not supported.
Examples
string(convert:string-to-hex('HelloWorld'))
Result: '48656C6C6F576F726C64'

Binary Data

convert:integers-to-base64

Signature
convert:integers-to-base64(
  $integers  as xs:integer*
) as xs:base64Binary
SummaryConverts the specified $integers to an item of type xs:base64Binary:
  • Only the first 8 bits of the supplied integers will be considered.
  • Conversion of byte sequences is very efficient, as items of binary type are internally represented as byte arrays.
Examples
convert:integers-to-base64(Q{java:java.lang.String}get-bytes('abc'))
Converts a byte sequence to a xs:base64Binary item.

convert:integers-to-hex

Signature
convert:integers-to-hex(
  $integers  as xs:integer*
) as xs:hexBinary
SummaryConverts the specified $integers to an item of type xs:hexBinary:
  • Only the first 8 bits of the supplied integers will be considered.
  • Conversion of byte sequences is very efficient, as items of binary type are internally represented as byte arrays.

convert:binary-to-integers

Signature
convert:binary-to-integers(
  $binary  as xs:anyAtomicType
) as xs:integer*
SummaryReturns the specified $binary (xs:base64Binary, xs:hexBinary) as a sequence of unsigned integers (octets).
Examples
convert:binary-to-integers(xs:hexBinary('FF'))
Result: 255

convert:binary-to-bytes

Signature
convert:binary-to-bytes(
  $binary  as xs:anyAtomicType
) as xs:byte*
SummaryReturns the specified $binary (xs:base64Binary, xs:hexBinary) as a sequence of bytes. The conversion is very cheap and takes no additional memory, as items of binary type are internally represented as byte arrays.
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).

Number

convert:integer-to-base

Signature
convert:integer-to-base(
  $number  as xs:integer,
  $base    as xs:integer
) as xs:string
SummaryConverts $number to a string, using the specified $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
baseThe specified base is not in the range 2-36.
Examples
convert:integer-to-base(-1, 16)
Result: 'ffffffffffffffff'
convert:integer-to-base(22, 5)
Result: '42'

convert:integer-from-base

Signature
convert:integer-from-base(
  $string  as xs:string,
  $base    as xs:integer
) as xs:integer
SummaryDecodes an integer from $string, using the specified $base. The first base elements of the sequence '0',..,'9','a',..,'z' are allowed as digits; case does not matter. Valid bases are 2 - 36. If the supplied string contains more than 64 bits of information, the result will be truncated.
Errors
baseThe specified base is not in the range 2-36.
integerThe specified digit is not valid for the given range.
Examples
convert:integer-from-base('ffffffffffffffff', 16)
Result: -1
convert:integer-from-base('CAFEBABE', 16)
Result: 3405691582
convert:integer-from-base('42', 5)
Result: 22
convert:integer-from-base(convert:integer-to-base(123, 7), 7)
Result: 123

Dates and Durations

convert:integer-to-dateTime

Signature
convert:integer-to-dateTime(
  $milliseconds  as xs:integer
) as xs:dateTime
SummaryConverts the specified number of $milliseconds since 1 Jan 1970 to an item of type xs:dateTime.
Examples
convert:integer-to-dateTime(0)
Result: xs:dateTime('1970-01-01T00:00:00Z')
convert:integer-to-dateTime(1234567890123)
Result: xs:dateTime('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

Signature
convert:dateTime-to-integer(
  $dateTime  as xs:dateTime
) as xs:integer
SummaryConverts the specified $dateTime item to the number of milliseconds since 1 Jan 1970.
Examples
convert:dateTime-to-integer(xs:dateTime('1970-01-01T00:00:00Z'))
Result: 0

convert:integer-to-dayTime

Signature
convert:integer-to-dayTime(
  $milliseconds  as xs:integer
) as xs:dayTimeDuration
SummaryConverts the specified number of $milliseconds to an item of type xs:dayTimeDuration.
Examples
convert:integer-to-dayTime(1234)
Result: xs:dayTimeDuration('PT1.234S')

convert:dayTime-to-integer

Signature
convert:dayTime-to-integer(
  $dayTime  as xs:dayTimeDuration
) as xs:integer
SummaryConverts the specified $dayTime duration to milliseconds represented by an integer.
Examples
convert:dayTime-to-integer(xs:dayTimeDuration('PT1S'))
Result: 1000

Keys

The key conversion is employed by the JSON Functions and the CSV Functions to encode strings to valid element names and back to the original representation:
  • If lax conversion is disabled, invalid characters are replaced with underscores or (when invalid as first character of an element name) prefixed with an underscore. The resulting string may be better readable, but it cannot necessarily be converted back to the original form.
  • With lax conversion enabled, a string is encoded to a valid NCName representation:
    • An empty string is converted to a single underscore (_).
    • Existing underscores are rewritten to two underscores (__).
    • Characters that are no valid NCName characters are rewritten to an underscore and the character’s four-digit Unicode. For example, the exclamation mark ? is transformed to _003f.

convert:encode-key

Signature
convert:encode-key(
  $key  as xs:string,
  $lax  as xs:boolean?  := false()
) as xs:string
SummaryEncodes the specified $key (with the optional $lax conversion method) to a valid NCName representation, which can be used to create an element node. This encoding is employed by the JSON Functions and the CSV Functions.
Examples
element { convert:encode-key("!") } { }
Creates a new element with an encoded name: <_0021/>.

convert:decode-key

Signature
convert:decode-key(
  $key  as xs:string,
  $lax  as xs:boolean?  := false()
) as xs:string
SummaryDecodes the specified $key (with the optional $lax conversion method) to the original string representation. Keys supplied to this function can be element names that have been created by the JSON Functions or CSV Functions.
Errors
keyThe specified key cannot be decoded to its original representation.
Examples
convert:decode-key(name(<_0021/>))
Result: '!'
json:doc("doc.json")//* ! convert:decode-key(name())
Yields the original string representation of all names of a JSON document.

Errors

CodeDescription
baseThe specified base is not in the range 2-36.
binaryThe input cannot be converted to a binary representation.
encodingThe specified encoding is invalid or not supported.
integerThe specified digit is not valid for the given range.
keyThe specified key cannot be decoded to its original representation.
stringThe input is an invalid XML string, or the wrong encoding has been specified.

Changelog

Version 9.4Version 9.0Version 8.5Version 7.5Version 7.3
  • Added: New module added. Some of the functions have been adopted from the obsolete Utility Functions.

⚡Generated with XQuery