package travesty

You can search for identifiers within the package.

in-package search v0.2.0

Traversable containers, monad extensions, and more

Install

Dune Dependency

mattwindsor91.github.io Readme Changelog Edit opam file Versions (8)

Authors

M

Matt Windsor <mattwindsor91@gmail.com>

Maintainers

M

Matt Windsor <mattwindsor91@gmail.com>

Sources

travesty-0.8.0.tbz

sha256=216c920c872cef2d52fa58e3c49826766a2cf6f2233e64937f18c46c0c5c5388

sha512=3b4f76794666aa3fb16c3639479790df3478a79e6f582b3e66b144e57df26a76580499961dd374f4fb6f3bd2dd7506e2725ed1242bada9deb14eb1916cacd18f

doc/travesty.base_exts/Travesty_base_exts/Option/index.html

Module `Travesty_base_exts.Option`Source

Option extensions.

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

Sourcetype '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

Source

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.

Source

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.

Source

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, 'phantom) 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, 'phantom) t := 'a t
  with type 'a elt := 'a

We can do generic container operations.

include Base.Container.Generic
  with type ('a, 'phantom) t := 'a t
   and type 'a elt := 'a

We can do non-applicative mapping operations.

include Travesty.Mappable_types.Generic
  with type ('a, 'phantom) 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, 'phantom) t := 'a t
  with type 'a elt := 'a

Sourceval 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.

Sourceval 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, 'phantom) 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, 'phantom) t := 'a t
  with type 'a elt := 'a

Sourceval 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

Sourceval mem : 'a t -> 'a -> equal:('a -> 'a -> bool) -> bool

Checks whether the provided element is there, using equal.

Sourceval length : 'a t -> int

Sourceval is_empty : 'a t -> bool

Sourceval iter : 'a t -> f:('a -> unit) -> unit

Sourceval fold : 'a t -> init:'acc -> f:('acc -> 'a -> 'acc) -> 'acc

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

Source

val fold_result : 
  'a t ->
  init:'acc ->
  f:('acc -> 'a -> ('acc, 'e) Base.Result.t) ->
  ('acc, '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.

Source

val fold_until : 
  'a t ->
  init:'acc ->
  f:('acc -> 'a -> ('acc, 'final) Base.Container.Continue_or_stop.t) ->
  finish:('acc -> '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

Sourceval 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.

Sourceval 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.

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

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

Source

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.

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

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

Sourceval 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.

Sourceval to_list : 'a t -> 'a list

Sourceval to_array : 'a t -> 'a array

Sourceval 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.

Sourceval 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, 'phantom) 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, 'phantom) 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).

Sourceval 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]

Sourceval 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]

Sourceval 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

Source

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, 'phantom) t := ('a -> Base.bool) t
   and type 'a item := 'a

Sourceval 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.

Sourceval 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.

Sourceval 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.

Sourceval 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, 'phantom) t := 'a t
   and type 'a elt := 'a

Generic strictly extends Generic_basic.

include Travesty.Filter_mappable_types.Generic_basic
  with type ('a, 'phantom) 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, 'phantom) t := 'a t
  with type 'a elt := 'a

Sourceval 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.

Sourceval 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.

Sourceval 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

Sourceval (let+) : 'a t -> ('a -> 'b) -> 'b t

let+ is map.

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

let* is bind.

Haskell-style operators

Sourceval 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.

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

x >> y is then_m x y.

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

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

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

x >=> y is compose_m x y.

Guarded monadic computations

Source

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.

Source

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.

Source

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.

Source

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

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

Sourceval 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

Sourceval 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.

Sourceval value_l : 'a option -> default_l:'a 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

Sourceval 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.

On This Page

Travesty instances
1. Applying defaults non-eagerly
Miscellaneous extension functions

package travesty

Install

Dune Dependency

Authors

Maintainers

Sources

doc/travesty.base_exts/Travesty_base_exts/Option/index.html

Module Travesty_base_exts.OptionSource

Travesty instances

Testing for a specific number of elements

Miscellaneous extensions

Haskell-style operators

Guarded monadic computations

Executing monadic effects in the middle of pipelines

Applying defaults non-eagerly

Miscellaneous extension functions

Module `Travesty_base_exts.Option`Source