Changes

This [[Module Library|XQuery Module]] contains functions for handling ''streamablelazy'' items.

In contrast to conventional standard XQuery items, streamable items may take up much less space, because they only contain a lazy item contains a reference to the actual data, and the data itself will only be retrieved if it is processed. Hence, possible errors will be postponed, and no memory will be occupied by a lazy item as long as its content has not been requested yet. The following BaseX functions return lazy items: * Lazy Base64 binaries:** {{Function|Fetch|fetch:binary}}** {{Function|File|file:read-binary}}** {{Function|Database|db:get-binary}} * Lazy strings:** {{Function|Fetch|fetch:text}}** {{Function|File|file:read-text}} Some functions are capable of consuming the contents of lazy items in a ''streamable'' fashion: data will not be retrieved until cached, but instead passed on to another target (file, the item is requiredcalling expression, eetc.g). The following streaming functions are currently available: * [[Archive Module]] (most functions)* Conversion Module: {{Function|Conversion|convert:binary-to-string}}* File Module: {{Function|File|file:write-binary-text}}, {{Function|File|file:write-text}} (if no encoding is specified)* Database Module: {{Function|Database|db:put-binary}}* [[Hashing Module]] (all functions) The XQuery expression below serves as an example on how large files can be downloaded and written to a file with constant memory consumption: <pre lang='xquery'>file:write-binary('output.data needs to ', fetch:binary('http://files.basex.org/xml/xmark111mb.zip'))</pre> If lazy items are serialized, they will be serialized or processed by another expressionstreamed as well.

All functions and errors in this module are assigned to the {{Code|<code><nowiki>http://basex.org/modules/stream}} lazy</nowiki></code> namespace, which is statically bound to the {{Code|streamlazy}} prefix.<br/>All errors are assigned to the {{Code|http://basex.org/errors}} namespace, which is statically bound to the {{Code|bxerr}} prefix.

==lazy:cache== {| width='100%'|- valign="top"| width='120' | '''Signature'''|<pre>lazy:cache( $input as item()*, $lazy as xs:boolean? := false()) as item()*</pre>|- valign="top"| '''Summary'''|Caches the data of lazy {{Code|$input}} items:<br/>* data of lazy items are retrieved and cached inside the item.* non-lazy items, or lazy items with cached data, are simply passed through.* If {{Code|$lazy}} is set to {{Code|true()}}, caching is deferred until the data is eventually requested. Streaming will be disabled: Data will be cached before a streamis returned.Caching is advisable if an item is processed more than once, or if the data may not be available anymore at a later stage.|- valign="top"| '''Example'''|In the following example, a file is deleted before its content is returned. To avoid a “file not found” error when serializing the result, the content must be cached:<pre lang='xquery'>let $file := 'data.txt'let $text := lazy:cache(file:read-text($file))return (file:delete($file), $text)</pre>|} ==lazy:materializeis-lazy== 

|-valign="top"| width='90120' | '''SignaturesSignature'''|{{Func|stream<pre>lazy:materialize|is-lazy( $item as item()|item()}}as xs:boolean</pre>|-valign="top"

|Returns a materialized instance of Checks whether the specified {{Code|$item}}.<br />If an item is streamable, its content will be retrieved, and a new item containing its data will be returned. Other, non-streamable items will simply be returnedlazy.

==streamlazy:is-streamablecached== 

|-valign="top"| width='90120' | '''SignaturesSignature'''|{{Func|stream<pre>lazy:is-streamable|cached( $item as item()|item()}}as xs:boolean</pre>|-valign="top"

|Checks if whether the contents of the specified {{Code|$item}} is streamableare cached. The function will always return {{Code|true}} for non-lazy items.