Difference between revisions of "Conversion Module"
Jump to navigation
Jump to search
Line 226: | Line 226: | ||
| | | | ||
* {{Code|convert:dayTime-to-integer(xs:dayTimeDuration('PT1S'))}} yields {{Code|1000}}. | * {{Code|convert:dayTime-to-integer(xs:dayTimeDuration('PT1S'))}} yields {{Code|1000}}. | ||
+ | |} | ||
+ | |||
+ | =Keys= | ||
+ | |||
+ | ==convert:decode-key== | ||
+ | |||
+ | {{Mark|Introduced with Version 9.4:}} | ||
+ | |||
+ | {| width='100%' | ||
+ | |- | ||
+ | | width='120' | '''Signatures''' | ||
+ | |{{Func|convert:decode-key|$key as xs:string|xs:string}}<br />{{Func|convert:decode-key|$key as xs:string, $lax as xs:boolean|xs:string}}<br /> | ||
+ | |- | ||
+ | | '''Summary''' | ||
+ | |Decodes the specified {{Code|$key}} to its original string representation, using the optional {{Code|$lax}} conversion method.<br />Keys supplied to this function are usually element names from documents that have been created with the [[JSON Module]] and the [[CSV Module]] and the {{Code|direct}} conversion format. | ||
+ | |- | ||
+ | | '''Examples''' | ||
+ | | | ||
+ | * <code>convert:decode-key('_0021'))</code> yields <code>!</code>. | ||
+ | * <code>json:doc("doc.json")//* ! convert:decode-key(name())</code> yields the original string representation of all names of a JSON document. | ||
+ | |} | ||
+ | |||
+ | ==convert:encode-key== | ||
+ | |||
+ | {{Mark|Introduced with Version 9.4:}} | ||
+ | |||
+ | {| width='100%' | ||
+ | |- | ||
+ | | width='120' | '''Signatures''' | ||
+ | |{{Func|convert:encode-key|$key as xs:string|xs:string}}<br />{{Func|convert:encode-key|$key as xs:string, $lax as xs:boolean|xs:string}}<br /> | ||
+ | |- | ||
+ | | '''Summary''' | ||
+ | |Encodes the specified {{Code|$key}} to a format that can be used to create an element node, using the optional {{Code|$lax}} conversion method.<br />The encoding is the same that is used in the [[JSON Module]] and the [[CSV Module]] and the {{Code|direct}} conversion format. | ||
+ | |- | ||
+ | | '''Examples''' | ||
+ | | | ||
+ | * <code>element { convert:encode-key("!") } { 'text' }</code> creates a new element with an encoded name key. | ||
|} | |} | ||
Line 251: | Line 288: | ||
=Changelog= | =Changelog= | ||
+ | |||
+ | ;Version 9.4 | ||
+ | |||
+ | * Added: [[#convert:name-to-key|convert:name-to-key]], [[#convert:key-to-name|convert:key-to-name]]. | ||
;Version 9.0 | ;Version 9.0 |
Revision as of 12:57, 14 April 2020
This XQuery Module contains functions to convert data between different formats.
Contents
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 $bytes (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($string as xs:string) as xs:base64Binary convert:string-to-base64($string as xs:string, $encoding as xs:string) as xs:base64Binary
|
Summary | Converts 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 | 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($string as xs:string) as xs:hexBinary convert:string-to-hex($string as xs:string, $encoding as xs:string) as xs:hexBinary
|
Summary | Converts 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 | binary : The input cannot be represented in the specified encoding.encoding : The specified encoding is invalid or not supported.
|
Examples |
|
Binary Data
convert:integers-to-base64
Signatures | convert:integers-to-base64($integers as xs:integer*) as xs:base64Binary
|
Summary | Converts the specified $integers to an item of type xs:base64Binary :
|
convert:integers-to-hex
Signatures | convert:integers-to-hex($integers as xs:integer*) as xs:hexBinary
|
Summary | Converts the specified $integers to an item of type xs:hexBinary :
|
convert:binary-to-integers
Signatures | convert:binary-to-integers($binary as xs:anyAtomicType) as xs:integer*
|
Summary | Returns the specified $binary (xs:base64Binary , xs:hexBinary ) as a sequence of unsigned integers (octets).
|
Examples |
|
convert:binary-to-bytes
Signatures | convert:binary-to-bytes($binary as xs:anyAtomicType) as xs:byte*
|
Summary | Returns 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 |
|
Numbers
convert:integer-to-base
Signatures | convert:integer-to-base($number as xs:integer, $base as xs:integer) as xs:string |
Summary | Converts $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 | base : The specified base is not in the range 2-36.
|
Examples |
|
convert:integer-from-base
Signatures | convert:integer-from-base($string as xs:string, $base as xs:integer) as xs:integer |
Summary | Decodes 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 | 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($milliseconds 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 $dateTime item to the number of milliseconds since 1 Jan 1970. |
Examples |
|
convert:integer-to-dayTime
Signatures | convert:integer-to-dayTime($milliseconds 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 $dayTime duration to milliseconds represented by an integer. |
Examples |
|
Keys
convert:decode-key
Signatures | convert:decode-key($key as xs:string) as xs:string convert:decode-key($key as xs:string, $lax as xs:boolean) as xs:string |
Summary | Decodes the specified $key to its original string representation, using the optional $lax conversion method.Keys supplied to this function are usually element names from documents that have been created with the JSON Module and the CSV Module and the direct conversion format.
|
Examples |
|
convert:encode-key
Signatures | convert:encode-key($key as xs:string) as xs:string convert:encode-key($key as xs:string, $lax as xs:boolean) as xs:string |
Summary | Encodes the specified $key to a format that can be used to create an element node, using the optional $lax conversion method.The encoding is the same that is used in the JSON Module and the CSV Module and the direct conversion format.
|
Examples |
|
Errors
Code | Description |
---|---|
base
|
The specified base is not in the range 2-36. |
binary
|
The input cannot be converted to a binary representation. |
encoding
|
The specified encoding is invalid or not supported. |
integer
|
The specified digit is not valid for the given range. |
string
|
The input is an invalid XML string, or the wrong encoding has been specified. |
Changelog
- Version 9.4
- Added: convert:name-to-key, convert:key-to-name.
- 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 fromxs:byte
toxs: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.
The module was introduced with Version 7.3. Some of the functions have been adopted from the obsolete Utility Module.