Difference between revisions of "Conversion Module"

From BaseX Documentation
Jump to navigation Jump to search
 
(50 intermediate revisions by the same user not shown)
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/>
+
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/>
All errors are assigned to the <code><nowiki>http://basex.org/errors</nowiki></code> namespace, which is statically bound to the {{Code|bxerr}} prefix.
 
  
 
=Strings=
 
=Strings=
Line 11: Line 10:
  
 
{| width='100%'
 
{| width='100%'
|-
+
|- valign="top"
| width='120' | '''Signatures'''
+
| width='120' | '''Signature'''
|{{Func|convert:binary-to-string|$bytes as xs:anyAtomicType|xs:string}}<br/>{{Func|convert:binary-to-string|$bytes as xs:anyAtomicType, $encoding as xs:string|xs:string}}<br/>{{Func|convert:binary-to-string|$bytes as xs:anyAtomicType, $encoding as xs:string, $fallback as xs:boolean|xs:string}}
+
|<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 binary data (xs:base64Binary, 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> (&#xFFFD;).
 
* 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> (&#xFFFD;).
|-
+
|- valign="top"
 
| '''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.
|-
+
|- valign="top"
 
| '''Examples'''
 
| '''Examples'''
 
|
 
|
Line 31: Line 34:
  
 
{| width='100%'
 
{| width='100%'
|-
+
|- valign="top"
| width='120' | '''Signatures'''
+
| width='120' | '''Signature'''
|{{Func|convert:string-to-base64|$input as xs:string|xs:base64Binary}}<br/>{{Func|convert:string-to-base64|$input as xs:string, $encoding as xs:string|xs:base64Binary}}
+
|<pre>convert:string-to-base64(
|-
+
  $string    as xs:string,
 +
  $encoding as xs:string := ()
 +
) as xs:base64Binary</pre>
 +
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
|Converts the specified string to a {{Code|xs:base64Binary}} item. If the default encoding is chosen, conversion will be cheap, as both {{Code|xs:string}} and {{Code|xs:base64Binary}} items are 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|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.
|-
+
|- valign="top"
 
| '''Examples'''
 
| '''Examples'''
 
|
 
|
Line 49: Line 55:
  
 
{| width='100%'
 
{| width='100%'
|-
+
|- valign="top"
| width='120' | '''Signatures'''
+
| width='120' | '''Signature'''
|{{Func|convert:string-to-hex|$input as xs:string|xs:hexBinary}}<br/>{{Func|convert:string-to-hex|$input as xs:string, $encoding as xs:string|xs:hexBinary}}
+
|<pre>convert:string-to-hex(
|-
+
  $string    as xs:string,
 +
  $encoding as xs:string := ()
 +
) as xs:hexBinary</pre>
 +
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
|Converts the specified string to a {{Code|xs:hexBinary}} item. If the default encoding is chosen, conversion will be cheap, as both {{Code|xs:string}} and {{Code|xs:hexBinary}} items are 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|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.
|-
+
|- valign="top"
 
| '''Examples'''
 
| '''Examples'''
 
|
 
|
Line 66: Line 75:
 
=Binary Data=
 
=Binary Data=
  
==convert:bytes-to-base64==
+
==convert:integers-to-base64==
 
 
{{Mark|Updated with Version 8.7}}: Argument type relaxed from {{Code|xs:byte}} to {{Code|xs:integer}}.
 
  
 
{| width='100%'
 
{| width='100%'
|-
+
|- valign="top"
| width='120' | '''Signatures'''
+
| width='120' | '''Signature'''
|{{Func|convert:bytes-to-base64|$input as xs:integer*|xs:base64Binary}}
+
|<pre>convert:integers-to-base64(
|-
+
  $integers  as xs:integer*
 +
) as xs:base64Binary</pre>
 +
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
|Converts the specified integer sequence to a {{Code|xs:base64Binary}} item:
+
|Converts the specified {{Code|$integers}} to an item of type {{Code|xs:base64Binary}}:
* Only the first 8 bits of the supplied integer values will be considered.
+
* Only the first 8 bits of the supplied integers will be considered.
* Conversion of byte sequences is particularly cheap, as {{Code|xs:base64Binary}} items 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"
| '''Errors'''
+
| '''Examples'''
|{{Error|BXCO0001|#Errors}} The input cannot be represented in the specified encoding.<br/>{{Error|BXCO0002|#Errors}} The specified encoding is invalid or not supported.
+
|
 +
* <code>convert:integers-to-base64(Q{java:java.lang.String}get-bytes('abc'))</code> converts a byte sequence to a {{Code|xs:base64Binary}} item.
 
|}
 
|}
  
==convert:bytes-to-hex==
+
==convert:integers-to-hex==
 
 
{{Mark|Updated with Version 8.7}}: Argument type relaxed from {{Code|xs:byte}} to {{Code|xs:integer}}.
 
  
 
{| width='100%'
 
{| width='100%'
|-
+
|- valign="top"
| width='120' | '''Signatures'''
+
| width='120' | '''Signature'''
|{{Func|convert:bytes-to-hex|$input as xs:integer*|xs:hexBinary}}
+
|<pre>convert:integers-to-hex(
|-
+
  $integers  as xs:integer*
 +
) as xs:hexBinary</pre>
 +
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
|Converts the specified integer sequence to a {{Code|xs:hexBinary}} item:
+
|Converts the specified {{Code|$integers}} to an item of type {{Code|xs:hexBinary}}:
* Only the first 8 bits of the supplied integer values will be considered.
+
* Only the first 8 bits of the supplied integers will be considered.
* Conversion of byte sequences is particularly cheap, as {{Code|xs:hexBinary}} items are internally represented as byte arrays.
+
* Conversion of byte sequences is very efficient, as items of binary type are internally represented as byte arrays.
 
|}
 
|}
  
==convert:binary-to-bytes==
+
==convert:binary-to-integers==
  
 
{| width='100%'
 
{| width='100%'
|-
+
|- valign="top"
| width='120' | '''Signatures'''
+
| width='120' | '''Signature'''
|{{Func|convert:binary-to-bytes|$bin as xs:anyAtomicType|xs:byte*}}
+
|<pre>convert:binary-to-integers(
|-
+
  $binary  as xs:anyAtomicType
 +
) as xs:integer*</pre>
 +
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
|Returns the specified binary data (xs:base64Binary, xs:hexBinary) as a sequence of bytes.
+
|Returns the specified {{Code|$binary}} ({{Code|xs:base64Binary}}, {{Code|xs:hexBinary}}) as a sequence of unsigned integers (octets).
|-
+
|- valign="top"
 
| '''Examples'''
 
| '''Examples'''
 
|
 
|
* <code>convert:binary-to-bytes(xs:base64Binary('QmFzZVggaXMgY29vbA=='))</code> yields the sequence {{Code|(66, 97, 115, 101, 88, 32, 105, 115, 32, 99, 111, 111, 108)}}.
+
* <code>convert:binary-to-integers(xs:hexBinary('FF'))</code> yields {{Code|255}}.
* {{Code|convert:binary-to-bytes(xs:hexBinary("4261736558"))}} yields the sequence {{Code|(66 97 115 101 88)}}.
 
 
|}
 
|}
  
==convert:binary-to-integer==
+
==convert:binary-to-bytes==
 
 
{{Mark|Introduced with Version 8.7}}:
 
  
 
{| width='100%'
 
{| width='100%'
|-
+
|- valign="top"
| width='120' | '''Signatures'''
+
| width='120' | '''Signature'''
|{{Func|convert:binary-to-integer|$bin as xs:anyAtomicType|xs:integer*}}
+
|<pre>convert:binary-to-bytes(
|-
+
  $binary  as xs:anyAtomicType
 +
) as xs:byte*</pre>
 +
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
|Returns the specified binary data (xs:base64Binary, xs:hexBinary) as a sequence of unsigned integers (octets).
+
|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'''
 
|
 
|
* <code>convert:binary-to-integer(xs:hexBinary('FF'))</code> yields {{Code|255}}.
+
* <code>convert:binary-to-bytes(xs:base64Binary('QmFzZVggaXMgY29vbA=='))</code> yields the sequence {{Code|(66, 97, 115, 101, 88, 32, 105, 115, 32, 99, 111, 111, 108)}}.
 +
* {{Code|convert:binary-to-bytes(xs:hexBinary("4261736558"))}} yields the sequence {{Code|(66 97 115 101 88)}}.
 
|}
 
|}
  
Line 137: Line 149:
  
 
{| width='100%'
 
{| width='100%'
|-
+
|- valign="top"
| width='120' | '''Signatures'''
+
| width='120' | '''Signature'''
|{{Func|convert:integer-to-base|$num as xs:integer, $base as xs:integer|xs:string}}<br />
+
|<pre>convert:integer-to-base(
|-
+
  $number  as xs:integer,
 +
  $base   as xs:integer
 +
) as xs:string</pre>
 +
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
|Converts {{Code|$num}} to base {{Code|$base}}, interpreting it as a 64-bit unsigned integer.<br />The first {{Code|$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|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.
|-
+
|- valign="top"
 
| '''Examples'''
 
| '''Examples'''
 
|
 
|
Line 156: Line 171:
  
 
{| width='100%'
 
{| width='100%'
|-
+
|- valign="top"
| width='120' | '''Signatures'''
+
| width='120' | '''Signature'''
|{{Func|convert:integer-from-base|$str as xs:string, $base as xs:integer|xs:integer}}<br />
+
|<pre>convert:integer-from-base(
|-
+
  $string  as xs:string,
 +
  $base   as xs:integer
 +
) as xs:integer</pre>
 +
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
|Decodes an {{Code|xs:integer}} from {{Code|$str}}, assuming that it's encoded in base {{Code|$base}}.<br /> The first {{Code|$base}} elements of the sequence {{Code|'0',..,'9','a',..,'z'}} are allowed as digits, case doesn't matter. <br />Valid bases are 2 - 36.<br /> If {{Code|$str}} contains more than 64 bits of information, the result is truncated arbitarily.
+
|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|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.
|-
+
|- valign="top"
 
| '''Examples'''
 
| '''Examples'''
 
|
 
|
Line 179: Line 197:
  
 
{| width='100%'
 
{| width='100%'
|-
+
|- valign="top"
| width='120' | '''Signatures'''
+
| width='120' | '''Signature'''
|{{Func|convert:integer-to-dateTime|$ms as xs:integer|xs:dateTime}}<br />
+
|<pre>convert:integer-to-dateTime(
|-
+
  $milliseconds  as xs:integer
 +
) as xs:dateTime</pre>
 +
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
|Converts the specified number of 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 196: Line 216:
  
 
{| width='100%'
 
{| width='100%'
|-
+
|- valign="top"
| width='120' | '''Signatures'''
+
| width='120' | '''Signature'''
|{{Func|convert:dateTime-to-integer|$dateTime as xs:dateTime|xs:integer}}<br />
+
|<pre>convert:dateTime-to-integer(
|-
+
  $dateTime as xs:dateTime
 +
) as xs:integer</pre>
 +
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
|Converts the specified item of type xs:dateTime 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 211: Line 233:
  
 
{| width='100%'
 
{| width='100%'
|-
+
|- valign="top"
| width='120' | '''Signatures'''
+
| width='120' | '''Signature'''
|{{Func|convert:integer-to-dayTime|$ms as xs:integer|xs:dayTimeDuration}}<br />
+
|<pre>convert:integer-to-dayTime(
|-
+
  $milliseconds  as xs:integer
 +
) as xs:dayTimeDuration</pre>
 +
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
|Converts the specified number of 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 226: Line 250:
  
 
{| width='100%'
 
{| width='100%'
|-
+
|- valign="top"
| width='120' | '''Signatures'''
+
| width='120' | '''Signature'''
|{{Func|convert:dayTime-to-integer|$dayTime as xs:dayTimeDuration|xs:integer}}<br />
+
|<pre>convert:dayTime-to-integer(
|-
+
  $dayTime as xs:dayTimeDuration
 +
) as xs:integer</pre>
 +
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
|Converts the specified item of type xs:dayTimeDuration to milliseconds represented by an integer.<br />
+
|Converts the specified {{Code|$dayTime}} duration to milliseconds represented by an integer.<br/>
|-
+
|- valign="top"
 
| '''Examples'''
 
| '''Examples'''
 
|
 
|
 
* {{Code|convert:dayTime-to-integer(xs:dayTimeDuration('PT1S'))}} yields {{Code|1000}}.
 
* {{Code|convert:dayTime-to-integer(xs:dayTimeDuration('PT1S'))}} yields {{Code|1000}}.
 +
|}
 +
 +
=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==
 +
 +
{| width='100%'
 +
|- valign="top"
 +
| width='120' | '''Signature'''
 +
|<pre>convert:encode-key(
 +
  $key  as xs:string,
 +
  $lax  as xs:boolean?  := false()
 +
) as xs:string</pre>
 +
|- valign="top"
 +
| '''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. This encoding is employed by the [[JSON Module]] and the [[CSV Module]].
 +
|- valign="top"
 +
| '''Examples'''
 +
|
 +
* <code>element { convert:encode-key("!") } { }</code> creates a new element with an encoded name: <code><_0021/></code>.
 +
|}
 +
 +
==convert:decode-key==
 +
 +
{| width='100%'
 +
|- valign="top"
 +
| width='120' | '''Signature'''
 +
|<pre>convert:decode-key(
 +
  $key  as xs:string,
 +
  $lax  as xs:boolean?  := false()
 +
) as xs:string</pre>
 +
|- valign="top"
 +
| '''Summary'''
 +
|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'''
 +
|
 +
* <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.
 +
|- valign="top"
 +
| '''Errors'''
 +
|{{Error|key|#Errors}} The specified key cannot be decoded to its original representation.
 
|}
 
|}
  
Line 243: Line 319:
 
! width="110"|Code
 
! width="110"|Code
 
| Description
 
| Description
|-
+
|- valign="top"
|{{Code|BXCO0001}}
+
|{{Code|base}}
|The input is an invalid XML string, or the wrong encoding has been specified.
 
|-
 
|{{Code|BXCO0002}}
 
|The specified encoding is invalid or not supported.
 
|-
 
|{{Code|BXCO0003}}
 
 
|The specified base is not in the range 2-36.
 
|The specified base is not in the range 2-36.
|-
+
|- valign="top"
|{{Code|BXCO0004}}
+
|{{Code|binary}}
 +
|The input cannot be converted to a binary representation.
 +
|- valign="top"
 +
|{{Code|encoding}}
 
|The specified encoding is invalid or not supported.
 
|The specified encoding is invalid or not supported.
|-
+
|- valign="top"
|{{Code|BXCO0005}}
+
|{{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}}
 +
|The specified key cannot be decoded to its original representation.
 +
|- valign="top"
 +
|{{Code|string}}
 +
|The input is an invalid XML string, or the wrong encoding has been specified.
 
|}
 
|}
  
 
=Changelog=
 
=Changelog=
  
;Version 8.7
+
;Version 9.4
 +
* Added: {{Function||convert:encode-key}}, {{Function||convert:decode-key}}.
  
* Added: [[#convert:bytes-to-integer|convert:bytes-to-integer]].
+
;Version 9.0
* 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}}.
+
* Added: {{Function||convert:binary-to-integers}}.
 +
* 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: 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: [[#convert:binary-to-string|convert:binary-to-string]]: <code>$fallback</code> argument added.
 
  
 
;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: [[#convert:integer-to-dateTime|convert:integer-to-dateTime]], [[#convert:dateTime-to-integer|convert:dateTime-to-integer]], [[#convert:integer-to-dayTime|convert:integer-to-dayTime]], [[#convert:dayTime-to-integer|convert:dayTime-to-integer]].
 
  
 
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 17:37, 20 June 2023

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:
  • 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[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
  • string(convert:string-to-base64('HelloWorld')) yields SGVsbG9Xb3JsZA==.

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
  • string(convert:string-to-hex('HelloWorld')) yields 48656C6C6F576F726C64.

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:
  • 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.
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[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:
  • 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.

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-integers(xs:hexBinary('FF')) yields 255.

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

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-to-base(-1, 16) yields 'ffffffffffffffff'.
  • convert:integer-to-base(22, 5) yields '42'.

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
  • 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[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: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[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:dateTime-to-integer(xs:dateTime('1970-01-01T00:00:00Z')) yields 0.

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:integer-to-dayTime(1234) yields PT1.234S.

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
  • convert:dayTime-to-integer(xs:dayTimeDuration('PT1S')) yields 1000.

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.

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
  • element { convert:encode-key("!") } { } creates a new element with an encoded name: <_0021/>.

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
  • convert:decode-key(name(<_0021/>)) yields !.
  • json:doc("doc.json")//* ! convert:decode-key(name()) yields the original string representation of all names of a JSON document.
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
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.