Difference between revisions of "Output Module"

From BaseX Documentation
Jump to navigation Jump to search
 
(109 intermediate revisions by 4 users not shown)
Line 1: Line 1:
This module contains auxiliary [[Querying#Functions|XQuery Functions]], which can be used for testing and profiling the code. All functions are preceded by the <code>util:</code> prefix.  
+
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 the argument at runtime.
+
|Returns a single carriage return character ({{Code|&amp;#13;}}).
|-
 
| valign='top' | '''Rules'''
 
|This function dynamically evaluates <code>$expr</code> as XQuery expression and returns the resulting items.<br />
 
|-
 
| valign='top' | '''Examples'''
 
|The expression <code>util:eval("1+3")</code> returns <code>4</code>.<br />
 
 
|}
 
|}
  
==util:run==
+
==out:nl==
{|
+
 
|-
+
{| width='100%'
| valign='top' width='90' | '''Signatures'''
 
|<code><b>util:run</b>($input as xs:string) as item()*</code><br />
 
 
|-
 
|-
| valign='top' | '''Summary'''
+
| width='120' | '''Signatures'''
|Opens the argument as file and evaluates it at runtime.
+
|{{Code|'''out:nl()''' as xs:string}}
 
|-
 
|-
| valign='top' | '''Rules'''
+
| '''Summary'''
|This function opens <code>$input</code> as file, evaluates it as XQuery expression, and returns the resulting items.<br />
+
|Returns a single newline character ({{Code|&amp;#10;}}).
 
|}
 
|}
  
==util:mb==
+
==out:tab==
{|
+
 
|-
+
{| width='100%'
| 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'''
+
| width='120' | '''Signatures'''
|Measures the memory consumption for evaluating the argument.
+
|{{Code|'''out:tab()''' as xs:string}}
 
|-
 
|-
| valign='top' | '''Rules'''
+
| '''Summary'''
|This function measures the amount of memory that is needed to evaluate <code>$expr</code>. If the value of <code>$cache</code> is <code>true()</code>, the result will be cached. The returned <code>xs:double</code> value represents the amount of memory in megabytes.<br />
+
|Returns a single tabulator character ({{Code|&amp;#9;}}).
|-
 
| valign='top' | '''Examples'''
 
|The expression <code>util:mb("1 to 100000")</code> might return <code>0</code>.<br />The expression <code>util:mb("1 to 100000", true())</code> might return <code>26.678</code>.<br />
 
 
|}
 
|}
  
==util:ms==
+
==out:format==
{|
+
{| 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 />
+
|{{Func|out:format|$format as xs:string, $items as item() ...|xs:string}}<br />
 
|-
 
|-
| valign='top' | '''Summary'''
+
| '''Summary'''
|Measures the time needed for evaluating the argument.
+
|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' | '''Rules'''
+
| '''Errors'''
|This function measures the time needed to evaluate <code>$expr</code>. If the value of <code>$cache</code> is <code>true()</code>, the result will be cached. The returned <code>xs:double</code> value represents the needed time in milliseconds.<br />
+
|{{Error|format|#Errors}} The specified format is not valid.
 
|-
 
|-
| valign='top' | '''Examples'''
+
| '''Examples'''
|The expression <code>util:ms("1 to 100000")</code> might return <code>25.69</code>.<br />The expression <code>util:ms("1 to 100000", true())</code> might return <code>208.12</code>.<br />
+
|
 +
* {{Code|out:format("%b", true())}} returns {{Code|true}}.
 +
* {{Code|out:format("%06d", 256)}} returns {{Code|000256}}.
 +
* {{Code|out:format("%e", 1234.5678)}} returns {{Code|1.234568e+03}}.
 
|}
 
|}
  
==util:integer-to-base==
+
=Errors=
{|
+
 
|-
+
{| class="wikitable" width="100%"
| valign='top' width='90' | '''Signatures'''
+
! width="110"|Code
|<code><b>util:integer-to-base</b>($num as xs:integer, $base as xs:integer) as xs:string</code><br />
+
| Description
|-
 
| valign='top' | '''Summary'''
 
|Converts <code>$num</code> to base <code>$base</code>, interpreting it as a 64-bit unsigned integer. The first <code>$base</code> elements of the sequence <code>'0',..,'9','a',..,'z'</code> are used as digits.<br />
 
|-
 
| valign='top' | '''Rules'''
 
|Valid bases are <code>2, .., 36</code>.<br />
 
 
|-
 
|-
| valign='top' | '''Examples'''
+
|{{Code|format}}
|The expression <code>util:integer-to-base(22, 5)</code> returns <code>'42'</code>.<br /> The expression <code>util:integer-to-base(-1, 16)</code> returns <code>'ffffffffffffffff'</code>.<br />
+
|The specified format is not valid.
 
|}
 
|}
  
==util:integer-from-base==
+
=Changelog=
{|
 
|-
 
| valign='top' width='90' | '''Signatures'''
 
|<code><b>util:integer-from-base</b>($str as xs:string, $base as xs:integer) as xs:integer</code><br />
 
|-
 
| valign='top' | '''Summary'''
 
|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 />
 
|-
 
| valign='top' | '''Rules'''
 
|Valid bases are <code>2, .., 36</code>.<br /> If <code>$str</code> contains more than 64 bits of information, the result is truncated arbitarily.
 
|-
 
| valign='top' | '''Examples'''
 
|The expression <code>util:integer-from-base('42', 5)</code> returns <code>22</code>.<br /> The expression <code>util:integer-from-base('ffffffffffffffff', 16)</code> returns <code>-1</code>.<br /> The expression <code>util:integer-from-base('CAFEBABE', 16)</code> returns <code>3405691582</code>.<br /> The expression <code>util:integer-from-base(util:integer-to-base(123, 7), 7)</code> returns <code>123</code>.<br />
 
|}
 
  
==util:md5==
+
;Version 9.0
{|
 
|-
 
| 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'''
 
|The expression <code>util:md5('')</code> returns <code>'D41D8CD98F00B204E9800998ECF8427E'</code>.<br /> The expression <code>util:md5('BaseX')</code> returns <code>'0D65185C9E296311C0A2200179E479A2'</code>.<br />
 
|}
 
  
==util:sha1==
+
* Added: {{Function|Output|out:cr}}
{|
+
* Updated: error codes updated; errors now use the module namespace
|-
 
| 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'''
 
|The expression <code>util:sha1('')</code> returns <code>'DA39A3EE5E6B4B0D3255BFEF95601890AFD80709'</code>.<br /> The expression <code>util:sha1('BaseX')</code> returns <code>'3AD5958F0F27D5AFFDCA2957560F121D0597A4ED'</code>.<br />
 
|}
 
  
[[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.