Difference between revisions of "Lazy Module"
m (Text replace - "| width='90' | '''Signatures'''" to "| width='120' | '''Signatures'''") |
|||
Line 35: | Line 35: | ||
==stream:materialize== | ==stream:materialize== | ||
+ | |||
+ | {{Mark|Updated with Version 8.0}}: Extended to sequences. | ||
+ | |||
+ | |||
{| width='100%' | {| width='100%' | ||
|- | |- | ||
| width='120' | '''Signatures''' | | width='120' | '''Signatures''' | ||
− | |{{Func|stream:materialize|$ | + | |{{Func|stream:materialize|$value as item()*|item()*}} |
|- | |- | ||
| '''Summary''' | | '''Summary''' | ||
− | |Returns a materialized instance of the specified {{Code|$ | + | |Returns a materialized instance of the specified {{Code|$value}}:<br /> |
* if an item is streamable, its value will be retrieved, and a new item containing the value will be returned. | * 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. | * other, non-streamable items will simply be passed through. | ||
Line 66: | Line 70: | ||
=Changelog= | =Changelog= | ||
+ | |||
+ | ;Version 8.0 | ||
+ | * Update: [[#stream:materialize|stream:materialize]] extended to sequences. | ||
This module was introduced with Version 7.7. | This module was introduced with Version 7.7. | ||
[[Category:XQuery]] | [[Category:XQuery]] |
Revision as of 14:24, 8 August 2014
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:
- Streamable Base64 binaries:
- Streamable strings:
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
Template:Mark: Extended to sequences.
Signatures | stream:materialize($value as item()*) as item()*
|
Summary | Returns a materialized instance of the specified $value :
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
- Update: stream:materialize extended to sequences.
This module was introduced with Version 7.7.