(* string  utility routines for ocaml
   Copyright (C) 2002, 2003, 2004 Shawn Wagner <shawnw@speakeasy.org>

   This library is free software; you can redistribute it and/or
   modify it under the terms of the GNU Lesser General Public
   License as published by the Free Software Foundation; either
   version 2.1 of the License, or (at your option) any later version.
   
   This library is distributed in the hope that it will be useful,
   but WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
   Lesser General Public License for more details.
   
   You should have received a copy of the GNU Lesser General Public
   License along with this library; if not, write to the Free Software
   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
*)

(** String functions *)

(** {1 String construction} *)

(** Concatenates a list of strings with a blank seperator *)
val combine: string list -> string

(** Turn a list of characters into a string. *)
val implode: char list -> string

(** Turn an array of characters into a string. *)
val of_array: char array -> string

(** Like [Array.map], for strings. Returns a newly allocated
transformed string.  *)
val map: (char -> char) -> string -> string

(** Like [map], but passes the index as well as the character. *)
val mapi: (char -> int -> char) -> string -> string

(** [subpos string startp endp] returns the substring of string
starting at position start and ending at position end. [subpos "foo."
0 2] returns "foo", for example. *)
val subpos: string -> int -> int -> string

(** [repeat s n] returns a new string made up of n copies of s. *)
val repeat: string -> int -> string

(** {2 Processing characters} *)

(** Like [String.iter], but passes the index of the character as well. *)
val iteri: (char -> int -> unit) -> string -> unit

(** [fold_left f x s] computes [f (... (f (f x s.[0]) s.[1])
  ...) s.[n-1]] where [n] is the length of the string [s]. *)
val fold_left: ('a -> char -> 'a) -> 'a -> string -> 'a

(** [fold_right f s x] computes
   [f s.(0) (f s.(1) ( ... (f s.(n-1) x) ...))],
   where [n] is the length of the string [s]. *)
val fold_right : ('a -> char -> 'a) -> string -> 'a -> 'a

(** [ensure f s] returns true if [f] is true for all characters in
  [s]. It stops after the first false result, making it more efficient
  than {!StrExtras.fold_left} for validation. *)
val ensure: (char -> bool) -> string -> bool

(** [ensure_range f s i len] applies [f] to the [len]-gth characters in [s]
  starting at index [i] and returns true if [f] is true for all the
  characters, otherwise false. *)
val ensure_range : (char -> bool) -> string -> int -> int -> bool


(** {2 String manipulation} *)

(** Most of these functions return newly allocated strings that are
modified versions of their arguments *)

(** Turn a string into a list of characters. *)
val explode: string -> char list

(** Turn a string into an array of characters. *)
val to_array: string -> char array

(** [center str length] returns str centered in a length-character
line. The default padding character is space. If trunc is true and the
string is longer than length, the string is truncated. *)
val center: ?pad:char -> ?trunc:bool -> string -> int -> string

(** [ljust str length] adds padding characters to the end of str if
needed so it is len characters long. The default padding character is a
space. If trunc is true, and the string is longer than length
characters, it is cut off. The default is to return a copy of string if
it is longer than length. *)
val ljust: ?pad:char -> ?trunc:bool -> string -> int -> string

(** Just like [rjust], but padding is added to the start of the string
if needed. *)
val rjust: ?pad:char -> ?trunc:bool -> string ->  int -> string

(** The direction that [trim] cuts characters from. *)
type trim_style = [ `Both | `Left | `Right ]

(** [trim string character] removes any leading and trailing
  occurances of character from string. style controls wether they're
  removed from just the front or back. *)
val trim: ?style:trim_style -> string -> char -> string

(** Like [map], but modifies the argument string. *)
val map_inplace: (char -> char) -> string -> unit

(** Like [map_inplace], but passes the index of the character as well. *)
val mapi_inplace: (char -> int -> char) -> string -> unit

(** Returns a reversed version of the string *)
val rev: string -> string

(** {3 Trimming off bits} *)

(** Returns the first word of a string *)
val first_word: string -> string

(** Cuts off the first character of a string and returns the rest *)
val cut_first_char: string -> string

(** Cuts off the first [n] characters of a string and returns the rest. *)
val cut_first_n: string -> int -> string

(** Cuts off the last character of a string and returns the rest *)
val cut_last_char: string -> string

(** Cuts off the last [n] characters of a string and returns the rest *)
val cut_last_n: string -> int -> string

(** Cuts off the first word of a string and returns the rest *)
val cut_first_word: string -> string

(** Returns everything after the character *)
val split_at: str:string -> sep:char -> string

(** Remove all trailing whitespace from a string *)
val chomp: string -> string

(** Return the rightmost n characters of a string *)
val right: string -> int -> string

(** Return the leftmost n characters of a string *)
val left: string -> int -> string

(** {3 Capitalization} *)

(** Like [String.uppercase], but locale-dependant *)
val uppercase: string -> string

(** Like [String.lowercase], but locale-dependant *)
val lowercase: string -> string

(** Like [String.capitalize], but locale-dependant *)
val capitalize: string -> string

(** Like [String.uncapitalize], but locale-dependant *)
val uncapitalize: string -> string

(** Lowercases all but the first letter in each word in the string, which is uppercased. *)
val titlecase: string -> string


(** {1 Searching} *)

(** [first_of needle haystack] returns the position of the first
  occurance in haystack of a character in needle. Like C strcspn(). *)
val first_of: string -> string -> int
  (**
    @raise Not_found if no characters in needle are in haystack 
  *)

(** [first_of_from needle haystack pos] returns the position of the first occurance in haystack (Starting at pos) of a character in needle. *)
val first_of_from: string -> string -> int -> int
  (**
    @raise Not_found if no characters in needle are in haystack 
  *)

(** [last_of needle haystack] returns the position of the last
  occurance in haystack of a character in needle. *)
val last_of: string -> string -> int
  (**
    @raise Not_found if no characters in needle are in haystack 
  *)

(** [last_of_from needle haystack pos] returns the position of the
  last occurance in haystack (Starting to look at pos) of a character in
  needle. *)
val last_of_from: string -> string -> int -> int
  (**
    @raise Not_found if no characters in needle are in haystack 
  *)

(** [first_not_of needle haystack] returns the position of the first
  occurance in haystack of a character that's not also in needle. Like C
  strspn(). *)
val first_not_of: string -> string -> int
  (**
    @raise Not_found if all characters in needle are in haystack 
  *)

(** [first_not_of_from needle haystack pos] returns the position of
  the first occurance in haystack (Starting at pos) of a character
  that's not also in needle. *)
val first_not_of_from: string -> string -> int -> int
  (**
    @raise Not_found if all characters in needle are in haystack 
  *)

(** [last_not_of needle haystack] returns the position of the last
  occurance in haystack of a character that's not also in needle. *)
val last_not_of: string -> string -> int
  (**
    @raise Not_found if all characters in needle are in haystack 
  *)

(** [last_not_of_from needle haystack pos] returns the position of the
  last occurance in haystack (Starting at pos) of a character that's not
  also in needle. *)
val last_not_of_from: string -> string -> int -> int
  (**
    @raise Not_found if all characters in needle are in haystack 
  *)

(** [prefix pref str] returns true if str starts with pref. *)
val prefix: string -> string -> bool

(** [suffix suf str] returns true if str ends with suf. *)
val suffix: string -> string -> bool

(** [index_substr needle haystack] returns the position in haystack
  where needle starts. *)
val index_substr: string -> string -> int
  (**
    @raise Not_found if the substring isn't present.
  *)

(** [index_substr_from needle haystack pos] returns the position in
  haystack where needle starts, starting looking at pos. *)
val index_substr_from: string -> string -> int -> int
  (**
    @raise Not_found if the substring isn't present.
    @raise Invalid_argument if the positition is outside of haystack.
  *)

(** [match_substr substr str pos] returns true if str contains substr
  at position pos *)
val match_substr: string -> string -> int -> bool
  (**
    @raise Invalid_argument if pos is out of range 
  *)

(** The functions in this module are for fast searching for the same
  substring multiple times. *)
module FastSearch : sig
  (** The idea is to take some extra time to analyze the search string
    to make each individual search for it go faster. These functions use
    the Boyer-Moore-Horspool algorithm. *)


  (** The type of an analyzed search string *)
  type t

    (** Analyze a search string *)
  val study: string -> t 


  (** [index needle haystack] returns the position in haystack where
    needle starts. *)
  val index: t -> string -> int
    (**
      @raise Not_found if the substring isn't present.
    *)

  (** [index_from needle haystack pos] returns the position in
    haystack where needle starts, starting looking at pos. *)
  val index_from: t -> string -> int -> int
    (**
      @raise Not_found if the substring isn't present.
      @raise Invalid_argument if the positition is outside of haystack.
    *)
end

(** Returns the longest prefix all the strings in the list have in
  common. For example, [common_prefix ["foobar"; "foobaz"; "food"]]
  returns ["foo"]. *)
val common_prefix: string list -> string

(** {1 Replacing} *)

(** [StrExtras.replace str old new] replaces every instance of [old]
  with [new] in [str] and returns a new string with the changes. *)
val replace: string -> string -> string -> string

(** {1 Comparison} *)

(** [collate a b] compares two strings like [String.compare], but
  using the [`LC_COLLATE] locale via the C strcoll()
  function. *)
val collate: string -> string -> int

(** [compare_insensitive a b] compares two strings in a
case-insensitive manner, using the current [`LC_CTYPE] locale. *)
val compare_insensitive: string -> string -> int

(** {2 Modules for comparision}

  These modules can be used as the input to functor like [Map.Make] or
  [Hashtbl.Make]
*)

(** Comparision using {!StrExtras.collate}. *)
module Collate: sig
  type t = string
  val compare: t -> t -> int
  val equal: t -> t -> bool
  val hash: t -> int
end

(** Comparision using {!StrExtras.compare_insensitive}. *)
module CaseInsensitive: sig
  type t = string
  val compare: t -> t -> int
  val equal: t -> t -> bool
  val hash: t -> int
end