package octez-libs

  1. Overview
  2. Docs
package octez-libs
Legend:
Library
Module
Module type
Parameter
Class
Class type

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.

API

module type S = sig ... end
OCaml

Innovation. Community. Security.

GitHub Discord Twitter Peertube RSS
About
Changelog Releases Industrial Users Academic Users Why OCaml
Ecosystem
Packages Community Events OCaml Planet Jobs
Resources
Install OCaml Get Started Platform Tools Language Manual Standard Library API Books Exercises Papers OCaml Playground Logo
Policies
Carbon Footprint Governance Privacy Code of Conduct