Difference between revisions of "Lazy Module"

From BaseX Documentation
Jump to navigation Jump to search
m (Text replace - "assigned to the {{Code|http://basex.org/errors}} namespace" to "assigned to the <code><nowiki>http://basex.org/errors</nowiki></code> namespace")
Line 30: Line 30:
  
 
All functions in this module are assigned to the {{Code|http://basex.org/modules/stream}} namespace, which is statically bound to the {{Code|stream}} prefix.<br/>
 
All functions in this module are assigned to the {{Code|http://basex.org/modules/stream}} namespace, which is statically bound to the {{Code|stream}} prefix.<br/>
All errors are assigned to the {{Code|http://basex.org/errors}} namespace, which is statically bound to the {{Code|bxerr}} prefix.
+
All errors are assigned to the <code><nowiki>http://basex.org/errors</nowiki></code> namespace, which is statically bound to the {{Code|bxerr}} prefix.
  
 
=Functions=
 
=Functions=

Revision as of 16:27, 7 April 2015

This XQuery Module contains functions for handling streamable items.

In contrast to standard XQuery items, a streamable item contains only a reference to the actual data. The data itself will be retrieved if it is requested by an expression, or if the item is to be serialized. Hence, a streamable item only uses a few bytes, and no additional memory is occupied during serialization.

The following BaseX functions return streamable items:

Some functions are capable of consuming items in a streamable fashion: data will never be cached, but instead passed on to another target (file, the calling expression, etc.). The following streaming functions are currently available:

The XQuery expression below serves as an example on how large files can be downloaded and written to a file with constant memory consumption:

file:write-binary('output.data', fetch:binary('http://files.basex.org/xml/xmark111mb.zip'))

Conventions

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

Functions

stream:materialize

Signatures stream:materialize($value as item()*) as item()*
Summary Returns a materialized instance of the specified $value:
  • if an item is streamable, its value will be retrieved, and a new item containing the value will be returned.
  • other, non-streamable items will simply be passed through.

Materialization is advisable if a value is to be processed more than once, and is expensive to retrieve. It is get mandatory whenever a value is invalidated before it is requested (see the example below).

Example In the following example, a file will be deleted before its content is returned. To avoid a "file not found" error, the content will first be materialized:
let $file := 'data.txt'
let $data := stream:materialize(file:read-text($file))
return (file:delete($file), $data)

stream:is-streamable

Signatures stream:is-streamable($item as item()) as item()
Summary Checks whether the specified $item is streamable.

Changelog

Version 8.0

This module was introduced with Version 7.7.