Bureaucrats, editor, reviewer, Administrators
13,550
edits
Changes
Jump to navigation
Jump to search
{{Mark|Updated with Version 9.0}}:
{{Mark|Updated with Version 9.0}}: Renamed from {{Code|convert:bytes-to-base64}}; argument type relaxed from {{Code|xs:byte}} to {{Code|xs:integer}}.
{{Mark|Updated with Version 9.0}}: Renamed from {{Code|convert:bytes-to-base64}}; argument type relaxed from {{Code|xs:byte}} to {{Code|xs:integer}}.
{{Mark|Updated with Version 9.0}}:
|-
|{{Code|base}}
|The specified base is not in the range 2-36.
→convert:decode-key
=Conventions=
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/>
|-
| '''Summary'''
|Converts the specifed {{CodesCode|$bytes}} ({{Code|xs:base64Binary}}, {{Code|xs:hexBinary}}) to a string:
* 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> (�).
==convert:integers-to-base64==
{| width='100%'
|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 particularly cheapvery efficient, as items of binary type are internally represented as byte arrays.
|-
| '''ErrorsExamples'''|* <code>convert:integers-to-base64(Q{{Error|binary|#Errorsjava:java.lang.String}} The input cannot be represented in the specified encoding.get-bytes('abc'))<br/code>converts a byte sequence to a {{Error|BXCO0002Code|#Errorsxs:base64Binary}} The specified encoding is invalid or not supporteditem.
|}
==convert:integers-to-hex==
{| width='100%'
|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 particularly cheapvery efficient, as items of binary type are internally represented as byte arrays.
|}
==convert:binary-to-bytesintegers==
{| width='100%'
|-
| width='120' | '''Signatures'''
|{{Func|convert:binary-to-bytesintegers|$bin binary as xs:anyAtomicType|xs:byteinteger*}}
|-
| '''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 arraysunsigned integers (octets).
|-
| '''Examples'''
|
* <code>convert:binary-to-bytesintegers(xs:base64BinaryhexBinary('QmFzZVggaXMgY29vbA==FF'))</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)255}}.
|}
==convert:binary-to-integersbytes== {{Mark|Introduced with Version 9.0}}:
{| width='100%'
|-
| width='120' | '''Signatures'''
|{{Func|convert:binary-to-integerbytes|$binary as xs:anyAtomicType|xs:integerbyte*}}
|-
| '''Summary'''
|Returns the specified {{Code|$binary}} ({{Code|xs:base64Binary}}, {{Code|xs:hexBinary}}) as a sequence of unsigned integers (octets)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-integerbytes(xs:hexBinarybase64Binary('FFQmFzZVggaXMgY29vbA=='))</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|255(66 97 115 101 88)}}.
|}
|
* {{Code|convert:dayTime-to-integer(xs:dayTimeDuration('PT1S'))}} yields {{Code|1000}}.
|}
=Keys=
==convert:encode-key==
{{Mark|Introduced with Version 9.4:}}
{| width='100%'
|-
| width='120' | '''Signatures'''
|{{Func|convert:encode-key|$key as xs:string|xs:string}}<br />{{Func|convert:encode-key|$key as xs:string, $lax as xs:boolean|xs:string}}<br />
|-
| '''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:
* 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 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:encode-key("!") } { }</code> creates a new element with an encoded name: <code><_0021/></code>.
|}
==convert:decode-key==
{{Mark|Introduced with Version 9.4:}}
{| width='100%'
|-
| width='120' | '''Signatures'''
|{{Func|convert:decode-key|$key as xs:string|xs:string}}<br />{{Func|convert:decode-key|$key as xs:string, $lax as xs:boolean|xs:string}}<br />
|-
| '''Summary'''
|Decodes the specified {{Code|$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: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.
|-
| '''Errors'''
|{{Error|key|#Errors}} The specified key cannot be decoded to its original representation.
|}
=Errors=
{| class="wikitable" width="100%"
| Description
|-
|{{Code|stringbase}}|The input specified base is an invalid XML string, or not in the wrong encoding has been specifiedrange 2-36.
|-
|{{Code|binary}}
|{{Code|encoding}}
|The specified encoding is invalid or not supported.
|-
|{{Code|integer}}
|The specified digit is not valid for the given range.
|-
|{{Code|key}}
|The specified key cannot be decoded to its original representation.
|-
|{{Code|string}}
|The input is an invalid XML string, or the wrong encoding has been specified.
|}
=Changelog=
;Version 9.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 updatesupdated; errors now use the module namespace
;Version 8.5
