(***********************************************************************)
(*                                                                     *)
(*                                 GALAX                               *)
(*                             XQuery Engine                           *)
(*                                                                     *)
(*  Copyright 2001-2003, Lucent Technologies.                          *)
(*  Distributed only by permission.                                    *)
(*                                                                     *)
(***********************************************************************)

(* $Id: gmisc.mli,v 1.14 2003/05/13 16:54:01 simeon Exp $ *)

(* Module Gmisc
   Description:
     This module implements some additions to the Caml standard
     library that appeared to be useful in the process of developing
     Galax.
*)

(* Note:
     All these functions raise standard Caml exceptions, rather than
     Galax exceptions in the rest of the system.
   - Jerome
 *)


(*****************)
(* I/O functions *)
(*****************)

(* Load the content of a file into a string *)

val load_file : string -> string


(******************)
(* List functions *)
(******************)

(* an additional function to partition list,
   but only getting the first element that satisfy
   the given predicate *)

val partition_first : ('a -> bool * 'b) -> 'a list -> 'b * 'a list

(* Filter non existing elements from a list *)

val filter_non_exists : 'a list -> 'a list -> 'a list

(* Map concat *)

val map_concat : ('a -> 'b list) -> 'a list -> 'b list

(* Triple split *)

val triple_split : ('a * 'b * 'c) list -> 'a list * 'b list * 'c list

(* Remove duplicates *)

val remove_duplicates : 'a list -> 'a list

(* Unwrap a list of optional values *)

val unwrap_option_list : 'a option list -> 'a list
val some_list : 'a option list -> 'a list
(*********************)
(* Hashtbl functions *)
(*********************)

val create_hashtable : int -> ('a * 'b) list -> ('a, 'b) Hashtbl.t
    (* Create a hashtable of the given size and fills it with the
       given bindings. *)

val all_of_hashtable : (('a, 'b) Hashtbl.t) -> ('a * 'b) list
    (* Returns all entries in hash table *)


(********************)
(* String functions *)
(********************)

val split_right_on_char  : string -> char -> string * string
val split_left_on_char   : string -> char -> string * string
val split_on_char        : string -> char -> string list
val remove_leading       : string -> char -> string
val remove_trailing      : string -> char -> string

(*********************)
(* Parsing functions *)
(*********************)

val wrap_lexer : (Lexing.lexbuf -> 'a) -> string -> 'a
    (* [wrap_lexer f s] applies the lexing function [f] on the
       string [s].
       Raises [Failure] in case of failure. *)


(**********************)
(* Printing functions *)
(**********************)

(* Print to stdout *)

val printf_stub : string -> (Format.formatter -> 'a -> unit) -> 'a -> unit

(* Print to stderr *)

val eprintf_stub : string -> (Format.formatter -> 'a -> unit) -> 'a -> unit

(* Print to output channel *)

val fprintf_stub : Format.formatter -> string -> (Format.formatter -> 'a -> unit) -> 'a -> unit

(* Print to a string buffer *)

val bprintf_stub : string -> (Format.formatter -> 'a -> unit) -> 'a -> string


(**********************)
(* Filename functions *)
(**********************)

(* Rename a DOS dir to a UNIX dir *)

val rename_dir : string -> string

