Difference between revisions of "Conversion Module"

From BaseX Documentation
Jump to navigation Jump to search
Line 17: Line 17:
 
|-
 
|-
 
| '''Summary'''
 
| '''Summary'''
|Converts the specifed binary data ({{Code|xs:base64Binary}}, {{Code|xs:hexBinary}}) to a string:
+
|Converts the specifed {{Codes|$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;).
Line 34: Line 34:
 
|-
 
|-
 
| width='120' | '''Signatures'''
 
| width='120' | '''Signatures'''
|{{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}}
+
|{{Func|convert:string-to-base64|$string as xs:string|xs:base64Binary}}<br/>{{Func|convert:string-to-base64|$string as xs:string, $encoding as xs:string|xs:base64Binary}}
 
|-
 
|-
 
| '''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.
 
|-
 
|-
 
| '''Errors'''
 
| '''Errors'''
Line 52: Line 52:
 
|-
 
|-
 
| width='120' | '''Signatures'''
 
| width='120' | '''Signatures'''
|{{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}}
+
|{{Func|convert:string-to-hex|$string as xs:string|xs:hexBinary}}<br/>{{Func|convert:string-to-hex|$string as xs:string, $encoding as xs:string|xs:hexBinary}}
 
|-
 
|-
 
| '''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.
 
|-
 
|-
 
| '''Errors'''
 
| '''Errors'''
Line 67: Line 67:
 
=Binary Data=
 
=Binary Data=
  
==convert:bytes-to-base64==
+
==convert:integers-to-base64==
  
{{Mark|Updated with Version 9.0}}: 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}}.
  
 
{| width='100%'
 
{| width='100%'
 
|-
 
|-
 
| width='120' | '''Signatures'''
 
| width='120' | '''Signatures'''
|{{Func|convert:bytes-to-base64|$input as xs:integer*|xs:base64Binary}}
+
|{{Func|convert:integers-to-base64|$integers as xs:integer*|xs:base64Binary}}
 
|-
 
|-
 
| '''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 particularly cheap, as items of binary type are internally represented as byte arrays.
 
|-
 
|-
 
| '''Errors'''
 
| '''Errors'''
Line 85: Line 85:
 
|}
 
|}
  
==convert:bytes-to-hex==
+
==convert:integers-to-hex==
  
{{Mark|Updated with Version 9.0}}: 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}}.
  
 
{| width='100%'
 
{| width='100%'
 
|-
 
|-
 
| width='120' | '''Signatures'''
 
| width='120' | '''Signatures'''
|{{Func|convert:bytes-to-hex|$input as xs:integer*|xs:hexBinary}}
+
|{{Func|convert:integers-to-hex|$integers as xs:integer*|xs:hexBinary}}
 
|-
 
|-
 
| '''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 particularly cheap, as items of binary type are internally represented as byte arrays.
 
|}
 
|}
  
Line 108: Line 108:
 
|-
 
|-
 
| '''Summary'''
 
| '''Summary'''
|Returns the specified binary data ({{Code|xs:base64Binary}}, {{Code|xs:hexBinary}}) as a sequence of bytes.
+
|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'''
 
| '''Examples'''
Line 116: Line 117:
 
|}
 
|}
  
==convert:binary-to-integer==
+
==convert:binary-to-integers==
  
 
{{Mark|Introduced with Version 9.0}}:
 
{{Mark|Introduced with Version 9.0}}:
Line 123: Line 124:
 
|-
 
|-
 
| width='120' | '''Signatures'''
 
| width='120' | '''Signatures'''
|{{Func|convert:binary-to-integer|$bin as xs:anyAtomicType|xs:integer*}}
+
|{{Func|convert:binary-to-integer|$binary as xs:anyAtomicType|xs:integer*}}
 
|-
 
|-
 
| '''Summary'''
 
| '''Summary'''
|Returns the specified binary data ({{Code|xs:base64Binary}}, {{Code|xs:hexBinary}}) as a sequence of unsigned integers (octets).
+
|Returns the specified {{Code|$binary}} ({{Code|xs:base64Binary}}, {{Code|xs:hexBinary}}) as a sequence of unsigned integers (octets).
 
|-
 
|-
 
| '''Examples'''
 
| '''Examples'''
Line 140: Line 141:
 
|-
 
|-
 
| width='120' | '''Signatures'''
 
| width='120' | '''Signatures'''
|{{Func|convert:integer-to-base|$num as xs:integer, $base as xs:integer|xs:string}}<br />
+
|{{Func|convert:integer-to-base|$number as xs:integer, $base as xs:integer|xs:string}}<br />
 
|-
 
|-
 
| '''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 />
 
|-
 
|-
 
| '''Errors'''
 
| '''Errors'''
Line 159: Line 160:
 
|-
 
|-
 
| width='120' | '''Signatures'''
 
| width='120' | '''Signatures'''
|{{Func|convert:integer-from-base|$str as xs:string, $base as xs:integer|xs:integer}}<br />
+
|{{Func|convert:integer-from-base|$string as xs:string, $base as xs:integer|xs:integer}}<br />
 
|-
 
|-
 
| '''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.
 
|-
 
|-
 
| '''Errors'''
 
| '''Errors'''
Line 182: Line 183:
 
|-
 
|-
 
| width='120' | '''Signatures'''
 
| width='120' | '''Signatures'''
|{{Func|convert:integer-to-dateTime|$ms as xs:integer|xs:dateTime}}<br />
+
|{{Func|convert:integer-to-dateTime|$milliseconds as xs:integer|xs:dateTime}}<br />
 
|-
 
|-
 
| '''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 />
 
|-
 
|-
 
| '''Examples'''
 
| '''Examples'''
Line 202: Line 203:
 
|-
 
|-
 
| '''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 />
 
|-
 
|-
 
| '''Examples'''
 
| '''Examples'''
Line 214: Line 215:
 
|-
 
|-
 
| width='120' | '''Signatures'''
 
| width='120' | '''Signatures'''
|{{Func|convert:integer-to-dayTime|$ms as xs:integer|xs:dayTimeDuration}}<br />
+
|{{Func|convert:integer-to-dayTime|$milliseconds as xs:integer|xs:dayTimeDuration}}<br />
 
|-
 
|-
 
| '''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 />
 
|-
 
|-
 
| '''Examples'''
 
| '''Examples'''
Line 232: Line 233:
 
|-
 
|-
 
| '''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 />
 
|-
 
|-
 
| '''Examples'''
 
| '''Examples'''
Line 267: Line 268:
 
;Version 9.0
 
;Version 9.0
  
* Added: [[#convert:bytes-to-integer|convert:bytes-to-integer]].
+
* Added: [[#convert:binary-to-integers|convert:binary-to-integers]].
* 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}}.
+
* 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 updates; errors now use the module namespace
 
* Updated: error codes updates; errors now use the module namespace
  

Revision as of 10:39, 21 November 2017

This XQuery Module contains functions to convert data between different formats.

Conventions

Template:Mark:

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

convert:binary-to-string

Signatures convert:binary-to-string($bytes as xs:anyAtomicType) as xs:string
convert:binary-to-string($bytes as xs:anyAtomicType, $encoding as xs:string) as xs:string
convert:binary-to-string($bytes as xs:anyAtomicType, $encoding as xs:string, $fallback as xs:boolean) as xs:string
Summary Converts the specifed Template:Codes (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

Signatures convert:string-to-base64($string as xs:string) as xs:base64Binary
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

Signatures convert:string-to-hex($string as xs:string) as xs:hexBinary
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

convert:integers-to-base64

Template:Mark: Renamed from convert:bytes-to-base64; argument type relaxed from xs:byte to xs:integer.

Signatures 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 particularly cheap, as items of binary type are internally represented as byte arrays.
Errors binary: The input cannot be represented in the specified encoding.
BXCO0002: The specified encoding is invalid or not supported.

convert:integers-to-hex

Template:Mark: Renamed from convert:bytes-to-base64; argument type relaxed from xs:byte to xs:integer.

Signatures 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 particularly cheap, as items of binary type are internally represented as byte arrays.

convert:binary-to-bytes

Signatures convert:binary-to-bytes($bin 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).

|}

convert:binary-to-integers

Template:Mark:

Signatures convert:binary-to-integer($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-integer(xs:hexBinary('FF')) yields 255.

Numbers

convert:integer-to-base

Signatures 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

Signatures 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

convert:integer-to-dateTime

Signatures 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

Signatures 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

Signatures 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

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

Errors

Template:Mark:

Code Description
string The input is an invalid XML string, or the wrong encoding has been specified.
binary The input cannot be converted to a binary representation.
encoding The specified encoding is invalid or not supported.
base The specified base is not in the range 2-36.
integer The specified digit is not valid for the given range.

Changelog

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.