package tezos-lwt-result-stdlib

List

A replacement for Stdlib.List which:

• replaces the exception-raising functions by exception-safe variants,
• provides Lwt-, result- and Lwt-result-aware traversors.

List is intended to shadow both Stdlib.List and Lwt_list.

Basics

Checkout Lwtreslib for an introduction to the naming and semantic convention of Lwtreslib. In a nutshell:

• Stdlib functions that raise exceptions are replaced by safe variants (typically returning option).
• The _e suffix is for result-aware traversors ("e" stands for "error"), _s and _p are for Lwt-aware, and _es and _ep are for Lwt-result-aware.
• _e, _s, and _es traversors are fail-early: they stop traversal as soon as a failure (Error or Fail) occurs; _p and _ep traversors are best-effort: they only resolve once all of the intermediate promises have, even if a failure occurs.

Double-traversal and combine

Note that double-list traversors (iter2, map2, etc., and also combine) take an additional when_different_lengths parameter. This is to control the error that is returned when the two lists passed as arguments have different lengths.

This mechanism is a replacement for Stdlib.List.iter2 (etc.) raising Invalid_argument.

Note that, as per the fail-early behaviour mentioned above, _e, _s, and _es traversors will have already processed the common-prefix before the error is returned.

Because the best-effort behaviour of _p and _ep is unsatisfying for this failure case, double parallel traversors are omitted from this library. (Specifically, it is not obvious whether nor how the when_different_lengths error should be composed with the other errors.)

To obtain a different behaviour for sequential traversors, or to process two lists in parallel, you can use combine or any of the alternatives that handles the error differently: combine_drop, combine_with_leftovers. Finally, the rev_combine is provided to allow to avoid multiple-reversing.

Special considerations

Because they traverse the list from right-to-left, the fold_right2 function and all its variants fail with when_different_lengths before any of the processing starts. Whilst this is still within the fail-early behaviour, it may be surprising enough that it requires mentioning here.

Because they may return early, for_all2 and exists2 and all their variants may return Ok _ even though the arguments have different lengths.