Difference between revisions of "Conversion Module"
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 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| | + | |{{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| | + | |{{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| | + | |{{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| | + | |{{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| | + | |{{Error|base|#Errors}} The specified base is not in the range 2-36. |
|- | |- | ||
| '''Examples''' | | '''Examples''' | ||
Line 164: | Line 165: | ||
|- | |- | ||
| '''Errors''' | | '''Errors''' | ||
− | |{{Error| | + | |{{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| | + | |{{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| | + | |{{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| | + | |{{Code|base}} |
|The specified base is not in the range 2-36. | |The specified base is not in the range 2-36. | ||
|- | |- | ||
− | |{{Code| | + | |{{Code|integer}} |
− | |||
− | |||
− | |||
|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
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:
|
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: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 |
|
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 |
|
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:
|
Errors | binary : 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:
|
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-integer
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 |
|
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-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 |
|
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: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: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: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 |
|
Errors
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
- Added: convert:bytes-to-integer.
- Updated: convert:bytes-to-base64, convert:bytes-to-hex: Argument type relaxed from
xs:byte
toxs:integer
. - Updated: error codes updates; 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.
The module was introduced with Version 7.3. Some of the functions have been adopted from the obsolete Utility Module.