package travesty

  1. Overview
  2. Docs
package travesty
Legend:
Library
Module
Module type
Parameter
Class
Class type

Option extensions.

This module contains various extensions for Base's Option module, including adding monadic traversal.

type 'a t = 'a option

Defined to let this module be used directly in chaining operations etc.

Travesty instances

Options are traversable.

include Travesty.Traversable_types.S1 with type 'a t := 'a t
module On (M : Base.Applicative.S) : Travesty.Traversable_types.S1_on_applicative with type 'a t := 'a t and module M := M

On implements applicative folding and mapping operators for a given applicative M, including arity-1 specific operators.

module On_monad (M : Base.Monad.S) : Travesty.Traversable_types.S1_on_monad with type 'a t := 'a t and module M := M

On_monad implements applicative folding and mapping operators for a given monad M, including arity-1 specific operators.

module With_errors : Travesty.Traversable_types.S1_on_monad with type 'a t := 'a t and module M := Base.Or_error

With_errors is shorthand for On_monad (Or_error).

include Travesty.Traversable_types.Generic with type 'a t := 'a t and type 'a elt := 'a and module On := On and module On_monad := On_monad and module With_errors := With_errors
include Travesty.Generic_types.Generic with type 'a t := 'a t with type 'a elt := 'a

We can do generic container operations.

include Base.Container.Generic with type 'a t := 'a t and type 'a elt := 'a

We can do non-applicative mapping operations.

include Travesty.Mappable_types.Generic with type 'a t := 'a t and type 'a elt := 'a

Generic refers to the container type as 'a t, and the element type as 'a elt; substitute t/elt (arity-0) or 'a t/'a (arity-1) accordingly below.

include Travesty.Generic_types.Generic with type 'a t := 'a t with type 'a elt := 'a
val fold_map : 'a t -> f:('acc -> 'a -> 'acc * 'b) -> init:'acc -> 'acc * 'b t

fold_map c ~f ~init folds f over every t in c, threading through an accumulator with initial value init.

val mapi : f:(Base.int -> 'a -> 'b) -> 'a t -> 'b t

mapi ~f t maps f across t, passing in an increasing position counter.

include Travesty.Mappable_types.S1_container with type 'a t := 'a t
include Travesty.Mappable_types.S1 with type 'a t := 'a t
include Travesty.Mappable_types.Generic with type 'a t := 'a t and type 'a elt := 'a

Generic refers to the container type as 'a t, and the element type as 'a elt; substitute t/elt (arity-0) or 'a t/'a (arity-1) accordingly below.

include Travesty.Generic_types.Generic with type 'a t := 'a t with type 'a elt := 'a
val map : 'a t -> f:('a -> 'b) -> 'b t

map c ~f maps f over every t in c.

include Base.Container.S1 with type 'a t := 'a t
val mem : 'a t -> 'a -> equal:('a -> 'a -> bool) -> bool
val length : 'a t -> int
val is_empty : 'a t -> bool
val iter : 'a t -> f:('a -> unit) -> unit
val fold : 'a t -> init:'accum -> f:('accum -> 'a -> 'accum) -> 'accum
val fold_result : 'a t -> init:'accum -> f:('accum -> 'a -> ('accum, 'e) Base__.Result.t) -> ('accum, 'e) Base__.Result.t
val fold_until : 'a t -> init:'accum -> f:('accum -> 'a -> ('accum, 'final) Base__Container_intf.Continue_or_stop.t) -> finish:('accum -> 'final) -> 'final
val exists : 'a t -> f:('a -> bool) -> bool
val for_all : 'a t -> f:('a -> bool) -> bool
val count : 'a t -> f:('a -> bool) -> int
val sum : (module Base__Container_intf.Summable with type t = 'sum) -> 'a t -> f:('a -> 'sum) -> 'sum
val find : 'a t -> f:('a -> bool) -> 'a option
val find_map : 'a t -> f:('a -> 'b option) -> 'b option
val to_list : 'a t -> 'a list
val to_array : 'a t -> 'a array
val min_elt : 'a t -> compare:('a -> 'a -> int) -> 'a option
val max_elt : 'a t -> compare:('a -> 'a -> int) -> 'a option
include Travesty.Mappable_types.Extensions1 with type 'a t := 'a t

Extensions1 includes the container extensions from Container_exts, as they work with any arity-1 container.

include Travesty.Container_exts_types.S1 with type 'a t := 'a t
include Travesty.Container_exts_types.Generic with type 'a t := 'a t and type 'a elt := 'a

Generic refers to the container type as 'a t, and the element type as 'a elt; substitute t/elt (arity-0) or 'a t/'a (arity-1) accordingly below.

include Travesty.Generic_types.Generic with type 'a t := 'a t with type 'a elt := 'a

Testing for a specific number of elements

The following functions help in checking whether a container has a particular, commonly-required number of elements (zero or one, one, two, and so on).

val at_most_one : 'a t -> 'a Base.option Base.Or_error.t

at_most_one xs returns Ok None if xs is empty; Ok Some(x) if it contains only x; and an error otherwise.

Examples (using an extended version of List):

(* ok None *)
List.at_most_one []
(* ok (Some 1) *)
List.at_most_one [1]
(* error -- too many *)
List.at_most_one [1; 2]
val one : 'a t -> 'a Base.Or_error.t

one xs returns Ok x if xs contains only x, and an error otherwise.

Examples (using an extended version of List):

(* error -- not enough *)
List.one []
(* ok 1 *)
List.one [1]
(* error -- too many *)
List.one [1; 2]
val two : 'a t -> ('a * 'a) Base.Or_error.t

two xs returns Ok (x, y) if xs is a list containing only x and y in that order, and an error otherwise.

Examples (using an extended version of List):

(* error -- not enough *)
List.two []
(* error -- not enough *)
List.two [1]
(* ok (1, 2) *)
List.two [1; 2]
(* error -- too many *)
List.two [1; 2; 3]

Miscellaneous extensions

val max_measure : measure:('a -> Base.int) -> ?default:Base.int -> 'a t -> Base.int

max_measure ~measure ~default xs measures each item in xs according to measure, and returns the highest measure reported. If xs is empty, return default if given, and 0 otherwise.

Predicate extensions are available on all arity-1 containers, provided that we fix the element type parameter to 'a -> bool.

include Travesty.Container_exts_types.Generic_predicate with type 'a t := ('a -> Base.bool) t and type 'a item := 'a
val any : 'a -> predicates:('a -> Base.bool) t -> Base.bool

any x ~predicates tests x against predicates until one returns true, in which case it returns true; or all return false, in which case it returns false.

val all : 'a -> predicates:('a -> Base.bool) t -> Base.bool

any x ~predicates tests x against predicates until one returns false, in which case it returns false; or all return true, in which case it returns true.

val none : 'a -> predicates:('a -> Base.bool) t -> Base.bool

none x ~predicates is the same as any x with all predicates in predicates negated. It tests x against predicates until one returns true, in which case it returns false; or all return false, in which case it returns true.

val right_pad : padding:'a -> 'a Base.list t -> 'a Base.list t

right_pad ~padding xs pads every list in xs with padding, ensuring all lists have equal length.

Example:

right_pad ~padding:6
  [ [0; 8; 0; 0] (* [ [ 0; 8; 0; 0; 6 ] *)
  ; [9; 9; 9] (* ; [ 9; 9; 9; 6; 6 ] *)
  ; [8; 8; 1; 9; 9] (* ; [ 8; 8; 1; 9; 9 ] *)
  ; [9; 1; 1; 9] (* ; [ 9; 1; 1; 9; 6 ] *)
  ; [7; 2; 5] (* ; [ 7; 2; 5; 6; 6 ] *)
  ; [3] (* ; [ 3; 6; 6; 6; 6 ] *) ]

(* ] *)

Options are also filter-mappable; filter-mapping effectively behaves as monadic bind.

include Travesty.Filter_mappable_types.S1 with type 'a t := 'a t
include Travesty.Filter_mappable_types.Generic with type 'a t := 'a t and type 'a elt := 'a

Generic strictly extends Generic_basic.

include Travesty.Filter_mappable_types.Generic_basic with type 'a t := 'a t with type 'a elt := 'a

Generic_basic refers to the container type as 'a t, and the element type as 'a elt; substitute t/elt (arity-0) or 'a t/'a (arity-1) accordingly below.

include Travesty.Generic_types.Generic with type 'a t := 'a t with type 'a elt := 'a
val filter_map : 'a t -> f:('a -> 'b Base.option) -> 'b t

filter_map c ~f maps f over every t in c, discarding any items for which f returns None.

val filter : 'a t -> f:('a -> Base.bool) -> 'a t

filter c ~f checks f over every t in c, discarding any items for which f returns false.

val exclude : 'a t -> f:('a -> Base.bool) -> 'a t

exclude c ~f checks f over every t in c, discarding any items for which f returns true.

We can also derive Mappable interfaces from filter-mappable ones, but leave that to a separate functor.

Finally, options are a monad, and take the various monad extensions.

include Travesty.Monad_exts_types.S with type 'a t := 'a t

S subsumes S_let.

include Travesty.Monad_exts_types.S_let with type 'a t := 'a t
val let+ : 'a t -> ('a -> 'b) -> 'b t

let+ is map.

val let* : 'a t -> ('a -> 'b t) -> 'b t

let* is bind.

Haskell-style operators

val then_m : _ t -> 'a t -> 'a t

then_m x y sequentially composes the actions x and y as with >>=, but, rather than using the returned value of x, it instead just returns y.

val (>>) : _ t -> 'a t -> 'a t

x >> y is then_m x y.

val compose_m : ('a -> 'b t) -> ('b -> 'c t) -> 'a -> 'c t

compose_m f g is the Kleisli composition of f and g.

val (>=>) : ('a -> 'b t) -> ('b -> 'c t) -> 'a -> 'c t

x >=> y is compose_m x y.

Guarded monadic computations

val map_when_m : ?otherwise:('a -> 'a t) -> bool -> 'a -> f:('a -> 'a t) -> 'a t

map_when_m ?otherwise condition ~f a is f a when condition is true, and otherwise a (by default, return) otherwise.

val when_m : ?otherwise:(unit -> unit t) -> bool -> f:(unit -> unit t) -> unit t

when_m ?otherwise condition ~f is f () when condition is true, and otherwise () (by default, return) otherwise.

val map_unless_m : ?otherwise:('a -> 'a t) -> bool -> 'a -> f:('a -> 'a t) -> 'a t

map_unless_m ?otherwise condition ~f a is f a when condition is false, and otherwise a (by default, return) otherwise.

val unless_m : ?otherwise:(unit -> unit t) -> bool -> f:(unit -> unit t) -> unit t

unless_m ?otherwise condition ~f is f () when condition is false, and otherwise () (by default, return) otherwise.

Executing monadic effects in the middle of pipelines

val tee_m : 'a -> f:('a -> unit t) -> 'a t

tee_m val ~f executes f val for its monadic action, then returns val.

Example (using an extended Or_error):

let fail_if_negative x =
  On_error.when_m (Int.is_negative x) ~f:(fun () ->
      Or_error.error_string "value is negative!" )
in
Or_error.(42 |> tee_m ~f:fail_if_negative >>| fun x -> x * x)

(* Ok (1764) *)
val tee : 'a -> f:('a -> unit) -> 'a t

tee val ~f behaves as tee_m, but takes a non-monadic f.

Example (using an extended Or_error):

let print_if_negative x =
  if Int.negative x then Stdio.print_string "value is negative!"
in
Or_error.(
  try_get_value () >>= tee ~f:print_if_negative >>= try_use_value ())

Applying defaults non-eagerly

val value_f : 'a option -> default_f:(unit -> 'a) -> 'a

value_f opt ~default_f behaves like value opt ~default:(default_f ()), but only evaluates the thunk default_f if value is None.

val value_l : 'a option -> default_l:'a Stdlib.Lazy.t -> 'a

value_f opt ~default_l behaves like value opt ~default:(Lazy.force default_l), but only forces default_l if value is None.

Miscellaneous extension functions

val first_some_of_thunks : (unit -> 'a option) list -> 'a option

first_some_of_thunks thunks evaluates each thunk in thunks until none remain (in which case, it returns None, or one of the thunks returns Some x (in which case, it returns Some x.

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