Main Page » XQuery » Functions » Conversion Functions

Conversion Functions

This module contains functions to convert data between different formats.

The following functions have been superseded by the Binary Functions, which are now part of the XQuery 4.0 standard:

BaseX 12	XQuery 4
`convert:binary-to-string`	`bin:decode-string`
`convert:string-to-base64`	`bin:encode-string`
`convert:string-to-hex`	`xs:hexBinary(bin:encode-string(...))`

Conventions

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

Binary Data

`convert:integers-to-base64`

Signature	convert:integers-to-base64( $input as xs:integer*) as xs:base64Binary
Summary	Converts the specified integer sequence `$input` to an item of type `xs:base64Binary`: Only the last 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( $input as xs:integer*) as xs:hexBinary
Summary	Converts the specified integer sequence `$input` to an item of type `xs:hexBinary`: Only the last 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( $value as (xs:base64Binary\|xs:hexBinary)) as xs:integer*
Summary	Returns the specified binary `$value` as a sequence of unsigned integers (octets).
Examples	`convert:binary-to-integers(xs:hexBinary('FF'))` Result: `255`

`convert:binary-to-bytes`

Signature

Signature	convert:binary-to-bytes( $value as (xs:base64Binary\|xs:hexBinary)) as xs:byte*
Summary	Returns the specified binary `$value` 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)`.

convert:binary-to-bytes(  $value  as (xs:base64Binary|xs:hexBinary)) as xs:byte*

Summary Returns the specified binary $value 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(  $value  as xs:integer,  $base   as xs:integer) as xs:string

Summary Converts the specified integer $value 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

base The 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(  $value  as xs:string,  $base   as xs:integer) as xs:integer

Summary Decodes an integer from the specified string $value, 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

`base`	The specified base is not in the range 2-36.
`integer`	The specified digit is not valid for the given base.

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

Signature	convert:integer-to-dateTime( $value as xs:integer) as xs:dateTimeStamp
Summary	Converts the specified number of milliseconds `$value` since 1 Jan 1970 to an item of type xs:dateTimeStamp.
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 time as an `xs:dateTimeStamp` item.

convert:integer-to-dateTime(  $value  as xs:integer) as xs:dateTimeStamp

Summary Converts the specified number of milliseconds $value since 1 Jan 1970 to an item of type xs:dateTimeStamp.

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 time as an xs:dateTimeStamp item.

`convert:dateTime-to-integer`

Signature

Signature	convert:dateTime-to-integer( $value as xs:dateTime) as xs:integer
Summary	Converts the specified dateTime `$value` to the number of milliseconds since 1 Jan 1970. A `FOCA0003` error is raised if the result is not representable as an `xs:integer`.
Examples	`convert:dateTime-to-integer(xs:dateTime('1970-01-01T00:00:00Z'))` Result: `0` `convert:dateTime-to-integer(xs:dateTime('292278994-08-17T07:12:55Z'))` Result: `9223372036854775000`. The most distant instant that can still be represented.

convert:dateTime-to-integer(  $value  as xs:dateTime) as xs:integer

Summary Converts the specified dateTime $value to the number of milliseconds since 1 Jan 1970. A FOCA0003 error is raised if the result is not representable as an xs:integer.

Examples

convert:dateTime-to-integer(xs:dateTime('1970-01-01T00:00:00Z'))

Result: 0

convert:dateTime-to-integer(xs:dateTime('292278994-08-17T07:12:55Z'))

Result: 9223372036854775000. The most distant instant that can still be represented.

`convert:integer-to-dayTime`

Signature	convert:integer-to-dayTime( $value as xs:integer) as xs:dayTimeDuration
Summary	Converts the specified number of milliseconds `$value` 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( $value as xs:dayTimeDuration) as xs:integer
Summary	Converts the specified dayTime duration `$value` 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, 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 not valid NCName characters are rewritten to an underscore and the character’s four-digit Unicode. For example, the exclamation mark ! is transformed to _0021.
With lax conversion enabled, 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.

`convert:encode-key`

Signature	convert:encode-key( $key as xs:string, $lax as xs:boolean? := false()) as xs:string
Summary	Encodes 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

Summary Decodes 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

key The 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

Code	Description
`base`	The specified base is not in the range 2-36.
`integer`	The specified digit is not valid for the given base.
`key`	The specified key cannot be decoded to its original representation.

Changelog

Version 13.0

Removed: convert:binary-to-string, convert:string-to-base64, convert:string-to-hex in favor of Binary Functions.

Version 9.4

Added: convert:encode-key, convert:decode-key.

Version 9.0

Added: convert:binary-to-integers.
Updated: convert:integers-to-base64, convert:integers-to-hex: Renamed from convert:bytes-to-base64; argument type relaxed from xs:byte to xs:integer.
Updated: error codes updated; 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.

Version 7.3

Added: New module added. Some of the functions have been adopted from the obsolete Utility Functions.

⚡Generated with XQuery

`/`	Jump to the search field
`?`	Show this list