Difference between revisions of "Conversion Module"
Jump to navigation
Jump to search
(→Keys) |
|||
(25 intermediate revisions by the same user not shown) | |||
Line 10: | Line 10: | ||
{| width='100%' | {| width='100%' | ||
− | |- | + | |- valign="top" |
− | | width='120' | ''' | + | | width='120' | '''Signature''' |
− | | | + | |<pre>convert:binary-to-string( |
− | |- | + | $bytes as xs:anyAtomicType, |
+ | $encoding as xs:string := (), | ||
+ | $fallback as xs:boolean? := false() | ||
+ | ) as xs:string</pre> | ||
+ | |- valign="top" | ||
| '''Summary''' | | '''Summary''' | ||
|Converts the specifed {{Code|$bytes}} ({{Code|xs:base64Binary}}, {{Code|xs:hexBinary}}) to a string: | |Converts the specifed {{Code|$bytes}} ({{Code|xs:base64Binary}}, {{Code|xs:hexBinary}}) to a string: | ||
* The UTF-8 default encoding can be overwritten with the optional {{Code|$encoding}} argument. | * The UTF-8 default encoding can be overwritten with the optional {{Code|$encoding}} argument. | ||
* By default, invalid characters will be rejected. If {{Code|$fallback}} is set to true, these characters will be replaced with the Unicode replacement character <code>FFFD</code> (�). | * By default, invalid characters will be rejected. If {{Code|$fallback}} is set to true, these characters will be replaced with the Unicode replacement character <code>FFFD</code> (�). | ||
− | |- | + | |- valign="top" |
| '''Errors''' | | '''Errors''' | ||
|{{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. | |{{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. | ||
− | |- | + | |- valign="top" |
| '''Examples''' | | '''Examples''' | ||
| | | | ||
Line 30: | Line 34: | ||
{| width='100%' | {| width='100%' | ||
− | |- | + | |- valign="top" |
− | | width='120' | ''' | + | | width='120' | '''Signature''' |
− | | | + | |<pre>convert:string-to-base64( |
− | |- | + | $string as xs:string, |
+ | $encoding as xs:string := () | ||
+ | ) as xs:base64Binary</pre> | ||
+ | |- valign="top" | ||
| '''Summary''' | | '''Summary''' | ||
|Converts the specified {{Code|$string}} to an {{Code|xs:base64Binary}} item. If the default encoding is chosen, conversion will be cheap, as strings and binaries are both internally represented as byte arrays.<br/>The UTF-8 default encoding can be overwritten with the optional {{Code|$encoding}} argument. | |Converts the specified {{Code|$string}} to an {{Code|xs:base64Binary}} item. If the default encoding is chosen, conversion will be cheap, as strings and binaries are both internally represented as byte arrays.<br/>The UTF-8 default encoding can be overwritten with the optional {{Code|$encoding}} argument. | ||
− | |- | + | |- valign="top" |
| '''Errors''' | | '''Errors''' | ||
|{{Error|binary|#Errors}} The input cannot be represented in the specified encoding.<br/>{{Error|encoding|#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. | ||
− | |- | + | |- valign="top" |
| '''Examples''' | | '''Examples''' | ||
| | | | ||
Line 48: | Line 55: | ||
{| width='100%' | {| width='100%' | ||
− | |- | + | |- valign="top" |
− | | width='120' | ''' | + | | width='120' | '''Signature''' |
− | | | + | |<pre>convert:string-to-hex( |
− | |- | + | $string as xs:string, |
+ | $encoding as xs:string := () | ||
+ | ) as xs:hexBinary</pre> | ||
+ | |- valign="top" | ||
| '''Summary''' | | '''Summary''' | ||
|Converts the specified {{Code|$string}} to an {{Code|xs:hexBinary}} item. If the default encoding is chosen, conversion will be cheap, as strings and binaries are both internally represented as byte arrays.<br/>The UTF-8 default encoding can be overwritten with the optional {{Code|$encoding}} argument. | |Converts the specified {{Code|$string}} to an {{Code|xs:hexBinary}} item. If the default encoding is chosen, conversion will be cheap, as strings and binaries are both internally represented as byte arrays.<br/>The UTF-8 default encoding can be overwritten with the optional {{Code|$encoding}} argument. | ||
− | |- | + | |- valign="top" |
| '''Errors''' | | '''Errors''' | ||
|{{Error|binary|#Errors}} The input cannot be represented in the specified encoding.<br/>{{Error|encoding|#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. | ||
− | |- | + | |- valign="top" |
| '''Examples''' | | '''Examples''' | ||
| | | | ||
Line 68: | Line 78: | ||
{| width='100%' | {| width='100%' | ||
− | |- | + | |- valign="top" |
− | | width='120' | ''' | + | | width='120' | '''Signature''' |
− | | | + | |<pre>convert:integers-to-base64( |
− | |- | + | $integers as xs:integer* |
+ | ) as xs:base64Binary</pre> | ||
+ | |- valign="top" | ||
| '''Summary''' | | '''Summary''' | ||
|Converts the specified {{Code|$integers}} to an item of type {{Code|xs:base64Binary}}: | |Converts the specified {{Code|$integers}} to an item of type {{Code|xs:base64Binary}}: | ||
* Only the first 8 bits of the supplied integers will be considered. | * 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. | * Conversion of byte sequences is very efficient, as items of binary type are internally represented as byte arrays. | ||
− | |- | + | |- valign="top" |
| '''Examples''' | | '''Examples''' | ||
| | | | ||
− | * <code>convert:integers-to-base64(Q{java:java.lang.String}get-bytes('abc'))</code> converts a | + | * <code>convert:integers-to-base64(Q{java:java.lang.String}get-bytes('abc'))</code> converts a byte sequence to a {{Code|xs:base64Binary}} item. |
|} | |} | ||
Line 85: | Line 97: | ||
{| width='100%' | {| width='100%' | ||
− | |- | + | |- valign="top" |
− | | width='120' | ''' | + | | width='120' | '''Signature''' |
− | | | + | |<pre>convert:integers-to-hex( |
− | |- | + | $integers as xs:integer* |
+ | ) as xs:hexBinary</pre> | ||
+ | |- valign="top" | ||
| '''Summary''' | | '''Summary''' | ||
|Converts the specified {{Code|$integers}} to an item of type {{Code|xs:hexBinary}}: | |Converts the specified {{Code|$integers}} to an item of type {{Code|xs:hexBinary}}: | ||
Line 98: | Line 112: | ||
{| width='100%' | {| width='100%' | ||
− | |- | + | |- valign="top" |
− | | width='120' | ''' | + | | width='120' | '''Signature''' |
− | | | + | |<pre>convert:binary-to-integers( |
− | |- | + | $binary as xs:anyAtomicType |
+ | ) as xs:integer*</pre> | ||
+ | |- valign="top" | ||
| '''Summary''' | | '''Summary''' | ||
|Returns the specified {{Code|$binary}} ({{Code|xs:base64Binary}}, {{Code|xs:hexBinary}}) as a sequence of unsigned integers (octets). | |Returns the specified {{Code|$binary}} ({{Code|xs:base64Binary}}, {{Code|xs:hexBinary}}) as a sequence of unsigned integers (octets). | ||
− | |- | + | |- valign="top" |
| '''Examples''' | | '''Examples''' | ||
| | | | ||
Line 113: | Line 129: | ||
{| width='100%' | {| width='100%' | ||
− | |- | + | |- valign="top" |
− | | width='120' | ''' | + | | width='120' | '''Signature''' |
− | | | + | |<pre>convert:binary-to-bytes( |
− | |- | + | $binary as xs:anyAtomicType |
+ | ) as xs:byte*</pre> | ||
+ | |- valign="top" | ||
| '''Summary''' | | '''Summary''' | ||
|Returns the specified {{Code|$binary}} ({{Code|xs:base64Binary}}, {{Code|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. | |Returns the specified {{Code|$binary}} ({{Code|xs:base64Binary}}, {{Code|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. | ||
− | |- | + | |- valign="top" |
| '''Examples''' | | '''Examples''' | ||
| | | | ||
Line 131: | Line 149: | ||
{| width='100%' | {| width='100%' | ||
− | |- | + | |- valign="top" |
− | | width='120' | ''' | + | | width='120' | '''Signature''' |
− | | | + | |<pre>convert:integer-to-base( |
− | |- | + | $number as xs:integer, |
+ | $base as xs:integer | ||
+ | ) as xs:string</pre> | ||
+ | |- valign="top" | ||
| '''Summary''' | | '''Summary''' | ||
− | |Converts {{Code|$number}} to a string, using the specified {{Code|$base}}, interpreting it as a 64-bit unsigned integer.<br />The first base elements of the sequence {{Code|'0',..,'9','a',..,'z'}} are used as digits.<br />Valid bases are {{Code|2, .., 36}}.<br /> | + | |Converts {{Code|$number}} to a string, using the specified {{Code|$base}}, interpreting it as a 64-bit unsigned integer.<br/>The first base elements of the sequence {{Code|'0',..,'9','a',..,'z'}} are used as digits.<br/>Valid bases are {{Code|2, .., 36}}.<br/> |
− | |- | + | |- valign="top" |
| '''Errors''' | | '''Errors''' | ||
|{{Error|base|#Errors}} The specified base is not in the range 2-36. | |{{Error|base|#Errors}} The specified base is not in the range 2-36. | ||
− | |- | + | |- valign="top" |
| '''Examples''' | | '''Examples''' | ||
| | | | ||
Line 150: | Line 171: | ||
{| width='100%' | {| width='100%' | ||
− | |- | + | |- valign="top" |
− | | width='120' | ''' | + | | width='120' | '''Signature''' |
− | | | + | |<pre>convert:integer-from-base( |
− | |- | + | $string as xs:string, |
+ | $base as xs:integer | ||
+ | ) as xs:integer</pre> | ||
+ | |- valign="top" | ||
| '''Summary''' | | '''Summary''' | ||
− | |Decodes an integer from {{Code|$string}}, using the specified {{Code|$base}}.<br /> The first base elements of the sequence {{Code|'0',..,'9','a',..,'z'}} are allowed as digits; case does not matter. <br />Valid bases are 2 - 36.<br /> If the supplied string contains more than 64 bits of information, the result will be truncated. | + | |Decodes an integer from {{Code|$string}}, using the specified {{Code|$base}}.<br/> The first base elements of the sequence {{Code|'0',..,'9','a',..,'z'}} are allowed as digits; case does not matter. <br/>Valid bases are 2 - 36.<br/> If the supplied string contains more than 64 bits of information, the result will be truncated. |
− | |- | + | |- valign="top" |
| '''Errors''' | | '''Errors''' | ||
|{{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. | |{{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. | ||
− | |- | + | |- valign="top" |
| '''Examples''' | | '''Examples''' | ||
| | | | ||
Line 173: | Line 197: | ||
{| width='100%' | {| width='100%' | ||
− | |- | + | |- valign="top" |
− | | width='120' | ''' | + | | width='120' | '''Signature''' |
− | | | + | |<pre>convert:integer-to-dateTime( |
− | |- | + | $milliseconds as xs:integer |
+ | ) as xs:dateTime</pre> | ||
+ | |- valign="top" | ||
| '''Summary''' | | '''Summary''' | ||
− | |Converts the specified number of {{Code|$milliseconds}} since 1 Jan 1970 to an item of type xs:dateTime.<br /> | + | |Converts the specified number of {{Code|$milliseconds}} since 1 Jan 1970 to an item of type xs:dateTime.<br/> |
− | |- | + | |- valign="top" |
| '''Examples''' | | '''Examples''' | ||
| | | | ||
Line 190: | Line 216: | ||
{| width='100%' | {| width='100%' | ||
− | |- | + | |- valign="top" |
− | | width='120' | ''' | + | | width='120' | '''Signature''' |
− | | | + | |<pre>convert:dateTime-to-integer( |
− | |- | + | $dateTime as xs:dateTime |
+ | ) as xs:integer</pre> | ||
+ | |- valign="top" | ||
| '''Summary''' | | '''Summary''' | ||
− | |Converts the specified {{Code|$dateTime}} item to the number of milliseconds since 1 Jan 1970.<br /> | + | |Converts the specified {{Code|$dateTime}} item to the number of milliseconds since 1 Jan 1970.<br/> |
− | |- | + | |- valign="top" |
| '''Examples''' | | '''Examples''' | ||
| | | | ||
Line 205: | Line 233: | ||
{| width='100%' | {| width='100%' | ||
− | |- | + | |- valign="top" |
− | | width='120' | ''' | + | | width='120' | '''Signature''' |
− | | | + | |<pre>convert:integer-to-dayTime( |
− | |- | + | $milliseconds as xs:integer |
+ | ) as xs:dayTimeDuration</pre> | ||
+ | |- valign="top" | ||
| '''Summary''' | | '''Summary''' | ||
− | |Converts the specified number of {{Code|$milliseconds}} to an item of type xs:dayTimeDuration.<br /> | + | |Converts the specified number of {{Code|$milliseconds}} to an item of type xs:dayTimeDuration.<br/> |
− | |- | + | |- valign="top" |
| '''Examples''' | | '''Examples''' | ||
| | | | ||
Line 220: | Line 250: | ||
{| width='100%' | {| width='100%' | ||
− | |- | + | |- valign="top" |
− | | width='120' | ''' | + | | width='120' | '''Signature''' |
− | | | + | |<pre>convert:dayTime-to-integer( |
− | |- | + | $dayTime as xs:dayTimeDuration |
+ | ) as xs:integer</pre> | ||
+ | |- valign="top" | ||
| '''Summary''' | | '''Summary''' | ||
− | |Converts the specified {{Code|$dayTime}} duration to milliseconds represented by an integer.<br /> | + | |Converts the specified {{Code|$dayTime}} duration to milliseconds represented by an integer.<br/> |
− | |- | + | |- valign="top" |
| '''Examples''' | | '''Examples''' | ||
| | | | ||
Line 233: | Line 265: | ||
=Keys= | =Keys= | ||
+ | |||
+ | The key conversion is employed by the [[JSON Module]] and the [[CSV Module]] 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 ({{Code|_}}). | ||
+ | ** Existing underscores are rewritten to two underscores ({{Code|__}}). | ||
+ | ** Characters that are no valid NCName characters are rewritten to an underscore and the character’s four-digit Unicode. For example, the exclamation mark {{Code|?}} is transformed to {{Code|_003f}}. | ||
==convert:encode-key== | ==convert:encode-key== | ||
− | |||
− | |||
{| width='100%' | {| width='100%' | ||
− | |- | + | |- valign="top" |
− | | width='120' | ''' | + | | width='120' | '''Signature''' |
− | | | + | |<pre>convert:encode-key( |
− | |- | + | $key as xs:string, |
+ | $lax as xs:boolean? := false() | ||
+ | ) as xs:string</pre> | ||
+ | |- valign="top" | ||
| '''Summary''' | | '''Summary''' | ||
− | |Encodes the specified {{Code|$key}} (with the optional {{Code|$lax}} conversion method) to a valid NCName representation, which can be used to create an element node | + | |Encodes the specified {{Code|$key}} (with the optional {{Code|$lax}} conversion method) to a valid NCName representation, which can be used to create an element node. This encoding is employed by the [[JSON Module]] and the [[CSV Module]]. |
− | + | |- valign="top" | |
− | |||
− | |||
− | |||
− | This encoding is employed by | ||
− | |- | ||
| '''Examples''' | | '''Examples''' | ||
| | | | ||
Line 257: | Line 293: | ||
==convert:decode-key== | ==convert:decode-key== | ||
− | |||
− | |||
{| width='100%' | {| width='100%' | ||
− | |- | + | |- valign="top" |
− | | width='120' | ''' | + | | width='120' | '''Signature''' |
− | | | + | |<pre>convert:decode-key( |
− | |- | + | $key as xs:string, |
+ | $lax as xs:boolean? := false() | ||
+ | ) as xs:string</pre> | ||
+ | |- valign="top" | ||
| '''Summary''' | | '''Summary''' | ||
− | |Decodes the specified {{Code|$key}} (with the optional {{Code|$lax}} conversion method) to the original string representation.<br />Keys supplied to this function | + | |Decodes the specified {{Code|$key}} (with the optional {{Code|$lax}} conversion method) to the original string representation.<br/>Keys supplied to this function can be element names that have been created by the [[JSON Module]] or [[CSV Module]]. |
− | |- | + | |- valign="top" |
| '''Examples''' | | '''Examples''' | ||
| | | | ||
− | * <code>convert:decode-key( | + | * <code>convert:decode-key(name(<_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. | * <code>json:doc("doc.json")//* ! convert:decode-key(name())</code> yields the original string representation of all names of a JSON document. | ||
− | |- | + | |- valign="top" |
| '''Errors''' | | '''Errors''' | ||
|{{Error|key|#Errors}} The specified key cannot be decoded to its original representation. | |{{Error|key|#Errors}} The specified key cannot be decoded to its original representation. | ||
Line 282: | Line 319: | ||
! width="110"|Code | ! width="110"|Code | ||
| Description | | Description | ||
− | |- | + | |- valign="top" |
|{{Code|base}} | |{{Code|base}} | ||
|The specified base is not in the range 2-36. | |The specified base is not in the range 2-36. | ||
− | |- | + | |- valign="top" |
|{{Code|binary}} | |{{Code|binary}} | ||
|The input cannot be converted to a binary representation. | |The input cannot be converted to a binary representation. | ||
− | |- | + | |- valign="top" |
|{{Code|encoding}} | |{{Code|encoding}} | ||
|The specified encoding is invalid or not supported. | |The specified encoding is invalid or not supported. | ||
− | |- | + | |- valign="top" |
|{{Code|integer}} | |{{Code|integer}} | ||
|The specified digit is not valid for the given range. | |The specified digit is not valid for the given range. | ||
− | |- | + | |- valign="top" |
|{{Code|key}} | |{{Code|key}} | ||
|The specified key cannot be decoded to its original representation. | |The specified key cannot be decoded to its original representation. | ||
− | |- | + | |- valign="top" |
|{{Code|string}} | |{{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. | ||
Line 305: | Line 342: | ||
;Version 9.4 | ;Version 9.4 | ||
− | + | * Added: {{Function||convert:encode-key}}, {{Function||convert:decode-key}}. | |
− | * Added: | ||
;Version 9.0 | ;Version 9.0 | ||
− | + | * Added: {{Function||convert:binary-to-integers}}. | |
− | * Added: | + | * Updated: {{Function||convert:integers-to-base64}}, {{Function||convert:integers-to-hex}}: Renamed from {{Code|convert:bytes-to-base64}}; argument type relaxed from {{Code|xs:byte}} to {{Code|xs:integer}}. |
− | * Updated: | ||
* Updated: error codes updated; errors now use the module namespace | * Updated: error codes updated; errors now use the module namespace | ||
;Version 8.5 | ;Version 8.5 | ||
− | + | * Updated: {{Function||convert:binary-to-string}}: <code>$fallback</code> argument added. | |
− | * Updated: | ||
;Version 7.5 | ;Version 7.5 | ||
− | + | * Added: {{Function||convert:integer-to-dateTime}}, {{Function||convert:dateTime-to-integer}}, {{Function||convert:integer-to-dayTime}}, {{Function||convert:dayTime-to-integer}}. | |
− | * Added: | ||
The module was introduced with Version 7.3. Some of the functions have been adopted from the obsolete Utility Module. | The module was introduced with Version 7.3. Some of the functions have been adopted from the obsolete Utility Module. |
Latest revision as of 18:37, 20 June 2023
This XQuery Module contains functions to convert data between different formats.
Contents
Conventions[edit]
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[edit]
convert:binary-to-string[edit]
Signature | convert:binary-to-string( $bytes as xs:anyAtomicType, $encoding as xs:string := (), $fallback as xs:boolean? := false() ) 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[edit]
Signature | 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[edit]
Signature | 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[edit]
convert:integers-to-base64[edit]
Signature | convert:integers-to-base64( $integers as xs:integer* ) as xs:base64Binary |
Summary | Converts the specified $integers to an item of type xs:base64Binary :
|
Examples |
|
convert:integers-to-hex[edit]
Signature | 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[edit]
Signature | 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[edit]
Signature | 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[edit]
convert:integer-to-base[edit]
Signature | 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[edit]
Signature | 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[edit]
convert:integer-to-dateTime[edit]
Signature | 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[edit]
Signature | 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[edit]
Signature | 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[edit]
Signature | 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[edit]
The key conversion is employed by the JSON Module and the CSV Module 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
.
- An empty string is converted to a single underscore (
convert:encode-key[edit]
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 Module and the CSV Module.
|
Examples |
|
convert:decode-key[edit]
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 Module or CSV Module. |
Examples |
|
Errors | key : The specified key cannot be decoded to its original representation.
|
Errors[edit]
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. |
key
|
The specified key cannot be decoded to its original representation. |
string
|
The input is an invalid XML string, or the wrong encoding has been specified. |
Changelog[edit]
- 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 fromconvert: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.