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. The , and the data itself will only be retrieved if it is requiredprocessed. Hence, possible errors will be postponed, e.g. if it needs to and no memory will be serialized or processed occupied by another expressiona lazy item as long as its content has not been requested yet.

Currently, the The following BaseX functions return streamable lazy items:

* <code>[[Database Module#dbLazy Base64 binaries:retrieve|db:retrieve]]</code>* <code>[[* {{Function|Fetch Module#fetch:binary|fetch:binary]]</code>}}* <code>[[Fetch Module#fetch:text* {{Function|fetch:text]]</code>* <code>[[File Module#file:read-binary|file:read-binary]]</code>}}* <code>[[File Module#file:read-text* {{Function|Database|filedb:readget-text]]</code>binary}}

The following functions are capable of processing streamed input* 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 cached, but instead passed on to another target (file, the calling expression, etc.). The following streaming functions are currently available: * <code>[[Archive Module]] (most functions)* Conversion Module#: {{Function|Conversion|convert:binary-to-bytesstring}}* File Module: {{Function|File|convertfile:write-binary-totext}}, {{Function|File|file:write-bytes]]</code>text}} (if no encoding is specified)* <code>[[Database Module#db:store{{Function|Database|db:store]]</code>put-binary}}* <code>[[Fetch Hashing Module#]] (all functions) The XQuery expression below serves as an example on how large files can be downloaded and written to a filewith constant memory consumption:write-text|file:write-text]] </codepre lang='xquery'>* <code>[[File Module#file:write-binary|file('output.data', fetch:write-binary]]('http://files.basex.org/xml/xmark111mb.zip'))</codepre> If lazy items are serialized, they will be streamed 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.