Difference between revisions of "Conversion Module"

From BaseX Documentation
Jump to navigation Jump to search
Line 3: Line 3:
 
=Conventions=
 
=Conventions=
  
All functions in this module are assigned to the <code><nowiki>http://basex.org/modules/convert</nowiki></code> namespace, which is statically bound to the {{Code|convert}} prefix.<br/>
+
{{Mark|Updated with Version 9.0}}:
All errors are assigned to the <code><nowiki>http://basex.org/errors</nowiki></code> namespace, which is statically bound to the {{Code|bxerr}} prefix.
+
 
 +
All functions and errors in this module are assigned to the <code><nowiki>http://basex.org/modules/convert</nowiki></code> namespace, which is statically bound to the {{Code|convert}} prefix.<br/>
  
 
=Strings=
 
=Strings=
Line 21: Line 22:
 
|-
 
|-
 
| '''Errors'''
 
| '''Errors'''
|{{Error|BXCO0001|#Errors}} The input is an invalid XML string, or the wrong encoding has been specified.<br/>{{Error|BXCO0002|#Errors}} The specified encoding is invalid or not supported.
+
|{{Error|string|#Errors}} The input is an invalid XML string, or the wrong encoding has been specified.<br/>{{Error|BXCO0002|#Errors}} The specified encoding is invalid or not supported.
 
|-
 
|-
 
| '''Examples'''
 
| '''Examples'''
Line 39: Line 40:
 
|-
 
|-
 
| '''Errors'''
 
| '''Errors'''
|{{Error|BXCO0001|#Errors}} The input cannot be represented in the specified encoding.<br/>{{Error|BXCO0002|#Errors}} The specified encoding is invalid or not supported.
+
|{{Error|binary|#Errors}} The input cannot be represented in the specified encoding.<br/>{{Error|encoding|#Errors}} The specified encoding is invalid or not supported.
 
|-
 
|-
 
| '''Examples'''
 
| '''Examples'''
Line 57: Line 58:
 
|-
 
|-
 
| '''Errors'''
 
| '''Errors'''
|{{Error|BXCO0001|#Errors}} The input cannot be represented in the specified encoding.<br/>{{Error|BXCO0002|#Errors}} The specified encoding is invalid or not supported.
+
|{{Error|binary|#Errors}} The input cannot be represented in the specified encoding.<br/>{{Error|encoding|#Errors}} The specified encoding is invalid or not supported.
 
|-
 
|-
 
| '''Examples'''
 
| '''Examples'''
Line 81: Line 82:
 
|-
 
|-
 
| '''Errors'''
 
| '''Errors'''
|{{Error|BXCO0001|#Errors}} The input cannot be represented in the specified encoding.<br/>{{Error|BXCO0002|#Errors}} The specified encoding is invalid or not supported.
+
|{{Error|binary|#Errors}} The input cannot be represented in the specified encoding.<br/>{{Error|BXCO0002|#Errors}} The specified encoding is invalid or not supported.
 
|}
 
|}
  
Line 145: Line 146:
 
|-
 
|-
 
| '''Errors'''
 
| '''Errors'''
|{{Error|BXCO0004|#Errors}} The specified base is not in the range 2-36.
+
|{{Error|base|#Errors}} The specified base is not in the range 2-36.
 
|-
 
|-
 
| '''Examples'''
 
| '''Examples'''
Line 164: Line 165:
 
|-
 
|-
 
| '''Errors'''
 
| '''Errors'''
|{{Error|BXCO0004|#Errors}} The specified base is not in the range 2-36.<br/>{{Error|BXCO0005|#Errors}} The specified digit is not valid for the given range.
+
|{{Error|base|#Errors}} The specified base is not in the range 2-36.<br/>{{Error|integer|#Errors}} The specified digit is not valid for the given range.
 
|-
 
|-
 
| '''Examples'''
 
| '''Examples'''
Line 239: Line 240:
  
 
=Errors=
 
=Errors=
 +
 +
{{Mark|Updated with Version 9.0}}:
  
 
{| class="wikitable" width="100%"
 
{| class="wikitable" width="100%"
Line 244: Line 247:
 
| Description
 
| Description
 
|-
 
|-
|{{Code|BXCO0001}}
+
|{{Code|string}}
 
|The input is an invalid XML string, or the wrong encoding has been specified.
 
|The input is an invalid XML string, or the wrong encoding has been specified.
 
|-
 
|-
|{{Code|BXCO0002}}
+
|{{Code|binary}}
 +
|The input cannot be converted to a binary representation.
 +
|-
 +
|{{Code|encoding}}
 
|The specified encoding is invalid or not supported.
 
|The specified encoding is invalid or not supported.
 
|-
 
|-
|{{Code|BXCO0003}}
+
|{{Code|base}}
 
|The specified base is not in the range 2-36.
 
|The specified base is not in the range 2-36.
 
|-
 
|-
|{{Code|BXCO0004}}
+
|{{Code|integer}}
|The specified encoding is invalid or not supported.
 
|-
 
|{{Code|BXCO0005}}
 
 
|The specified digit is not valid for the given range.
 
|The specified digit is not valid for the given range.
 
|}
 
|}
Line 266: Line 269:
 
* Added: [[#convert:bytes-to-integer|convert:bytes-to-integer]].
 
* Added: [[#convert:bytes-to-integer|convert:bytes-to-integer]].
 
* Updated: [[#convert:bytes-to-base64|convert:bytes-to-base64]], [[#convert:bytes-to-hex|convert:bytes-to-hex]]: Argument type relaxed from {{Code|xs:byte}} to {{Code|xs:integer}}.
 
* Updated: [[#convert:bytes-to-base64|convert:bytes-to-base64]], [[#convert:bytes-to-hex|convert:bytes-to-hex]]: Argument type relaxed from {{Code|xs:byte}} to {{Code|xs:integer}}.
 +
* Updated: error codes updates; errors now use the module namespace
  
 
;Version 8.5
 
;Version 8.5

Revision as of 11:07, 21 November 2017

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

Conventions

Updated with Version 9.0:

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

Updated with Version 9.0: 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

Updated with Version 9.0: 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

Introduced with Version 9.0:

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

Updated with Version 9.0:

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
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.