Difference between revisions of "Output Module"

From BaseX Documentation
Jump to navigation Jump to search
m (Text replace - "<font color='orangered'>Version 7.0</font>" to "{{Version|7.0}}")
 
(75 intermediate revisions by 2 users not shown)
Line 1: Line 1:
This module contains auxiliary [[Querying#Functions|XQuery Functions]], which can be used to perform data conversions and test and profile code snippets. All functions are preceded by the <code>util:</code> prefix, which is linked to the <code>http://www.basex.org/util</code> namespace.
+
This [[Module Library|XQuery Module]] contains functions for simplifying formatted data output.
  
==util:eval==
+
=Conventions=
{|
+
 
 +
All functions and errors in this module are assigned to the <code><nowiki>http://basex.org/modules/out</nowiki></code> namespace, which is statically bound to the {{Code|out}} prefix.<br/>
 +
 
 +
=Functions=
 +
 
 +
==out:cr==
 +
 
 +
{| width='100%'
 
|-
 
|-
| valign='top' width='90' | '''Signatures'''
+
| width='120' | '''Signatures'''
|<code><b>util:eval</b>($expr as xs:string) as item()*</code><br />
+
|{{Code|'''out:cr()''' as xs:string}}
 
|-
 
|-
| valign='top' | '''Summary'''
+
| '''Summary'''
|Evaluates <code>$expr</code> as XQuery expression at runtime and returns the resulting items.<br />
+
|Returns a single carriage return character ({{Code|&amp;#13;}}).
|-
 
| valign='top' | '''Examples'''
 
|
 
* <code>util:eval("1+3")</code> returns <code>4</code>.<br />
 
 
|}
 
|}
  
==util:run==
+
==out:nl==
{|
 
|-
 
| valign='top' width='90' | '''Signatures'''
 
|<code><b>util:run</b>($input as xs:string) as item()*</code><br />
 
|-
 
| valign='top' | '''Summary'''
 
|Opens <code>$input</code> as file, evaluates it as XQuery expression at runtime, and returns the resulting items.<br />
 
|}
 
  
==util:format==
+
{| width='100%'
{|
 
|-
 
| valign='top' width='90' | '''Signatures'''
 
|<code><b>util:format</b>($format as xs:string, $item1 as item(), ...) as xs:string</code><br />
 
 
|-
 
|-
| valign='top' | '''Summary'''
+
| width='120' | '''Signatures'''
|Returns a formatted string. <code>$item1</code> and all following items are applied to the <code>$format</code> string, according to [http://download.oracle.com/javase/1.5.0/docs/api/java/util/Formatter.html#syntax Java’s printf syntax].
+
|{{Code|'''out:nl()''' as xs:string}}
 
|-
 
|-
| valign='top' | '''Examples'''
+
| '''Summary'''
|
+
|Returns a single newline character ({{Code|&amp;#10;}}).
* <code>util:format("%b", true())</code> returns <code>true</code>.
 
* <code>util:format("%06d", 256)</code> returns <code>000256</code>.
 
* <code>util:format("%e", 1234.5678)</code> returns <code>1.234568e+03</code>.
 
 
|}
 
|}
  
==util:mb==
+
==out:tab==
{|
 
|-
 
| valign='top' width='90' | '''Signatures'''
 
|<code><b>util:mb</b>($expr as item()) as xs:double</code><br /><code><b>util:mb</b>($expr as item(), $cache as xs:boolean) as xs:double</code><br />
 
|-
 
| valign='top' | '''Summary'''
 
|Measures the amount of memory that is needed to evaluate <code>$expr</code>.<br/>The returned <code>xs:double</code> value represents the amount of memory in megabytes.<br />If the value of <code>$cache</code> is <code>true()</code>, the result will be cached. <br/>
 
|-
 
| valign='top' | '''Examples'''
 
|
 
* <code>util:mb("1 to 100000")</code> might return <code>0</code>.
 
* <code>util:mb("1 to 100000", true())</code> might return <code>26.678</code>.
 
|}
 
  
==util:ms==
+
{| width='100%'
{|
 
 
|-
 
|-
| valign='top' width='90' | '''Signatures'''
+
| width='120' | '''Signatures'''
|<code><b>util:ms</b>($expr as item()) as xs:double</code><br /><code><b>util:ms</b>($expr as item(), $cache as xs:boolean) as xs:double</code><br />
+
|{{Code|'''out:tab()''' as xs:string}}
 
|-
 
|-
| valign='top' | '''Summary'''
+
| '''Summary'''
|Measures the time needed to evaluate <code>$expr</code>.<br/>The returned <code>xs:double</code> value represents the needed time in milliseconds.<br />If the value of <code>$cache</code> is <code>true()</code>, the result will be cached. <br />
+
|Returns a single tabulator character ({{Code|&amp;#9;}}).
|-
 
| valign='top' | '''Examples'''
 
|
 
* <code>util:ms("1 to 100000")</code> might return <code>25.69</code>.
 
* <code>util:ms("1 to 100000", true())</code> might return <code>208.12</code>.
 
 
|}
 
|}
  
==util:integer-to-base==
+
==out:format==
{|
+
{| width='100%'
 
|-
 
|-
| valign='top' width='90' | '''Signatures'''
+
| width='120' | '''Signatures'''
|<code><b>util:integer-to-base</b>($num as xs:integer, $base as xs:integer) as xs:string</code><br />
+
|{{Func|out:format|$format as xs:string, $items as item() ...|xs:string}}<br />
|-
 
| valign='top' | '''Summary'''
 
|Converts <code>$num</code> to base <code>$base</code>, interpreting it as a 64-bit unsigned integer.<br />The first <code>$base</code> elements of the sequence <code>'0',..,'9','a',..,'z'</code> are used as digits.<br />Valid bases are <code>2, .., 36</code>.<br />
 
|-
 
| valign='top' | '''Examples'''
 
|
 
* <code>util:integer-to-base(-1, 16)</code> returns the hexadecimal string <code>'ffffffffffffffff'</code>.
 
* <code>util:integer-to-base(22, 5)</code> returns <code>'42'</code>.
 
|}
 
 
 
==util:integer-from-base==
 
{|
 
 
|-
 
|-
| valign='top' width='90' | '''Signatures'''
+
| '''Summary'''
|<code><b>util:integer-from-base</b>($str as xs:string, $base as xs:integer) as xs:integer</code><br />
+
|Returns a formatted string. The remaining arguments specified by {{Code|$items}} are applied to the {{Code|$format}} string, according to [https://docs.oracle.com/javase/8/docs/api/java/util/Formatter.html#syntax Java’s printf syntax].
 
|-
 
|-
| valign='top' | '''Summary'''
+
| '''Errors'''
|Decodes an <code>xs:integer</code> from <code>$str</code>, assuming that it's encoded in base <code>$base</code>.<br /> The first <code>$base</code> elements of the sequence <code>'0',..,'9','a',..,'z'</code> are allowed as digits, case doesn't matter. <br />Valid bases are <code>2, .., 36</code>.<br /> If <code>$str</code> contains more than 64 bits of information, the result is truncated arbitarily.
+
|{{Error|format|#Errors}} The specified format is not valid.
 
|-
 
|-
| valign='top' | '''Examples'''
+
| '''Examples'''
 
|
 
|
* <code>util:integer-from-base('ffffffffffffffff', 16)</code> returns <code>-1</code>.
+
* {{Code|out:format("%b", true())}} returns {{Code|true}}.
* <code>util:integer-from-base('CAFEBABE', 16)</code> returns <code>3405691582</code>.
+
* {{Code|out:format("%06d", 256)}} returns {{Code|000256}}.
* <code>util:integer-from-base('42', 5)</code> returns <code>22</code>.
+
* {{Code|out:format("%e", 1234.5678)}} returns {{Code|1.234568e+03}}.
* <code>util:integer-from-base(util:integer-to-base(123, 7), 7)</code> returns <code>123</code>.
 
 
|}
 
|}
  
==util:md5==
+
=Errors=
{|
 
|-
 
| valign='top' width='90' | '''Signatures'''
 
|<code><b>util:md5</b>($str as xs:string) as xs:hexBinary</code><br />
 
|-
 
| valign='top' | '''Summary'''
 
|Calculates the MD5 hash of the given string <code>$str</code>.<br />
 
|-
 
| valign='top' | '''Examples'''
 
|
 
* <code>util:md5("")</code> returns <code>'D41D8CD98F00B204E9800998ECF8427E'</code>.
 
* <code>util:md5('BaseX')</code> returns <code>'0D65185C9E296311C0A2200179E479A2'</code>.
 
|}
 
  
==util:sha1==
+
{| class="wikitable" width="100%"
{|
+
! width="110"|Code
|-
+
| Description
| valign='top' width='90' | '''Signatures'''
 
|<code><b>util:sha1</b>($str as xs:string) as xs:hexBinary</code><br />
 
|-
 
| valign='top' | '''Summary'''
 
|Calculates the SHA1 hash of the given string <code>$str</code>.<br />
 
 
|-
 
|-
| valign='top' | '''Examples'''
+
|{{Code|format}}
|
+
|The specified format is not valid.
* <code>util:sha1("")</code> returns <code>'DA39A3EE5E6B4B0D3255BFEF95601890AFD80709'</code>.
 
* <code>util:sha1("BaseX")</code> returns <code>'3AD5958F0F27D5AFFDCA2957560F121D0597A4ED'</code>.
 
 
|}
 
|}
  
==util:crc32==
+
=Changelog=
{|
 
|-
 
| valign='top' width='90' | '''Signatures'''
 
|<code><b>util:crc32</b>($str as xs:string) as xs:hexBinary</code><br />
 
|-
 
| valign='top' | '''Summary'''
 
|Calculates the CRC32 check sum of the given string <code>$str</code>.<br />
 
|-
 
| valign='top' | '''Examples'''
 
|
 
* <code>util:crc32("")</code> returns <code>'00000000'</code>.
 
* <code>util:crc32("BaseX")</code> returns <code>'4C06FC7F'</code>.
 
|}
 
  
==util:to-bytes==
+
;Version 9.0
{|
 
|-
 
| valign='top' width='90' | '''Signatures'''
 
|<code><b>util:to-bytes</b>($bin as xs:base64Binary) as xs:byte*</code>
 
|-
 
| valign='top' | '''Summary'''
 
|Extracts the bytes from the given binary data <code>$bin</code>.
 
|-
 
| valign='top' | '''Examples'''
 
|
 
* <code>util:to-bytes(xs:base64Binary('QmFzZVggaXMgY29vbA=='))</code> returns the sequence <code>(66, 97, 115, 101, 88, 32, 105, 115, 32, 99, 111, 111, 108)</code>.
 
* <code>util:to-bytes(xs:base64Binary(xs:hexBinary("4261736558")))</code> returns the sequence <code>(66 97 115 101 88)</code>.
 
|}
 
  
==util:uuid==
+
* Added: {{Function|Output|out:cr}}
{|
+
* Updated: error codes updated; errors now use the module namespace
|-
 
| valign='top' width='90' | '''Signatures'''
 
|<code><b>util:uuid</b>() as xs:string</code>.
 
|-
 
| valign='top' | '''Summary'''
 
|Creates a random universally unique identifier (UUID), represented as 128-bit value. Introduced with {{Version|7.0}}
 
|-
 
| valign='top' | '''Examples'''
 
|
 
* <code>util:uuid() ne util:uuid()</code> will (most probably) return the boolean value <code>true</code>.
 
|}
 
  
[[Category:XQuery]]
+
Introduced with Version 7.3. Functions have been adopted from the obsolete Utility Module.

Latest revision as of 14:59, 30 October 2018

This XQuery Module contains functions for simplifying formatted data output.

Conventions[edit]

All functions and errors in this module are assigned to the http://basex.org/modules/out namespace, which is statically bound to the out prefix.

Functions[edit]

out:cr[edit]

Signatures out:cr() as xs:string
Summary Returns a single carriage return character (&#13;).

out:nl[edit]

Signatures out:nl() as xs:string
Summary Returns a single newline character (&#10;).

out:tab[edit]

Signatures out:tab() as xs:string
Summary Returns a single tabulator character (&#9;).

out:format[edit]

Signatures out:format($format as xs:string, $items as item() ...) as xs:string
Summary Returns a formatted string. The remaining arguments specified by $items are applied to the $format string, according to Java’s printf syntax.
Errors format: The specified format is not valid.
Examples
  • out:format("%b", true()) returns true.
  • out:format("%06d", 256) returns 000256.
  • out:format("%e", 1234.5678) returns 1.234568e+03.

Errors[edit]

Code Description
format The specified format is not valid.

Changelog[edit]

Version 9.0
  • Added: out:cr
  • Updated: error codes updated; errors now use the module namespace

Introduced with Version 7.3. Functions have been adopted from the obsolete Utility Module.