Changes

All functions and errors in this module are assigned to the {{Code|<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|http://basex.org/errors}} namespace, which is statically bound to the {{Code|bxerr}} prefix.

=Binary DataStrings= ==convert:binary-to-string==

==convert:to-string=={|width='100%'

| width='90120' | '''Signatures'''|{{Func|convert:binary-to-string|$bytes as basexxs: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 basexxs:binaryanyAtomicType, $encoding as xs:string, $fallback as xs:boolean|xs:string}}

|Converts the specifed binary data {{Code|$bytes}} ({{Code|xs:base64Binary}}, {{Code|xs:hexBinary}}) to a string.<br/>:* 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;).

|{{Error|BXCO0001string|#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.

* {{Code|convert:binary-to-string(xs:hexBinary('48656c6c6f576f726c64'))}} returns the string yields {{Code|HelloWorld}}.

==convert:string-to-base64Binarybase64== {|width='100%'

| width='90120' | '''Signatures'''|{{Func|convert:string-to-base64Binarybase64|$input string as xs:string|xs:base64Binary}}<br/>{{Func|convert:string-to-base64Binarybase64|$input string as xs:string, $encoding as xs:string|xs:base64Binary}}

|Converts the specified {{Code|$string }} to a an {{Code|xs:base64Binary}} item. If the default encoding is chosen, conversion will be very cheap in BaseX, as both {{Code|xs:string}} strings and {{Code|xs:base64Binary}} items binaries are both internally mapped to represented as byte arrays.<br/>The UTF-8 default encoding can be overwritten with the optional {{Code|$encoding}} argument.

|{{Error|BXCO0001binary|#Errors}} The input cannot be represented in the specified encoding.<br/>{{Error|BXCO0002encoding|#Errors}} The specified encoding is invalid or not supported.

* {{Code|string(convert:string-to-base64Binarybase64('HelloWorld'))}} returns the Base64 item {{Code|yields <code>SGVsbG9Xb3JsZA==}}</code>.

==convert:string-to-hexBinaryhex== {|width='100%'

| width='90120' | '''Signatures'''|{{Func|convert:string-to-hexBinaryhex|$input string as xs:string|xs:hexBinary}}<br/>{{Func|convert:string-to-hexBinaryhex|$input string as xs:string, $encoding as xs:string|xs:hexBinary}}

|Converts the specified {{Code|$string }} to a an {{Code|xs:hexBinary}} item. If the default encoding is chosen, conversion will be very cheap in BaseX, as both {{Code|xs:string}} strings and {{Code|xs:hexBinary}} items binaries are both internally mapped to represented as byte arrays.<br/>The UTF-8 default encoding can be overwritten with the optional {{Code|$encoding}} argument.

|{{Error|BXCO0001binary|#Errors}} The input cannot be represented in the specified encoding.<br/>{{Error|BXCO0002encoding|#Errors}} The specified encoding is invalid or not supported.|-| '''Examples'''|* {{Code|string(convert:string-to-hex('HelloWorld'))}} yields {{Code|48656C6C6F576F726C64}}.|} =Binary Data= ==convert:integers-to-base64== {| width='100%'|-| width='120' | '''Signatures'''|{{Func|convert:integers-to-base64|$integers as xs:integer*|xs:base64Binary}}|-| '''Summary'''|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.* Conversion of byte sequences is very efficient, as items of binary type are internally represented as byte arrays.

* <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:integers-to-hex== {| width='100%'|-| width='120' | '''Signatures'''|{{Func|convert:integers-to-hex|$integers as xs:integer*|xs:hexBinary(}}|-| '''Summary''HelloWorld')|Converts the specified {{Code|$integers}} returns the Base64 to an item of type {{Code|48656C6C6F576F726C64xs: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-bytesintegers== {|width='100%'

| width='90120' | '''Signatures'''|{{Func|convert:binary-to-bytesintegers|$bin binary as basexxs:binaryanyAtomicType|xs:byteinteger*}}

|Extracts Returns the bytes from the given specified {{Code|$binary data }} ({{Code|$binxs:base64Binary}}, {{Code|xs:hexBinary}}) as a sequence of unsigned integers (octets).

* <code>convert:binary-to-bytesintegers(xs:base64BinaryhexBinary('QmFzZVggaXMgY29vbA==FF'))</code> returns the sequence {{Code|(66, 97, 115, 101, 88, 32, 105, 115, 32, 99, 111, 111, 108)}}.* {{Code|convert:to-bytes(xs:hexBinary("4261736558"))}} returns the sequence yields {{Code|(66 97 115 101 88)255}}.

=Numeric Data=convert:binary-to-bytes== {| width='100%'|-| width='120' | '''Signatures'''|{{Func|convert:binary-to-bytes|$binary as xs:anyAtomicType|xs:byte*}}|-| '''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.|-| '''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-bytes(xs:hexBinary("4261736558"))}} yields the sequence {{Code|(66 97 115 101 88)}}.|} =Numbers=

 {|width='100%'

| width='90120' | '''Signatures'''|{{Func|convert:integer-to-base|$num number as xs:integer, $base as xs:integer|xs:string}}<br />

|Converts {{Code|$numnumber}} to base a string, using the specified {{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 />|-| '''Errors'''|{{Error|base|#Errors}} The specified base is not in the range 2-36.

* {{Code|convert:integer-to-base(-1, 16)}} returns the hexadecimal string yields {{Code|'ffffffffffffffff'}}.* {{Code|convert:integer-to-base(22, 5)}} returns yields {{Code|'42'}}.

 {|width='100%'|-| width='120' | '''Signatures'''|{{Func|convert:integer-from-base|$string as xs:string, $base as xs:integer|xs:integer}}<br />|-| '''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.|-| '''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.|-| '''Examples'''|* {{Code|convert:integer-from-base('ffffffffffffffff', 16)}} yields {{Code|-1}}.* {{Code|convert:integer-from-base('CAFEBABE', 16)}} yields {{Code|3405691582}}.* {{Code|convert:integer-from-base('42', 5)}} yields {{Code|22}}.* {{Code|convert:integer-from-base(convert:integer-to-base(123, 7), 7)}} yields {{Code|123}}.|} =Dates and Durations= ==convert:integer-to-dateTime== {| width='100%'|-| width='120' | '''Signatures'''|{{Func|convert:integer-to-dateTime|$milliseconds as xs:integer|xs:dateTime}}<br />|-| '''Summary'''|Converts the specified number of {{Code|$milliseconds}} since 1 Jan 1970 to an item of type xs:dateTime.<br />|-| '''Examples'''|* {{Code|convert:integer-to-dateTime(0)}} yields {{Code|1970-01-01T00:00:00Z}}.* {{Code|convert:integer-to-dateTime(1234567890123)}} yields {{Code|2009-02-13T23:31:30.123Z}}.* {{Code|convert:integer-to-dateTime(prof:current-ms())}} returns the current miliseconds in the {{Code|xs:dateTime}} format.|} ==convert:dateTime-to-integer== {| width='100%'|-| width='120' | '''Signatures'''|{{Func|convert:dateTime-to-integer|$dateTime as xs:dateTime|xs:integer}}<br />|-| '''Summary'''|Converts the specified {{Code|$dateTime}} item to the number of milliseconds since 1 Jan 1970.<br />|-| '''Examples'''|* {{Code|convert:dateTime-to-integer(xs:dateTime('1970-01-01T00:00:00Z'))}} yields {{Code|0}}.|} ==convert:integer-to-dayTime== {| width='100%'|-| width='120' | '''Signatures'''|{{Func|convert:integer-to-dayTime|$milliseconds as xs:integer|xs:dayTimeDuration}}<br />|-| '''Summary'''|Converts the specified number of {{Code|$milliseconds}} to an item of type xs:dayTimeDuration.<br />|-| '''Examples'''|* {{Code|convert:integer-to-dayTime(1234)}} yields {{Code|PT1.234S}}.|} ==convert:dayTime-to-integer== {| width='100%'

| width='90120' | '''Signatures'''|{{Func|convert:integerdayTime-fromto-baseinteger|$str dayTime as xs:string, $base as xs:integerdayTimeDuration|xs:integer}}<br />

|Decodes an {{Code|xs:integer}} from Converts the specified {{Code|$str}}, assuming that it's encoded in base {{Code|$basedayTime}}duration to milliseconds represented by an integer.<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.

* {{Code|convert:integerdayTime-fromto-baseinteger(xs:dayTimeDuration('ffffffffffffffffPT1S', 16))}} returns yields {{Code|1000}}.|} =Keys= ==convert:encode-1key== {{Mark|Introduced with Version 9.4:}}.* {| width='100%'|-| width='120' | '''Signatures'''|{{Func|convert:encode-key|$key as xs:string|xs:string}}<br />{{CodeFunc|convert:integerencode-fromkey|$key as xs:string, $lax as xs:boolean|xs:string}}<br />|-base(| '''Summary''CAFEBABE'|Encodes the specified {{Code|$key}} (with the optional {{Code|$lax}} conversion method) to a valid NCName representation, 16which can be used to create an element node:* 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|?}} returns is transformed to {{Code|3405691582_003f}}.* If lax conversion is chosen, 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.This encoding is employed by the {{Code|direct}} conversion format in the [[JSON Module]] and the [[CSV Module]].|-| '''Examples'''|* <code>element { convert:integerencode-key("!") } { }</code> creates a new element with an encoded name: <code><_0021/></code>.|} ==convert:decode-fromkey== {{Mark|Introduced with Version 9.4:}} {| width='100%'|-base(| width='120' | '''Signatures''42'|{{Func|convert:decode-key|$key as xs:string|xs:string}}<br />{{Func|convert:decode-key|$key as xs:string, 5)$lax as xs:boolean|xs:string}} returns <br />|-| '''Summary'''|Decodes the specified {{Code|22$key}}.* (with the optional {{Code|$lax}} conversion method) to the original string representation.<br />Keys supplied to this function are usually element names from documents that have been created with the [[JSON Module]] or [[CSV Module]].|-| '''Examples'''|* <code>convert:integerdecode-from-basekey(name(<_0021/>))</code> yields <code>!</code>.* <code>json:doc("doc.json")//* ! convert:integerdecode-to-basekey(name(123, 7), 7)}} returns </code> yields the original string representation of all names of a JSON document.|-| '''Errors'''|{{CodeError|key|123#Errors}}The specified key cannot be decoded to its original representation.

! width="5%110"|Code! width="95%"|Description

|{{Code|BXCO0001base}}|The input specified base is an invalid XML string, or not in the wrong encoding has been specifiedrange 2-36.|-|{{Code|binary}}|The input cannot be converted to a binary representation.

|{{Code|BXCO0002encoding}}

The module was introduced with ;Version 79.4 * Added: [[#convert:encode-key|convert:encode-key]], [[#convert:decode-key|convert:decode-key]].3 ;Version 9. Some of the functions have been moved 0 * Added: [[#convert:binary-to-integers|convert:binary-to-integers]].* Updated: [[#convert:integers-to-base64|convert:integers-to-base64]], [[#convert:integers-to-hex|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 * Updated: [[#convert:binary-to-string|convert:binary-to-string]]: <code>$fallback</code> argument added. ;Version 7.5 * 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]], [[Utility Module#convert:dayTime-to-integer|convert:dayTime-to-integer]].