package containers

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

LINQ-like operations on collections

The purpose is to provide powerful combinators to express iteration, transformation and combination of collections of items. This module depends on several other modules, including CCList and CCSequence.

Functions and operations are assumed to be referentially transparent, i.e. they should not rely on external side effects, they should not rely on the order of execution.

  • deprecated

    use OLinq

    CCLinq.(
  of_list [1;2;3]
  |> flat_map (fun x -> Sequence.(x -- (x+10)))
  |> sort ()
  |> count ()
  |> flat_map PMap.to_seq
  |> List.run
);;
- : (int * int) list = [(13, 1); (12, 2); (11, 3); (10, 3); (9, 3);
    (8, 3); (7, 3); (6, 3); (5, 3); (4, 3); (3, 3); (2, 2); (1, 1)]


CCLinq.(
  IO.slurp_file "/tmp/foo"
  |> IO.lines
  |> sort ()
  |> IO.to_file_lines "/tmp/bar"
);;
- :  `Ok ()

    DEPRECATED, use "OLinq" (standalone library) instead

    status: deprecated

type 'a sequence = ('a -> unit) -> unit
type 'a equal = 'a -> 'a -> bool
type 'a ord = 'a -> 'a -> int
type 'a hash = 'a -> int
type 'a with_err = [
  1. | `Ok of 'a
  2. | `Error of string
]
module PMap : sig ... end

Query operators

type 'a t

Type of a query that returns zero, one or more values of type 'a

Initial values
val empty : 'a t

Empty collection

val start : 'a -> 'a t

Start with a single value

  • deprecated

    since 0.13, use return instead

val return : 'a -> 'a t

Return one value

val of_list : 'a list -> 'a t

Query that just returns the elements of the list

val of_array : 'a array -> 'a t
val of_array_i : 'a array -> (int * 'a) t
val range : int -> int -> int t

range i j goes from i up to j included

val (--) : int -> int -> int t

Synonym to range

val of_hashtbl : ('a, 'b) Hashtbl.t -> ('a * 'b) t
val of_seq : 'a sequence -> 'a t

Query that returns the elements of the given sequence.

val of_queue : 'a Queue.t -> 'a t
val of_stack : 'a Stack.t -> 'a t
val of_string : string -> char t

Traverse the characters of the string

Execution
val run : ?limit:int -> 'a t -> 'a sequence

Execute the query, possibly returning an error if things go wrong

  • parameter limit

    max number of values to return

val run1 : 'a t -> 'a

Run the query and return the first value

  • raises Not_found

    if the query succeeds with 0 element

val run_no_optim : ?limit:int -> 'a t -> 'a sequence

Run without any optimization

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

Map each value

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

Infix synonym of map

val filter : ('a -> bool) -> 'a t -> 'a t

Filter out values that do not satisfy predicate

val size : _ t -> int t

size t returns one value, the number of items returned by t

val choose : 'a t -> 'a t

Choose one element (if any, otherwise empty) in the collection. This is like a "cut" in prolog.

val filter_map : ('a -> 'b option) -> 'a t -> 'b t

Filter and map elements at once

val flat_map : ('a -> 'b sequence) -> 'a t -> 'b t

Same as flat_map but using sequences

val flat_map_l : ('a -> 'b list) -> 'a t -> 'b t

map each element to a collection and flatten the result

val flatten : 'a list t -> 'a t
val flatten_seq : 'a sequence t -> 'a t
val take : int -> 'a t -> 'a t

Take at most n elements

val take_while : ('a -> bool) -> 'a t -> 'a t

Take elements while they satisfy a predicate

val sort : ?cmp:'a ord -> unit -> 'a t -> 'a t

Sort items by the given comparison function

val distinct : ?cmp:'a ord -> unit -> 'a t -> 'a t

Remove duplicate elements from the input collection. All elements in the result are distinct.

Aggregation
val group_by : ?cmp:'b ord -> ?eq:'b equal -> ?hash:'b hash -> ('a -> 'b) -> 'a t -> ('b, 'a list) PMap.t t

group_by f takes a collection c as input, and returns a multimap m such that for each x in c, x occurs in m under the key f x. In other words, f is used to obtain a key from x, and x is added to the multimap using this key.

val group_by' : ?cmp:'b ord -> ?eq:'b equal -> ?hash:'b hash -> ('a -> 'b) -> 'a t -> ('b * 'a list) t
val count : ?cmp:'a ord -> ?eq:'a equal -> ?hash:'a hash -> unit -> 'a t -> ('a, int) PMap.t t

count c returns a map from elements of c to the number of time those elements occur.

val count' : ?cmp:'a ord -> unit -> 'a t -> ('a * int) t
val fold : ('b -> 'a -> 'b) -> 'b -> 'a t -> 'b t

Fold over the collection

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

reduce start mix stop q uses start on the first element of q, and combine the result with following elements using mix. The final value is transformed using stop.

val is_empty : 'a t -> bool t
val sum : int t -> int t
val contains : ?eq:'a equal -> 'a -> 'a t -> bool t
val average : int t -> int t
val max : int t -> int t
val min : int t -> int t
val for_all : ('a -> bool) -> 'a t -> bool t
val exists : ('a -> bool) -> 'a t -> bool t
val find : ('a -> bool) -> 'a t -> 'a option t
val find_map : ('a -> 'b option) -> 'a t -> 'b option t
Binary Operators
val join : ?cmp:'key ord -> ?eq:'key equal -> ?hash:'key hash -> ('a -> 'key) -> ('b -> 'key) -> merge:('key -> 'a -> 'b -> 'c option) -> 'a t -> 'b t -> 'c t

join key1 key2 ~merge is a binary operation that takes two collections a and b, projects their elements resp. with key1 and key2, and combine values (x,y) from (a,b) with the same key using merge. If merge returns None, the combination of values is discarded.

val group_join : ?cmp:'a ord -> ?eq:'a equal -> ?hash:'a hash -> ('b -> 'a) -> 'a t -> 'b t -> ('a, 'b list) PMap.t t

group_join key2 associates to every element x of the first collection, all the elements y of the second collection such that eq x (key y)

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

Cartesian product

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

Append two collections together

val inter : ?cmp:'a ord -> ?eq:'a equal -> ?hash:'a hash -> unit -> 'a t -> 'a t -> 'a t

Intersection of two collections. Each element will occur at most once in the result

val union : ?cmp:'a ord -> ?eq:'a equal -> ?hash:'a hash -> unit -> 'a t -> 'a t -> 'a t

Union of two collections. Each element will occur at most once in the result

val diff : ?cmp:'a ord -> ?eq:'a equal -> ?hash:'a hash -> unit -> 'a t -> 'a t -> 'a t

Set difference

Tuple and Options

Specialized projection operators

val fst : ('a * 'b) t -> 'a t
val snd : ('a * 'b) t -> 'b t
val map1 : ('a -> 'b) -> ('a * 'c) t -> ('b * 'c) t
val map2 : ('a -> 'b) -> ('c * 'a) t -> ('c * 'b) t
val flatten_opt : 'a option t -> 'a t

Flatten the collection by removing options

Applicative
val pure : 'a -> 'a t

Synonym to return

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

Apply each function to each value

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

Infix synonym to app

Monad

Careful, those operators do not allow any optimization before running the query, they might therefore be pretty slow.

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

Use the result of a query to build another query and immediately run it.

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

Infix version of bind

Misc
val lazy_ : 'a lazy_t t -> 'a t
val opt_unwrap : 'a option t -> 'a t
val reflect : 'a t -> 'a sequence t

reflect q evaluates all values in q and returns a sequence of all those values. Also blocks optimizations

Infix
module Infix : sig ... end
Adapters
val to_seq : 'a t -> 'a sequence t

Build a (re-usable) sequence of elements, which can then be converted into other structures

val to_hashtbl : ('a * 'b) t -> ('a, 'b) Hashtbl.t t

Build a hashtable from the collection

val to_queue : 'a t -> 'a Queue.t t
val to_stack : 'a t -> 'a Stack.t t
module List : sig ... end
module Array : sig ... end
module AdaptSet (S : Set.S) : sig ... end
module AdaptMap (M : Map.S) : sig ... end
module IO : sig ... end
OCaml

Innovation. Community. Security.

GitHub Discord Twitter Peertube RSS
About
Changelog Releases Industrial Users Academic Users Why OCaml
Ecosystem
Packages Community Events Blog 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