Changes

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

In contrast to standard XQuery items, a streamable lazy item contains only a reference to the actual data. The , and the data itself will only be retrieved if it is requested by an expression, or if the item is to be serializedprocessed. Hence, a streamable item only uses a few bytespossible errors will be postponed, and no additional memory is will be occupied during serializationby a lazy item as long as its content has not been requested yet.

The following BaseX functions return streamable lazy items:

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

* Streamable Lazy strings:** <code>[[{{Function|Fetch Module#fetch:text|fetch:text]]</code>}}** <code>[[{{Function|File Module#file:read-text|file:read-text]]</code>}}

Some functions are capable of consuming the contents of lazy items in a ''streamable'' fashion: data will never 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#convert:binary-to-bytes{{Function|Conversion|convert:binary-to-bytes]]</code>string}}* <code>[[Database File Module#db:store{{Function|db:store]]</code>* <code>[[File Module#|file:write-binary-text}}, {{Function|File|file:write-binary]]</code>text}} (if no encoding is specified)* <code>[[Fetch Database Module#file:write-text{{Function|Database|filedb:writeput-textbinary}}* [[Hashing Module]]</code>(all functions)

<pre classlang="brush:'xquery"'>

All functions and errors 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><nowiki>http://basex.org/errorsmodules/lazy</nowiki></code> namespace, which is statically bound to the {{Code|bxerrlazy}} prefix.<br/>

==streamlazy:materializecache==

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

|Returns a materialized instance Caches the data of the specified lazy {{Code|$valueinput}}items:<br />* if an item is streamable, its value will be data of lazy items are retrieved, and a new cached inside the item containing the value will be returned.* other, non-streamable lazy items will , or lazy items with cached data, are simply be passed through.Materialization * 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 a value an item is to be processed more than once, and is expensive to retrieve. It is get mandatory whenever or if the data may not be available anymore at a value is invalidated before it is requested (see the example below)later stage.|-valign="top"

|In the following example, a file will be is deleted before its content is returned. To avoid a "file “file not found" found” errorwhen serializing the result, the content will first must be materializedcached:<pre classlang="brush:'xquery"'>

let $data text := streamlazy:materializecache(file:read-text($file))return (file:delete($file), $datatext)

==streamlazy:is-streamablelazy== 

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

|Checks 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.

 * UpdateUpdated: [[#stream:materialize{{Function||stream:materialize]] }} extended to sequences.