# Copyright 2011  Petter Urkedal
#
# This file is part of the Viz Standard Library <http://www.vizlang.org/>.
#
# The Viz Standard Library (VSL) 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 3 of the License,
# or (at your option) any later version.
#
# The VSL 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 the VSL.  If not, see <http://www.gnu.org/licenses/>.


# Z.  Strings

open prelude.ubiquitous
open effect

sealed with

type t := string


# Z.Z.  String Primitives

in buf
    type r ψ

    val create : effect ψ (r ψ)

    val clear : r ψ → effect ψ unit

    val contents : r ψ → effect ψ string

    val length : r ψ → effect ψ int

    val put_char : r ψ → char → effect ψ unit

    val put_string : r ψ → string → effect ψ unit

val length : t → int
 ## (length x) is the number of characters used to represent (x), including
 ## accents, control characters, etc.

val get : int → t → char
 ## (get i x) is the (i)th character of (x).

val init : int → (int → char) → t
 ## (x = init n f) is the (n)-character string such that (get i x = f i) for
 ## (0 ≤ i < n).

val eq : t → t → bool
 ## Structural equality: (eq x y) is true iff (x) and (y) contain the same
 ## string.  Unicode normalization is not taken into account.

val cmp : t → t → torder
 ## (cmp x y) provides lexicographic order of Unicode code points between (x)
 ## and (y).  This is a fast non-collating and non-normalizing comparison.

val as_utf8 : t → utf8_string
val of_utf8 : utf8_string → t

val of_char : char → string

val show : string → string
 ## Quote a string.


# Z.Z.  Concatenation

val cat : t → t → t
 ## Concatenates two strings.

val cat_list : list t → t
 ## Concatenates the elements of a list.

val join : t → list t → t
 ## (join sep pieces) concatenates the elements of (pieces) with (sep) between
 ## each element.

val tile : int → t → t
 ## (tile n s) is the string containing (n) repetitions of (s).

val slice : int → int → t → t
 ## (slice i j s) is the (j - i)-character substring of (s) starting at (i).

val as_list : t → list char

val of_list : list char → t


# Z.Z.  Iteration

val fold : (char → α → α) → t → α → α

val foldr : (char → α → α) → t → α → α

val iter : (char → ψ/~ unit) → t → ψ/~ unit

val map : (char → char) → t → t

val mapi : (int → char → char) → t → t

val for_all : (char → bool) → t → bool

val for_some : (char → bool) → t → bool


# Z.Z.  Containment

val starts_with : t → t → bool

val ends_with : t → t → bool

val contains_char : char → t → bool

val contains_sub : t → t → bool

val count_char : char → t → int

val count_for : (char → bool) → t → int


# Z.Z.  Simple Skips and Scans

val skip_while : (char → bool) → t → int → int

val rskip_while : (char → bool) → t → int → int

val skip_space : t → int → int

val rskip_space : t → int → int

val skip_to_char : char → t → int → int

val rskip_to_char : char → t → int → int

val skip_to_sub : t → t → int → int

val scan_while : (char → bool) → t → int → t × int

val rscan_while : (char → bool) → t → int → t × int

val scan_to_char : char → t → int → t × int

val rscan_to_char : char → t → int → t × int

val scan_to_sub : t → t → int → t × int


# Z.Z.  Stripping Spaces or other Characters

val strip : t → t

val strip_left : t → t

val strip_right : t → t


# Z.Z.  Splitting

val split_where : (char → bool) → t → list t
 ## (split_where f s) splits (s) on characters on which (f) is true.  Empty
 ## components are kept, and the empty string is mapped to ([""]).

val split_on : char → t → list t
 ## (split_on ch f s ≡ split_where (char.eq ch) f s).

val csplit_where : (char → bool) → t → list t
 ## (csplit_where f s) splits (s) on contiguous characters where (f) is true,
 ## and strips out any continuous prefix or suffix where (f) is true.  That is,
 ## no empty strings are returned.

val csplit_on_space : t → list t
 ## (csplit_on_space s ≡ csplit_where char.is_space s) is the list of
 ## space-separated substrings of (s).

end

include prelude.string