mirror of
https://github.com/c-cube/ocaml-containers.git
synced 2025-12-07 11:45:31 -05:00
425 lines
12 KiB
OCaml
425 lines
12 KiB
OCaml
|
|
(*
|
|
copyright (c) 2013-2014, simon cruanes
|
|
all rights reserved.
|
|
|
|
redistribution and use in source and binary forms, with or without
|
|
modification, are permitted provided that the following conditions are met:
|
|
|
|
redistributions of source code must retain the above copyright notice, this
|
|
list of conditions and the following disclaimer. redistributions in binary
|
|
form must reproduce the above copyright notice, this list of conditions and the
|
|
following disclaimer in the documentation and/or other materials provided with
|
|
the distribution.
|
|
|
|
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
|
|
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
|
|
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
|
|
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
|
|
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
|
|
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
|
|
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
|
|
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
|
|
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
|
*)
|
|
|
|
(** {1 LINQ-like operations on collections}
|
|
|
|
The purpose it 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.
|
|
|
|
{[
|
|
|
|
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 ()
|
|
]}
|
|
|
|
{b status: experimental}
|
|
|
|
*)
|
|
|
|
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 = [`Ok of 'a | `Error of string ]
|
|
|
|
(** {2 Polymorphic Maps} *)
|
|
module PMap : sig
|
|
type ('a, 'b) t
|
|
|
|
val get : ('a,'b) t -> 'a -> 'b option
|
|
|
|
val size : (_,_) t -> int
|
|
|
|
val to_seq : ('a, 'b) t -> ('a * 'b) sequence
|
|
|
|
val to_list : ('a, 'b) t -> ('a * 'b) list
|
|
|
|
val map : ('b -> 'c) -> ('a, 'b) t -> ('a, 'c) t
|
|
(** Transform values *)
|
|
|
|
val to_list : ('a,'b) t -> ('a*'b) list
|
|
|
|
val reverse : ?cmp:'b ord -> ?eq:'b equal -> ?hash:'b hash -> unit ->
|
|
('a,'b) t -> ('b,'a list) t
|
|
(** Reverse relation of the map, as a multimap *)
|
|
|
|
val reverse_multimap : ?cmp:'b ord -> ?eq:'b equal -> ?hash:'b hash -> unit ->
|
|
('a,'b list) t -> ('b,'a list) t
|
|
(** Reverse relation of the multimap *)
|
|
|
|
val fold : ('acc -> 'a -> 'b -> 'acc) -> 'acc -> ('a,'b) t -> 'acc
|
|
(** Fold on the items of the map *)
|
|
|
|
val fold_multimap : ('acc -> 'a -> 'b -> 'acc) -> 'acc ->
|
|
('a,'b list) t -> 'acc
|
|
(** Fold on the items of the multimap *)
|
|
|
|
val get_seq : 'a -> ('a, 'b) t -> 'b sequence
|
|
(** Select a key from a map and wrap into sequence *)
|
|
|
|
val iter : ('a,'b) t -> ('a*'b) sequence
|
|
(** View a multimap as a proper collection *)
|
|
|
|
val flatten : ('a,'b sequence) t -> ('a*'b) sequence
|
|
(** View a multimap as a collection of individual key/value pairs *)
|
|
|
|
val flatten_l : ('a,'b list) t -> ('a*'b) sequence
|
|
(** View a multimap as a collection of individual key/value pairs *)
|
|
end
|
|
|
|
(** {2 Query operators} *)
|
|
|
|
type 'a t
|
|
(** Type of a query that returns zero, one or more values of type 'a *)
|
|
|
|
(** {6 Initial values} *)
|
|
|
|
val empty : 'a t
|
|
(** Empty collection *)
|
|
|
|
val start : 'a -> 'a t
|
|
(** Start with a single value
|
|
@deprecated since NEXT_RELEASE, 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 *)
|
|
|
|
(** {6 Execution} *)
|
|
|
|
val run : ?limit:int -> 'a t -> 'a sequence
|
|
(** Execute the query, possibly returning an error if things go wrong
|
|
@param limit max number of values to return *)
|
|
|
|
val run1 : 'a t -> 'a
|
|
(** Run the query and return the first value
|
|
@raise Not_found if the query succeeds with 0 elements *)
|
|
|
|
val run_no_optim : ?limit:int -> 'a t -> 'a sequence
|
|
(** Run without any optimization *)
|
|
|
|
(** {6 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 flat_map_l : ('a -> 'b list) -> 'a t -> 'b t
|
|
|
|
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. *)
|
|
|
|
(** {6 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
|
|
|
|
(** {6 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 *)
|
|
|
|
(** {6 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 *)
|
|
|
|
(** {6 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} *)
|
|
|
|
(** {6 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 imediately run it. *)
|
|
|
|
val (>>=) : 'a t -> ('a -> 'b t) -> 'b t
|
|
(** Infix version of {!bind} *)
|
|
|
|
(** {6 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 *)
|
|
|
|
(** {6 Infix} *)
|
|
|
|
module Infix : sig
|
|
val (>>=) : 'a t -> ('a -> 'b t) -> 'b t
|
|
val (>|=) : 'a t -> ('a -> 'b) -> 'b t
|
|
val (<*>) : ('a -> 'b) t -> 'a t -> 'b t
|
|
val (--) : int -> int -> int t
|
|
end
|
|
|
|
(** {6 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
|
|
val of_list : 'a list -> 'a t
|
|
val to_list : 'a t -> 'a list t
|
|
val run : 'a t -> 'a list
|
|
end
|
|
|
|
module Array : sig
|
|
val of_array : 'a array -> 'a t
|
|
val to_array : 'a t -> 'a array t
|
|
val run : 'a t -> 'a array
|
|
end
|
|
|
|
module AdaptSet(S : Set.S) : sig
|
|
val of_set : S.t -> S.elt t
|
|
val to_set : S.elt t -> S.t t
|
|
val run : S.elt t -> S.t
|
|
end
|
|
|
|
module AdaptMap(M : Map.S) : sig
|
|
val of_map : 'a M.t -> (M.key * 'a) t
|
|
val to_pmap : 'a M.t -> (M.key, 'a) PMap.t
|
|
val to_map : (M.key * 'a) t -> 'a M.t t
|
|
val run : (M.key * 'a) t -> 'a M.t
|
|
end
|
|
|
|
module IO : sig
|
|
val slurp : in_channel -> string t
|
|
(** Slurp the whole channel in (blocking), returning the
|
|
corresponding string. The channel will be read at most once
|
|
during execution, and its content cached; however the channel
|
|
might never get read because evaluation is lazy. *)
|
|
|
|
val slurp_file : string -> string t
|
|
(** Read a whole file (given by name) and return its content as
|
|
a string *)
|
|
|
|
val lines : string t -> string t
|
|
(** Convert a string into a collection of lines *)
|
|
|
|
val lines' : string t -> string list t
|
|
(** Convert a string into a list of lines *)
|
|
|
|
val join : string -> string t -> string t
|
|
|
|
val unlines : string t -> string t
|
|
(** Join lines together *)
|
|
|
|
val out : out_channel -> string t -> unit
|
|
val out_lines : out_channel -> string t -> unit
|
|
(** Evaluate the query and print it line by line on the output *)
|
|
|
|
(** {8 Run methods} *)
|
|
|
|
val to_file : string -> string t -> unit with_err
|
|
val to_file_exn : string -> string t -> unit
|
|
|
|
val to_file_lines : string -> string t -> unit with_err
|
|
val to_file_lines_exn : string -> string t -> unit
|
|
end
|