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 required processed. Hence, possible errors will be postponed, and no memory will be occupied by another expression, or if an a lazy item is serialized. Serialization of streamable items takes constant spaceas long as its content has not been requested yet.

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}}

Some functions are capable of consuming items in a ''streamable'' fashion* Lazy strings: data will never be cached, but instead passed on to another target (** {{Function|Fetch|fetch:text}}** {{Function|File|file, the calling expression, etc.). The following streaming functions are currently available:read-text}}

* <code>[[Conversion Module#convertSome functions are capable of consuming the contents of lazy items in a ''streamable'' fashion:binary-data will not be cached, but instead passed on to-bytes|convert:binary-to-bytes]]</code>* <code>[[Database Module#db:store|db:store]]</code>* <code>[[Fetch Module#file:write-text|file:write-text]]</code>* <code>[[File Module#file:write-binary|another target (file, the calling expression, etc.). The following streaming functions are currently available:write-binary]]</code>

The exemplary XQuery expression below demonstrates how large files can be downloaded and written * [[Archive Module]] (most functions)* Conversion Module: {{Function|Conversion|convert:binary-to a -string}}* File Module: {{Function|File|file with constant memory consumption: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 classlang="brush:'xquery"'>

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.

==streamlazy:materializecache== 

|-valign="top"| width='90120' | '''SignaturesSignature'''|{{Func|stream<pre>lazy:materialize|cache( $input as item ()*, $lazy as itemxs:boolean? := false()|) as item()}}*</pre>|-valign="top"

|Returns a materialized instance Caches the data of the specified lazy {{Code|$iteminput}}.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 stream is returned.Caching is advisable if an item is streamableprocessed more than once, its content will or if the data may not be retrievedavailable anymore at a later stage.|- valign="top"| '''Example'''|In the following example, and a new item containing file is deleted before its data will be content is returned. OtherTo avoid a “file not found” error when serializing the result, non-streamable items will simply the content must be returnedcached:<pre lang='xquery'>let $file := 'data.txt'let $text := lazy:cache(file:read-text($file))return (file:delete($file), $text)</pre>

==streamlazy:is-streamablelazy== 

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

|Checks if whether the specified {{Code|$item}} is streamablelazy.|} ==lazy:is-cached== {| width='100%'|- valign="top"| width='120' | '''Signature'''|<pre>lazy:is-cached( $item as item()) as xs:boolean</pre>|- valign="top"| '''Summary'''|Checks whether the contents of the specified {{Code|$item}} are cached. The function will always return {{Code|true}} for non-lazy items.