(*
 * ExtString - Additional functions for string manipulations.
 * Copyright (C) 2003 Nicolas Cannasse
 * 
 * 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,
 * with the special exception on linking described in file LICENSE.
 *
 * 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
 *)

(** Additional functions for string manipulations. *)

open ExtBytes

exception Invalid_string

module String :
  sig

  (** {6 New Functions} *)

  val init : int -> (int -> char) -> string
  (** [init l f] returns the string of length [l] with the chars
      f 0 , f 1 , f 2 ... f (l-1). *)

  val find : string -> string -> int
  (** [find s x] returns the starting index of the string [x]
      within the string [s] or raises [Invalid_string] if [x]
      is not a substring of [s]. *)

  val find_from : string -> int -> string -> int
  (** [find s i x] returns the starting index of the string [x]
      within the string [s] (starting search from position [i]) or
      raises [Invalid_string] if no such substring exists.
      [find s x] is equivalent to [find_from s 0 x]. *)

  val split : string -> string -> string * string
  (** [split s sep] splits the string [s] between the first
      occurrence of [sep].
      raises [Invalid_string] if the separator is not found. *)

  val nsplit : string -> string -> string list
  (** [nsplit s sep] splits the string [s] into a list of strings
    which are separated by [sep].
                [nsplit "" _] returns the empty list.
    @raise Invalid_string if [sep] is empty string.  *)

  val join : string -> string list -> string
  (** Same as [concat] *)

  val slice : ?first:int -> ?last:int -> string -> string
  (** [slice ?first ?last s] returns a "slice" of the string
    which corresponds to the characters [s.[first]],
    [s.[first+1]], ..., [s[last-1]]. Note that the character at
    index [last] is {b not} included! If [first] is omitted it
    defaults to the start of the string, i.e. index 0, and if
    [last] is omitted is defaults to point just past the end of
    [s], i.e. [length s].  Thus, [slice s] is equivalent to
    [copy s].

    Negative indexes are interpreted as counting from the end of
    the string. For example, [slice ~last:-2 s] will return the
    string [s], but without the last two characters.

    This function {b never} raises any exceptions. If the
    indexes are out of bounds they are automatically clipped.
  *)

  val lchop : string -> string
  (** Returns the same string but without the first character.
      does nothing if the string is empty. *)

  val rchop : string -> string
  (** Returns the same string but without the last character.
     does nothing if the string is empty. *)

  val of_int : int -> string
  (** Returns the string representation of an int. *)

  val of_float : float -> string
  (** Returns the string representation of an float. *)

  val of_char : char -> string
  (** Returns a string containing one given character. *)

  val to_int : string -> int
  (** Returns the integer represented by the given string or
      raises [Invalid_string] if the string does not represent an integer.*)

  val to_float : string -> float
  (** Returns the float represented by the given string or
      raises Invalid_string if the string does not represent a float. *)

  val ends_with : string -> string -> bool
  (** [ends_with s x] returns true if the string [s] is ending with [x]. *)

  val starts_with : string -> string -> bool
  (** [starts_with s x] return true if [s] is starting with [x]. *)

  val enum : string -> char Enum.t
  (** Returns an enumeration of the characters of a string.*)

  val of_enum : char Enum.t -> string
  (** Creates a string from a character enumeration. *)

  val map : (char -> char) -> string -> string
  (** [map f s] returns a string where all characters [c] in [s] have been
    replaced by [f c]. **)

  val mapi : (int -> char -> char) -> string -> string
  (** [map f s] returns a string where all characters [c] in [s] have been replaced by [f i s.\[i\]]. **)

  val iteri : (int -> char -> unit) -> string -> unit
  (** Call [f i s.\[i\]] for every position [i] in string *)

  val fold_left : ('a -> char -> 'a) -> 'a -> string -> 'a
    (** [fold_left f a s] is
        [f (... (f (f a s.[0]) s.[1]) ...) s.[n-1]] *)
  val fold_right : (char -> 'a -> 'a) -> string -> 'a -> 'a
    (** [fold_right f s b] is
        [f s.[0] (f s.[1] (... (f s.[n-1] b) ...))] *)

  val explode : string -> char list
    (** [explode s] returns the list of characters in the string [s]. *)
  val implode : char list -> string
    (** [implode cs] returns a string resulting from concatenating
        the characters in the list [cs]. *)

  val strip : ?chars:string -> string -> string
  (** Returns the string without the chars if they are at the beginning or
    at the end of the string. By default chars are " \t\r\n". *)

  val exists : string -> string -> bool
  (** [exists str sub] returns true if [sub] is a substring of [str] or
    false otherwise. *)

  val replace_chars : (char -> string) -> string -> string
  (** [replace_chars f s] returns a string where all chars [c] of [s] have been
    replaced by the string returned by [f c]. *)

        val replace : str:string -> sub:string -> by:string -> bool * string
        (** [replace ~str ~sub ~by] returns a tuple constisting of a boolean
    and a string where the first occurrence of the string [sub]
    within [str] has been replaced by the string [by]. The boolean
    is true if a subtitution has taken place. *)

  (** Return a copy of the argument, without leading and trailing
     whitespace.  The characters regarded as whitespace are: [' '],
     ['\012'], ['\n'], ['\r'], and ['\t'].
     (Note that it is different from {!strip} defaults). *)
  val trim : string -> string

  (** {6 Compatibility Functions} *)

  val uppercase_ascii : string -> string
  val lowercase_ascii : string -> string
  val capitalize_ascii : string -> string
  val uncapitalize_ascii : string -> string

  val split_on_char : char -> string -> string list

  (** {6 Older Functions} *)

  (** Please refer to the Ocaml Manual for documentation of these
    functions. *)

  val length : string -> int
  val get : string -> int -> char
  val set : Bytes.t -> int -> char -> unit
  val create : int -> Bytes.t
  val make : int -> char -> string
  val copy : string -> string
  val sub : string -> int -> int -> string
  val fill : Bytes.t -> int -> int -> char -> unit
  val blit : string -> int -> Bytes.t -> int -> int -> unit
  val concat : string -> string list -> string
  val iter : (char -> unit) -> string -> unit
  val escaped : string -> string
  val index : string -> char -> int
  val index_opt : string -> char -> int option
  val rindex : string -> char -> int
  val rindex_opt : string -> char -> int option
  val index_from : string -> int -> char -> int
  val index_from_opt : string -> int -> char -> int option
  val rindex_from : string -> int -> char -> int
  val rindex_from_opt : string -> int -> char -> int option
  val contains : string -> char -> bool
  val contains_from : string -> int -> char -> bool
  val rcontains_from : string -> int -> char -> bool
  val uppercase : string -> string
  val lowercase : string -> string
  val capitalize : string -> string
  val uncapitalize : string -> string

  type t = string
  val compare : t -> t -> int
  val equal : t -> t -> bool

#if OCAML >= 407
  (** [*_seq] functions were introduced in OCaml 4.07.0, and are _not_ implemented in extlib for older OCaml versions *)
  val to_seq : t -> char Seq.t
  val to_seqi : t -> (int * char) Seq.t
  val of_seq : char Seq.t -> t
#endif

  (**/**)

  external unsafe_get : string -> int -> char = "%string_unsafe_get"
  val unsafe_set : Bytes.t -> int -> char -> unit
  val unsafe_blit : string -> int -> Bytes.t -> int -> int -> unit
  val unsafe_fill : Bytes.t -> int -> int -> char -> unit

  end