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

* {{Code|<code>convert:stringbinary-to-hexintegers(xs:hexBinary('HelloWorldFF')}} returns the Base64 item )</code> yields {{Code|48656C6C6F576F726C64255}}.

=Byte Arrays=convert:binary-to-bytes==

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

| width='90120' | '''Signatures'''|{{Func|convert:bytesbinary-to-base64bytes|$input binary as xs:byte*anyAtomicType|xs:base64Binarybyte*}}

|Converts Returns the specified byte sequence to a {{Code|$binary}} ({{Code|xs:base64Binary}} item. Conversion is cheap, as {{Code|xs:base64BinaryhexBinary}} ) 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= ==convert:integer-to-base== {| width='100%'|-| width='120' | '''Signatures'''|{{Func|convert:integer-to-base|$number as xs:integer, $base as xs:integer|xs:string}}<br />|-| '''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 />

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

* {{Code|convert:stringinteger-tofrom-base('ffffffffffffffff', 16)}} yields {{Code|-1}}.* {{Code|convert:integer-from-base('CAFEBABE', 16)}} yields {{Code|3405691582}}.* {{Code|convert:integer-from-hexbase('HelloWorld42', 5)}} yields {{Code|22}}.* {{Code|convert:integer-from-base(convert:integer-to-base(123, 7), 7)}} returns the Base64 item yields {{Code|48656C6C6F576F726C64123}}.

{| 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:binarydateTime-to-bytesinteger== {|width='100%'

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

|Returns Converts the specified binary data (xs:base64Binary, xs:hexBinary) as a sequence {{Code|$dateTime}} item to the number of bytesmilliseconds since 1 Jan 1970.<br />

* <code>{{Code|convert:binarydateTime-to-bytesinteger(xs:base64BinarydateTime('QmFzZVggaXMgY29vbA=='))</code> returns the sequence {{Code|(66, 97, 115, 101, 88, 32, 105, 115, 32, 99, 111, 111, 108)}}.* {{Code|convert:binary1970-to01-bytes(xs01T00:00:hexBinary("4261736558"00Z'))}} returns the sequence yields {{Code|(66 97 115 101 88)0}}.

=Numbers=convert:integer-to-dayTime==

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

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

|Converts the specified number of {{Code|$nummilliseconds}} to base {{Code|$base}}, interpreting it as a 64-bit unsigned integer.<br />The first {{Code|$base}} elements an item of the sequence {{Code|'0',..,'9','a',..,'z'}} are used as digits.<br />Valid bases are {{Code|2, .., 36}}type xs:dayTimeDuration.<br />

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

==convert:integerdayTime-fromto-baseinteger== {|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-from-base('ffffffffffffffff', 16)}} returns {{Code|to-1}}.* {{Code|convert:integer-from-base('CAFEBABE', 16)}} returns {{Code|3405691582}}.* {{Code|convertxs:integer-from-basedayTimeDuration('42PT1S', 5)}} returns {{Code|22}}.* {{Code|convert:integer-from-base(convert:integer-to-base(123, 7), 7)}} returns yields {{Code|1231000}}.

=DatesKeys=

==convert:msencode-to-dateTimekey==

{{Mark|Introduced with Version 79.4:}} {|width='100%'

| width='90120' | '''Signatures'''|{{Func|convert:msencode-tokey|$key as xs:string|xs:string}}<br />{{Func|convert:encode-dateTimekey|$number key as xs:string, $lax as xs:integerboolean|xs:dateTimestring}}<br />

|Converts Encodes the specified {{Code|$numberkey}} (with the optional {{Code|$lax}} conversion method) to a valid NCName representation, which 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|?}} is transformed to {{Code|_003f}}.* If lax conversion is chosen, invalid characters are replaced with underscores or (when invalid as first character of milliseconds since 1 Jan 1970 an element name) prefixed with an underscore. The resulting string may be better readable, but it cannot necessarily be converted back to a dateTime itemthe original form.This encoding is employed by the {{Code|direct}} conversion format in the [[JSON Module]] and the [[CSV Module]].<br />

* <code>element {{Code|convert:ms-toencode-dateTimekey(0"!")}} returns {{Code|1970-01-01T00:00:00Z}}.* {{Code|convert:ms-to-dateTime(1234567890123)}} returns {{Code|2009-02-14T00:31</code> creates a new element with an encoded name:30.123Z}}<code><_0021/></code>.

==convert:dateTimedecode-to-mskey==

{{Mark|Introduced with Version 79.4:}} {|width='100%'

| width='90120' | '''Signatures'''|{{Func|convert:dateTimedecode-tokey|$key as xs:string|xs:string}}<br />{{Func|convert:decode-mskey|$dateTime key as xs:string, $lax as xs:dateTimeboolean|xs:integerstring}}<br />

|Converts Decodes the specified {{Code|$dateTimekey}} (with the optional {{Code|$lax}} conversion method) to number of milliseconds since 1 Jan 1970the 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]].

* {{Code|<code>convert:dateTimedecode-to-mskey(name(xs<_0021/>))</code> yields <code>!</code>.* <code>json:dateTimedoc('1970"doc.json")//* ! convert:decode-01key(name())</code> yields the original string representation of all names of a JSON document.|-01T00:00:00Z| '''Errors'''))}} returns |{{CodeError|key|0#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}}

;Version 79.4

* Added: [[#convert:encode-key|convert:encode-key]], [[#convert:decode-key|convert:decode-key]]. ;Version 9.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:msinteger-to-dateTime|convert:msinteger-to-dateTime]]</code>, <code>[[#convert:dateTime-to-msinteger|convert:dateTime-to-msinteger]], [[#convert:integer-to-dayTime|convert:integer-to-dayTime]]</code>, [[#convert:dayTime-to-integer|convert:dayTime-to-integer]].