Lazy Functions

This module contains functions for handling lazy items.

In contrast to standard XQuery items, 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 Base64 binaries:
  • fetch:binary
  • file:read-binary
  • db:get-binary
• Lazy strings:
  • fetch:text
  • 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 streamed to the target (file, the calling expression, etc.). The following functions have streaming capabilities:

• Archive Functions (most functions)
• Conversion Functions: convert:binary-to-string
• File Functions: file:write-binary, file:write-text (if no encoding is specified)
• Database Functions: db:put-binary
• Standard Functions: fn:hash

The XQuery expression below serves as an example on how large files can be downloaded and written to a file with constant memory consumption:

let $data := fetch:binary('https://files.basex.org/xml/xmark111mb.zip')
let $target := 'output.data'
return file:write-binary($target, $data)

A side effect of lazy evaluation is that not all errors can be caused by try/catch, as the error will only take place when its data is requested. However, you can enforce the evaluation by invoking lazy:cache:

try {
  fetch:binary('https://does.not/exist') => lazy:cache()
} catch * {
  'Did not succeed'
}

Conventions

All functions and errors in this module are assigned to the http://basex.org/modules/lazy namespace, which is statically bound to the lazy prefix.

Functions

lazy:cache

lazy:cache(
  $input  as item()*,
  $lazy   as xs:boolean?  := false()
) as item()*

let $file := 'data.txt'
let $text := lazy:cache(file:read-text($file))
return (file:delete($file), $text)

lazy:is-lazy

lazy:is-lazy(
  $item  as item()
) as xs:boolean

lazy:is-cached

lazy:is-cached(
  $item  as item()
) as xs:boolean

Changelog

• Updated: lazy:cache: $lazy argument added; support for sequences.

• Added: lazy:is-cached
• Updated: Renamed from Streaming Functions to Lazy Functions.

• Updated: stream:materialize extended to sequences.

• Added: New module added.