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.

 {|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}}.

 {|width='100%'

| width='90120' | '''Signatures'''|{{Func|convert:string-to-base64|$input string as xs:string|xs:base64Binary}}<br/>{{Func|convert:string-to-base64|$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 cheap, as both {{Code|xs:string}} strings and {{Code|xs:base64Binary}} items binaries are both internally 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-base64('HelloWorld'))}} returns the xs:base64binary item yields <code>SGVsbG9Xb3JsZA==</code>.

 {|width='100%'

| width='90120' | '''Signatures'''|{{Func|convert:string-to-hex|$input string as xs:string|xs:hexBinary}}<br/>{{Func|convert:string-to-hex|$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 cheap, as both {{Code|xs:string}} strings and {{Code|xs:hexBinary}} items binaries are both internally 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.|-| '''Examples'''|* <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'''|Converts the specified {{Code|$integers}} to an item of type {{Code|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== {| width='100%'|-| width='120' | '''Signatures'''|{{Func|convert:binary-to-integers|$binary as xs:anyAtomicType|xs:integer*}}|-| '''Summary'''|Returns the specified {{Code|$binary}} ({{Code|xs:base64Binary}}, {{Code|xs:hexBinary}}) as a sequence of unsigned integers (octets).|-| '''Examples'''|* <code>convert:binary-to-integers(xs:hexBinary('FF'))</code> yields {{Code|255}}.|} ==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.

* <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:stringbinary-to-hexbytes(xs:hexBinary('HelloWorld'"4261736558"))}} returns yields the Base64 item sequence {{Code|48656C6C6F576F726C64(66 97 115 101 88)}}.

=Byte ArraysNumbers= ==convert:integer-to-base==

==convert:bytes-to-base64=={|width='100%'

| width='90120' | '''Signatures'''|{{Func|convert:bytesinteger-to-base64base|$input number as xs:byte*integer, $base as xs:integer|xs:base64Binarystring}}<br />

|Converts {{Code|$number}} to a string, using the specified byte sequence to a {{Code|xs:base64Binary$base}} item. Conversion is cheap, interpreting it as a 64-bit unsigned integer.<br />The first base elements of the sequence {{Code|xs:base64Binary'0',..,'9','a',..,'z'}} items are internally represented used as byte arraysdigits.<br />Valid bases are {{Code|2, .., 36}}.<br />

|{{Error|BXCO0001|#Errors}} The input cannot be represented in the specified encoding.<br/>{{Error|BXCO0002base|#Errors}} The specified encoding base is invalid or not supportedin the range 2-36.

* {{Code|convert:stringinteger-to-base64base(-1, 16)}} yields {{Code|'HelloWorldffffffffffffffff'}}.* {{Code|convert:integer-to-base(22, 5)}} returns the xs:base64binary item <code>SGVsbG9Xb3JsZA==</code>yields {{Code|'42'}}.

==convert:bytesinteger-tofrom-hexbase== {|width='100%'

| width='90120' | '''Signatures'''|{{Func|convert:stringinteger-tofrom-hexbase|$input string as xs:string, $base as xs:byte*integer|xs:hexBinaryinteger}}<br />

|Converts Decodes an integer from {{Code|$string}}, using the specified byte sequence to a {{Code|xs:hexBinary$base}} item. Conversion is cheap, as <br /> The first base elements of the sequence {{Code|xs:hexBinary'0',..,'9','a',..,'z'}} items are internally represented allowed as byte arraysdigits; 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.

|{{Error|BXCO0001base|#Errors}} The input cannot be represented specified base is not in the specified encodingrange 2-36.<br/>{{Error|BXCO0002integer|#Errors}} The specified encoding digit is invalid or not supportedvalid 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 />

* {{Code|convert:stringinteger-to-hexdayTime('HelloWorld'1234)}} returns the Base64 item yields {{Code|48656C6C6F576F726C64PT1.234S}}.

==convert:binary-to-bytes=={|width='100%'

| width='90120' | '''Signatures'''|{{Func|convert:binarydayTime-to-bytesinteger|$bin dayTime as basexxs:binarydayTimeDuration|xs:byte*integer}}<br />

|Returns Converts the specified binary data (xs:base64Binary, xs:hexBinary) as a sequence of bytes{{Code|$dayTime}} duration to milliseconds represented by an integer.<br />

* <code>convert:binary-to-bytes(xs:base64Binary('QmFzZVggaXMgY29vbA=='))</code> returns the sequence {{Code|(66, 97, 115, 101, 88, 32, 105, 115, 32, 99, 111, 111, 108)}}.* {{Code|convert:binarydayTime-to-bytesinteger(xs:hexBinarydayTimeDuration("4261736558"'PT1S'))}} returns the sequence yields {{Code|(66 97 115 101 88)1000}}.

=NumbersKeys= ==convert:encode-key== {{Mark|Introduced with Version 9.4:}}

==convert:integer-to-base=={|width='100%'

| width='90120' | '''Signatures'''|{{Func|convert:integerencode-tokey|$key as xs:string|xs:string}}<br />{{Func|convert:encode-basekey|$num key as xs:integerstring, $base lax as xs:integerboolean|xs:string}}<br />

|Converts Encodes the specified {{Code|$numkey}} to base (with the optional {{Code|$baselax}}conversion method) to a valid NCName representation, interpreting it as which can be used to create an element node:* An empty string is converted to a 64-bit unsigned integer.<br />The first single underscore ({{Code|$base_}} elements of the sequence ).* Existing underscores are rewritten to two underscores ({{Code|'0',__}}).* Characters that are no valid NCName characters are rewritten to an underscore and the character’s four-digit Unicode.For example,'9','a',.the exclamation mark {{Code|?}} is transformed to {{Code|_003f}}.* If lax conversion is chosen,'z'}} invalid characters are used replaced with underscores or (when invalid as digitsfirst 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.<br />Valid bases are This encoding is employed by the {{Code|2, .., 36direct}}conversion format in the [[JSON Module]] and the [[CSV Module]].<br />

* <code>element {{Code|convert:integerencode-to-basekey(-1, 16"!")}} returns the hexadecimal string {{Code|'ffffffffffffffff'}}.* {{Code|convert</code> creates a new element with an encoded name:integer-to-base(22, 5)}} returns {{Code|'42'}}<code><_0021/></code>.

==convert:integerdecode-from-basekey== {{Mark|Introduced with Version 9.4:}} {|width='100%'

| width='90120' | '''Signatures'''|{{Func|convert:integerdecode-fromkey|$key as xs:string|xs:string}}<br />{{Func|convert:decode-basekey|$str key as xs:string, $base lax as xs:integerboolean|xs:integerstring}}<br />

|Decodes an {{Code|xs:integer}} from the specified {{Code|$strkey}}, assuming that it's encoded in base {{Code|$base}}.<br /> The first (with the optional {{Code|$baselax}} elements of conversion method) to the sequence {{Code|'0',..,'9','a',..,'z'}} are allowed as digits, case doesn't matteroriginal string representation. <br />Valid bases Keys supplied to this function are 2 - 36.<br /> If {{Code|$str}} contains more than 64 bits of information, usually element names from documents that have been created with the result is truncated arbitarily[[JSON Module]] or [[CSV Module]].

* {{Code|<code>convert:integerdecode-from-basekey(name('ffffffffffffffff', 16<_0021/>))}} returns {{Code|-1}}</code> yields <code>!</code>.* {{Code|<code>json:doc("doc.json")//* ! convert:integerdecode-from-basekey(name('CAFEBABE', 16)}} returns {{Code|3405691582}})</code> yields the original string representation of all names of a JSON document.* {{Code|convert:integer-from-base(| '''Errors''42', 5)}} returns {{Code|22}}.* {{CodeError|convert:integer-from-base(convert:integer-to-base(123, 7), 7)}} returns {{Codekey|123#Errors}}The specified key cannot be decoded to its original representation.

! width="5%110"|Code! width="95%"|Description|-|{{Code|base}}|The specified base is not in the range 2-36.

|{{Code|BXCO0001binary}}|The input is an invalid XML string, or the wrong encoding has been specifiedcannot be converted to a binary representation.

|{{Code|BXCO0002encoding}}