travesty

Traversable containers, monad extensions, and more
IN THIS PACKAGE
type 'a t = 'a list

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

Travesty instances

module With_errors : sig ... end

Extended With_errors, adding functions specific to working with lists in an error-prone context.

Lists are traversable containers, but have an extended With_errors submodule.

include Travesty.Traversable_types.S1 with type 'a t := 'a t and module With_errors := With_errors
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.

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

Checks whether the provided element is there, using equal.

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

fold t ~init ~f returns f (... f (f (f init e1) e2) e3 ...) en, where e1..en are the elements of t

val fold_result : 'a t -> init:'accum -> f:( 'accum -> 'a -> ( 'accum, 'e ) Base.Result.t ) -> ( 'accum, 'e ) Base.Result.t

fold_result t ~init ~f is a short-circuiting version of fold that runs in the Result monad. If f returns an Error _, that value is returned without any additional invocations of f.

val fold_until : 'a t -> init:'accum -> f:( 'accum -> 'a -> ( 'accum, 'final ) Base.Container.Continue_or_stop.t ) -> finish:( 'accum -> 'final ) -> 'final

fold_until t ~init ~f ~finish is a short-circuiting version of fold. If f returns Stop _ the computation ceases and results in that value. If f returns Continue _, the fold will proceed. If f never returns Stop _, the final result is computed by finish.

Example:

type maybe_negative =
  | Found_negative of int
  | All_nonnegative of { sum : int }

(** [first_neg_or_sum list] returns the first negative number in [list], if any,
    otherwise returns the sum of the list. *)
let first_neg_or_sum =
  List.fold_until ~init:0
    ~f:(fun sum x ->
      if x < 0
      then Stop (Found_negative x)
      else Continue (sum + x))
    ~finish:(fun sum -> All_nonnegative { sum })
;;

let x = first_neg_or_sum [1; 2; 3; 4; 5]
val x : maybe_negative = All_nonnegative {sum = 15}

let y = first_neg_or_sum [1; 2; -3; 4; 5]
val y : maybe_negative = Found_negative -3
val exists : 'a t -> f:( 'a -> bool ) -> bool

Returns true if and only if there exists an element for which the provided function evaluates to true. This is a short-circuiting operation.

val for_all : 'a t -> f:( 'a -> bool ) -> bool

Returns true if and only if the provided function evaluates to true for all elements. This is a short-circuiting operation.

val count : 'a t -> f:( 'a -> bool ) -> int

Returns the number of elements for which the provided function evaluates to true.

val sum : (module Base.Container.Summable with type t = 'sum) -> 'a t -> f:( 'a -> 'sum ) -> 'sum

Returns the sum of f i for all i in the container.

val find : 'a t -> f:( 'a -> bool ) -> 'a option

Returns as an option the first element for which f evaluates to true.

val find_map : 'a t -> f:( 'a -> 'b option ) -> 'b option

Returns the first evaluation of f that returns Some, and returns None if there is no such element.

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

Returns a minimum (resp maximum) element from the collection using the provided compare function, or None if the collection is empty. In case of a tie, the first element encountered while traversing the collection is returned. The implementation uses fold so it has the same complexity as fold.

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 ] *) ]

(* ] *)

We can also filter-map over them.

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.

Utility functions for modifying lists

val replace : 'a list -> int -> f:( 'a -> 'a option ) -> 'a list Or_error.t

replace xs at ~f tries to replace the value at index at in xs using the function f. f may return None, in which case the item is removed.

Examples:

replace [1; 2; 3] 1
  ~f:(fun _ -> None) (* Ok [1; 3] *)
  replace [1; 2; 3] 2
  ~f:(fun x -> Some (x + 1))

(* Ok [1; 2; 4] *)
val insert : 'a list -> int -> 'a -> 'a list Or_error.t

insert xs at value tries to insert value at index at in xs.

Miscellaneous extension functions

val prefixes : 'a list -> 'a list list

prefixes xs returns all non-empty prefixes of xs.

Examples:

prefixes [] (* [] *) prefixes [1; 2; 3]

(* [ [ 1 ]; [ 1; 2 ]; [ 1; 2; 3 ] *)