non_empty_list 0.1 · OCaml Package

A non-empty list is defined as a immutable (singly) linked list containing at least 1 element. Identical in terms of complexity to List. The API is inspired by Janestreet's Base.List (but is not identical).

type 'a t =

| :: of 'a * 'a Base.list

The non-empty list type. The use of the ( :: ) infix constructor allows the usage of the built-in list syntactic sugar provided by OCaml.

For example, a singleton is given by [1] . A list containing 2 elements is given by [1; 2] .

val equal : 
  ('a -> 'a -> Ppx_deriving_runtime.bool) ->
  'a t ->
  'a t ->
  Ppx_deriving_runtime.bool

val compare : 
  ('a -> 'a -> Ppx_deriving_runtime.int) ->
  'a t ->
  'a t ->
  Ppx_deriving_runtime.int

val pp : 
  (Ppx_deriving_runtime.Format.formatter -> 'a -> Ppx_deriving_runtime.unit) ->
  Ppx_deriving_runtime.Format.formatter ->
  'a t ->
  Ppx_deriving_runtime.unit

val show : 
  (Ppx_deriving_runtime.Format.formatter -> 'a -> Ppx_deriving_runtime.unit) ->
  'a t ->
  Ppx_deriving_runtime.string

type 'a non_empty_list = 'a t

include Base.Monad.S with type 'a t := 'a t

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

t >>= f returns a computation that sequences the computations represented by two monad elements. The resulting computation first does t to yield a value v, and then runs the computation returned by f v.

val (>>|) : 'a t -> ('a -> 'b) -> 'b t

t >>| f is t >>= (fun a -> return (f a)).

module Monad_infix : sig ... end

val bind : 'a t -> f:('a -> 'b t) -> 'b t

bind t ~f = t >>= f

val return : 'a -> 'a t

return v returns the (trivial) computation that returns v.

val join : 'a t t -> 'a t

join t is t >>= (fun t' -> t').

val ignore_m : 'a t -> unit t

ignore_m t is map t ~f:(fun _ -> ()). ignore_m used to be called ignore, but we decided that was a bad name, because it shadowed the widely used Stdlib.ignore. Some monads still do let ignore = ignore_m for historical reasons.

val all : 'a t list -> 'a list t

val all_unit : unit t list -> unit t

Like all, but ensures that every monadic value in the list produces a unit value, all of which are discarded rather than being collected into a list.

module Let_syntax : sig ... end

These are convenient to have in scope when programming with a monad:

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

init n ~f returns the non-empty list [(f 0); (f 1); ...; (f (n-1))].

val of_list : 'a Base.list -> 'a t Base.option

of_list creates a non-empty list from a standard list, returning None if the empty list is provided.

val of_list_exn : 'a Base.list -> 'a t

val of_array : 'a Base.array -> 'a t Base.option

of_array creates a non-empty list from an array. of_array arr is equivalent to of_list (List.to_array arr).

val of_array_exn : 'a Base.array -> 'a t

Simialar to Non_empty_list.of_array, but raises an Invalid_argument if an empty array is provided.

val to_list : 'a t -> 'a Base.list

to_list creates a standard list from a non-empty list.

val to_array : 'a t -> 'a Base.array

to_array creates an array from a non-empty list. to_array t is equivalent to Array.of_list (to_list t).

val length : 'a t -> Base.int

length t returns the number of elements in t. Note that length t >= 1 for all t.

val is_singleton : 'a t -> Base.bool

is_singleton t returns true if t is a singleton (a non-empty list containing a single element).

val cons : 'a -> 'a t -> 'a t

cons x t returns the non-empty list [x; ...t].

val append : 'a t -> 'a t -> 'a t

append t1 t2 returns a list t consisting of all elements of t1 and t2 (order preserved).

val rev_append : 'a t -> 'a t -> 'a t

rev_append t1 t2 reverses t1 and then appends it to t2. Equivalent to append (rev t1) t2, however, is more efficient.

val concat : 'a t t -> 'a t

Concatenates a non-empty list of non-empty lists.

val hd : 'a t -> 'a

hd returns the first element of the given non-empty list t. Note that no exception can occur.

val tl : 'a t -> 'a Base.list

tl returns the tail of the non-empty list. Note that the list type is used for the returned value, since removing an element from a non-empty list may yield an empty list (e.g. a singleton).

val last : 'a t -> 'a

last returns the final element of the non-empty list.

val nth : 'a t -> Base.int -> 'a Base.option

Returns the n-th element of the list. The head of the list has position 0. None is returned if the list t is too short or n is negative.

val nth_exn : 'a t -> Base.int -> 'a

Equivalent to nth. However, an Invalid_argument exception is raised if the list t is too short or n is negative.

val mem : 'a t -> 'a -> equal:('a -> 'a -> Base.bool) -> Base.bool

Checks whether the provided element x is a member of the non-empty list t, using equal.

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

find t ~f returns the first element of the non-empty list t that satisfied f.

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

Similar to Non_empty_list.find, but raises a Not_found if there is no such element that satisfies f.

val findi : 
  'a t ->
  f:(Base.int -> 'a -> Base.bool) ->
  (Base.int * 'a) Base.option

Similar to find, however, the index is passed as an argument to f as well.

val findi_exn : 'a t -> f:(Base.int -> 'a -> Base.bool) -> Base.int * 'a

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

find_map t ~f returns Some x, the first element x for which f x retunrs Some x. Returns None if there is no such element.

val find_map_exn : 'a t -> f:('a -> 'b Base.option) -> 'b

val find_mapi : 
  'a t ->
  f:(Base.int -> 'a -> 'b Base.option) ->
  (Base.int * 'b) Base.option

Similar to Non_empty_list.find_map, however, the index is passed as an argument to f as well.

val find_mapi_exn : 
  'a t ->
  f:(Base.int -> 'a -> 'b Base.option) ->
  Base.int * 'b

module Or_unequal_lengths : sig ... end

Or_unequal_lengths is used for functions that take multiple non-empty lists (denoted t1, etc). Defines the dependent type: {'a : length t1 = length t2 = ... length tn}. Extends the Base.List.Or_unequal_lengths implementation with the Monad methods, improves readabily and reuseability of other library functions.

val rev : 'a t -> 'a t

Reverses the non-empty list.

val rev_map : 'a t -> f:('a -> 'b) -> 'b t

rev_map t ~f is equivalent to rev (map t ~f). However, it is more efficient.

val rev_map2 : 'a t -> 'b t -> f:('a -> 'b -> 'c) -> 'c t Or_unequal_lengths.t

rev_map2 t1 t2 ~f is equivalent to map2 t1 t2 ~f >>| rev. Returns Unequal_lengths if length t1 <> length t2.

val rev_map2_exn : 'a t -> 'b t -> f:('a -> 'b -> 'c) -> 'c t

Similar to rev_map2, however, raises Invalid_argument if length t1 <> length t2.

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

for_all [x1; ...; xn] ~f returns true iff f xi is true for all 1 <= i <= n. This is a short-circuiting operation, evaluting f xi in a left-to-right order.

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

Similar to Non_empty_list.for_all, however, the index is passed as an argument to f as well.

val for_all2 : 
  'a t ->
  'b t ->
  f:('a -> 'b -> Base.bool) ->
  Base.bool Or_unequal_lengths.t

Similar to Non_empty_list.for_all, but defines a 2 non-empty list quanitifer

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

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

for_all [x1; ...; xn] ~f returns true iff there exists 1 <= i <= n such that f xi is true. This is a short-circuiting operation, evaluting f xi in a left-to-right order.

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

Similar to Non_empty_list.exists, however, the index is passed as an argument to f as well.

val exists2 : 
  'a t ->
  'b t ->
  f:('a -> 'b -> Base.bool) ->
  Base.bool Or_unequal_lengths.t

Similar to Non_empty_list.exists, but defines a 2 non-empty list quanitifer.

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

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

filter t ~f returns a *list* of elements of t that satisfy the predicate f. The order is preserved and evaluation is left-to-right.

val filter_map : 'a t -> f:('a -> 'b Base.option) -> 'b Base.list

val filteri : 'a t -> f:(Base.int -> 'a -> Base.bool) -> 'a Base.list

val filter_mapi : 'a t -> f:(Base.int -> 'a -> 'b Base.option) -> 'b Base.list

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

rev_filter t ~f is equivalent to List.rev (filter t ~f), however, is more efficient.

val rev_filter_map : 'a t -> f:('a -> 'b Base.option) -> 'b Base.list

val rev_filter_mapi : 
  'a t ->
  f:(Base.int -> 'a -> 'b Base.option) ->
  'b Base.list

val map : 'a t -> f:('a -> 'b) -> 'b t

map ~f [x1; ...; xn] (n >= 1) applies f to x1, ..., xn (left-to-right order), yielding the resultant non-empty list [f x1; ..., f xn].

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

Similar to Non_empty_list.map, however, the index is passed as an argument to f as well.

val map2 : 'a t -> 'b t -> f:('a -> 'b -> 'c) -> 'c t Or_unequal_lengths.t

Similar to Non_empty_list.map, but defined for 2 non-empty lists.

val map2_exn : 'a t -> 'b t -> f:('a -> 'b -> 'c) -> 'c t

val concat_map : 'a t -> f:('a -> 'b t) -> 'b t

concat_map t ~f is equivalent to concat (map t ~f).

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

val iter : 'a t -> f:('a -> Base.unit) -> Base.unit

iter [x1; ...; xn] ~f is equivalent to f x1; ...; f xn

val iteri : 'a t -> f:(Base.int -> 'a -> Base.unit) -> Base.unit

val iter2 : 
  'a t ->
  'b t ->
  f:('a -> 'b -> Base.unit) ->
  Base.unit Or_unequal_lengths.t

iter2 [x1; ...; xn] [y1; ...; ym] ~f is equvalent to f x1 y2; ...; f xn yn. Returns Unequal_lengths if m <> n.

val iter2_exn : 'a t -> 'b t -> f:('a -> 'b -> Base.unit) -> Base.unit

val fold_left : 'a t -> init:'b -> f:('b -> 'a -> 'b) -> 'b

fold_left [x1; ...; xn] ~init ~f returns f (... f (f init x1) x2 ...) xn. fold_left t ~init ~f is equivalent to List.fold_left (to_list t) ~init ~f

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

Similar to Non_empty_list.fold_left, however, the index is passed as an argument to f as well.

val fold_right : 'a t -> init:'b -> f:('a -> 'b -> 'b) -> 'b

fold_right [x1; ...; xn] ~init ~f returns f x1 (... f x(n-1) (f init xn) ...). fold_right t ~init ~f is equivalent to List.fold_right (to_list t) ~init ~f

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

Similar to Non_empty_list.fold_right, however, the index is passed as an argument to f as well.

val reduce : 'a t -> f:('a -> 'a -> 'a) -> 'a

reduce [x1; ...; xn] ~f returns f (... f (f x1 x2) x3 ...) xn. Note that no exception cqan occur.

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

count t ~f returns the number of elements of t that satisfy f.

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

Similar to Non_empty_list.count, however, the index is passed as an argument to f as well.

val zip : 'a t -> 'b t -> ('a * 'b) t Or_unequal_lengths.t

zip [x1; ...; xn] [y1; ...; ym] returns [(x1, y1); ...; (xn, yn)]. Returns Unequal_lengths if m <> n

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

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

unzip [(x1, y1); ...; (xn, yn)] returns ([x1; ...; xn], [y1; ...; yn]).

val partition_map : 
  'a t ->
  f:('a -> ('b, 'c) Base.Either.t) ->
  'b Base.list * 'c Base.list

val partition_tf : 'a t -> f:('a -> Base.bool) -> 'a Base.list * 'a Base.list

val split_n : 'a t -> Base.int -> 'a Base.list * 'a Base.list

package non_empty_list