Previous  Up  

Module String.Cap


module String.Cap: sig .. end
Capabilities for strings.

This modules provides the same set of features as String, but with the added twist that strings can be made read-only or write-only. Read-only strings may then be safely shared and distributed.

There is no loss of performance involved.

type 'a t
The type of capability strings.

If 'a contains [`Read], the contents of the string may be read. If 'a contains [`Write], the contents of the string may be written.

Other (user-defined) capabilities may be added without loss of performance or features. For instance, a string could be labelled [`Read | `UTF8] to state that it contains UTF-8 encoded data and may be used only for reading. Conversely, a string labelled with [] (i.e. nothing) can neither be read nor written. It can only be compared for textual equality using OCaml's built-in compare or for physical equality using OCaml's built-in ==.

val length : 'a t -> int
Return the length (number of characters) of the given string.
val is_empty : 'a t -> bool
Determine if a string is empty.
val get : [> `Read ] t -> int -> char
String.get s n returns character number n in string s. The first character is character number 0. The last character is character number String.length s - 1. You can also write s.[n] instead of String.get s n.

Raise Invalid_argument "index out of bounds" if n is outside the range 0 to (String.length s - 1).

val set : [> `Write ] t -> int -> char -> unit
String.set s n c modifies string s in place, replacing the character number n by c. You can also write s.[n] <- c instead of String.set s n c. Raise Invalid_argument "index out of bounds" if n is outside the range 0 to (String.length s - 1).
val create : int -> 'a t
String.create n returns a fresh string of length n. The string initially contains arbitrary characters. Raise Invalid_argument if n < 0 or n > Sys.max_string_length.

Constructors

val of_string : string -> 'a t
Adopt a regular string.
val to_string : [ `Read | `Write ] t -> string
Return a capability string as a regular string.
val read_only : [> `Read ] t ->
       [ `Read ] t
Drop capabilities to read only.
val write_only : [> `Write ] t ->
       [ `Write ] t
Drop capabilities to write only.
val make : int -> char -> 'a t
String.make n c returns a fresh string of length n, filled with the character c. Raise Invalid_argument if n < 0 or n > Sys.max_string_length.
val init : int -> (int -> char) -> 'a t
init l f returns the string of length l with the chars f 0 , f 1 , f 2 ... f (l-1).
val enum : [> `Read ] t -> char Enum.t
Conversions

Returns an enumeration of the characters of a string.

val of_enum : char Enum.t -> 'a t
Creates a string from a character enumeration.
val backwards : [> `Read ] t -> char Enum.t
Returns an enumeration of the characters of a string, from last to first.
val of_backwards : char Enum.t -> 'a t
Build a string from an enumeration, starting with last character, ending with first.
val of_list : char list -> 'a t
Converts a list of characters to a string.
val to_list : [> `Read ] t -> char list
Converts a string to the list of its characters.
val of_int : int -> 'a t
Returns the string representation of an int.
val of_float : float -> 'a t
Returns the string representation of an float.
val of_char : char -> 'a t
Returns a string containing one given character.
val to_int : [> `Read ] t -> int
Returns the integer represented by the given string or raises Invalid_string if the string does not represent an integer.
val to_float : [> `Read ] t -> float
Returns the float represented by the given string or raises Invalid_string if the string does not represent a float.

String traversals

val map : (char -> char) ->
       [> `Read ] t -> 'a t
map f s returns a string where all characters c in s have been replaced by f c. *
val fold_left : ('a -> char -> 'a) -> 'a -> [> `Read ] t -> 'a
fold_left f a s is f (... (f (f a s.[0]) s.[1]) ...) s.[n-1]
val fold_right : (char -> 'a -> 'a) -> [> `Read ] t -> 'a -> 'a
fold_right f s b is f s.[0] (f s.[1] (... (f s.[n-1] b) ...))
val filter : (char -> bool) ->
       [> `Read ] t -> 'a t
filter f s returns a copy of string s in which only characters c such that f c = true remain.
val filter_map : (char -> char option) ->
       [> `Read ] t -> 'a t
filter_map f s calls (f a0) (f a1).... (f an) where a0..an are the characters of s. It returns the string of characters ci such as f ai = Some ci (when f returns None, the corresponding element of s is discarded).
val iter : (char -> unit) -> [> `Read ] t -> unit
String.iter f s applies function f in turn to all the characters of s. It is equivalent to f s.[0]; f s.[1]; ...; f s.[String.length s - 1]; ().

Finding

val index : [> `Read ] t -> char -> int
String.index s c returns the position of the leftmost occurrence of character c in string s. Raise Not_found if c does not occur in s.
val rindex : [> `Read ] t -> char -> int
String.rindex s c returns the position of the rightmost occurrence of character c in string s. Raise Not_found if c does not occur in s.
val index_from : [> `Read ] t -> int -> char -> int
Same as String.index, but start searching at the character position given as second argument. String.index s c is equivalent to String.index_from s 0 c.
val rindex_from : [> `Read ] t -> int -> char -> int
Same as String.rindex, but start searching at the character position given as second argument. String.rindex s c is equivalent to String.rindex_from s (String.length s - 1) c.
val contains : [> `Read ] t -> char -> bool
String.contains s c tests if character c appears in the string s.
val contains_from : [> `Read ] t -> int -> char -> bool
String.contains_from s start c tests if character c appears in the substring of s starting from start to the end of s. Raise Invalid_argument if start is not a valid index of s.
val rcontains_from : [> `Read ] t -> int -> char -> bool
String.rcontains_from s stop c tests if character c appears in the substring of s starting from the beginning of s to index stop. Raise Invalid_argument if stop is not a valid index of s.
val find : [> `Read ] t ->
       [> `Read ] t -> 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 : [> `Read ] t ->
       int -> [> `Read ] t -> int
find_from s ofs x behaves as find s x but starts searching at offset ofs. find s x is equivalent to find_from s 0 x.
val rfind : [> `Read ] t ->
       [> `Read ] t -> int
rfind s x returns the starting index of the last occurrence of string x within string s.

Note This implementation is optimized for short strings.
Raises Invalid_string if x is not a substring of s.

val rfind_from : [> `Read ] t ->
       int -> [> `Read ] t -> int
rfind_from s ofs x behaves as rfind s x but starts searching at offset ofs. rfind s x is equivalent to rfind_from s (String.length s - 1) x.
val ends_with : [> `Read ] t ->
       [> `Read ] t -> bool
ends_with s x returns true if the string s is ending with x.
val starts_with : [> `Read ] t ->
       [> `Read ] t -> bool
starts_with s x return true if s is starting with x.
val exists : [> `Read ] t ->
       [> `Read ] t -> bool
exists str sub returns true if sub is a substring of str or false otherwise.

Transformations

val lchop : [> `Read ] t -> 'a t
Returns the same string but without the first character. does nothing if the string is empty.
val rchop : [> `Read ] t -> 'a t
Returns the same string but without the last character. does nothing if the string is empty.
val trim : [> `Read ] t -> 'a t
Returns the same string but without the leading and trailing whitespaces.
val quote : [> `Read ] t -> string
Add quotes around a string and escape any quote appearing in that string. This function is used typically when you need to generate source code from a string.

quote ro"foo" returns ro"\"foo\"" quote ro"\"foo\"" returns ro"\\\"foo\\\"" etc.

val left : [> `Read ] t ->
       int -> 'a t
left r len returns the string containing the len first characters of r
val right : [> `Read ] t ->
       int -> 'a t
left r len returns the string containing the len last characters of r
val head : [> `Read ] t ->
       int -> 'a t
as String.Cap.left
val tail : [> `Read ] t ->
       int -> 'a t
tail r pos returns the string containing all but the pos first characters of r
val strip : ?chars:[> `Read ] t ->
       [> `Read ] t -> 'a t
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 uppercase : [> `Read ] t -> 'a t
Return a copy of the argument, with all lowercase letters translated to uppercase, including accented letters of the ISO Latin-1 (8859-1) character set.
val lowercase : [> `Read ] t -> 'a t
Return a copy of the argument, with all uppercase letters translated to lowercase, including accented letters of the ISO Latin-1 (8859-1) character set.
val capitalize : [> `Read ] t -> 'a t
Return a copy of the argument, with the first character set to uppercase.
val uncapitalize : [> `Read ] t -> 'a t
Return a copy of the argument, with the first character set to lowercase.
val copy : [> `Read ] t -> 'a t
Return a copy of the given string.
val sub : [> `Read ] t ->
       int -> int -> 'a t
String.sub s start len returns a fresh string of length len, containing the characters number start to start + len - 1 of string s. Raise Invalid_argument if start and len do not designate a valid substring of s; that is, if start < 0, or len < 0, or start + len > String.length s.
val fill : [> `Write ] t -> int -> int -> char -> unit
String.fill s start len c modifies string s in place, replacing the characters number start to start + len - 1 by c. Raise Invalid_argument if start and len do not designate a valid substring of s.
val blit : [> `Read ] t ->
       int -> [> `Write ] t -> int -> int -> unit
String.blit src srcoff dst dstoff len copies len characters from string src, starting at character number srcoff, to string dst, starting at character number dstoff. It works correctly even if src and dst are the same string, and the source and destination chunks overlap. Raise Invalid_argument if srcoff and len do not designate a valid substring of src, or if dstoff and len do not designate a valid substring of dst.
val concat : [> `Read ] t ->
       [> `Read ] t list ->
       'a t
String.concat sep sl concatenates the list of strings sl, inserting the separator string sep between each.
val escaped : [> `Read ] t -> 'a t
Return a copy of the argument, with special characters represented by escape sequences, following the lexical conventions of Objective Caml. If there is no special character in the argument, return the original string itself, not a copy.
val replace_chars : (char -> [> `Read ] t) ->
       [> `Read ] t -> 'a t
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:[> `Read ] t ->
       sub:[> `Read ] t ->
       by:[> `Read ] t ->
       bool * 'a t
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.
val repeat : [> `Read ] t ->
       int -> 'a t
repeat s n returns s ^ s ^ ... ^ s
val split : [> `Read ] t ->
       [> `Read ] t ->
       'a t * 'b t
Splitting around

split s sep splits the string s between the first occurrence of sep. raises Invalid_string if the separator is not found.

val rsplit : [> `Read ] t -> string -> string * string
rsplit s sep splits the string s between the last occurrence of sep. raises Invalid_string if the separator is not found.
val nsplit : [> `Read ] t ->
       [> `Read ] t ->
       'a t list
nsplit s sep splits the string s into a list of strings which are separated by sep. nsplit "" _ returns the empty list.
val splice : [ `Read | `Write ] t ->
       int -> int -> [> `Read ] t -> string
String.splice s off len rep cuts out the section of s indicated by off and len and replaces it by rep
val join : [> `Read ] t ->
       [> `Read ] t list ->
       'a t
Same as concat
val slice : ?first:int ->
       ?last:int ->
       [> `Read ] t -> 'a t
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 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 never raises any exceptions. If the indexes are out of bounds they are automatically clipped.

val explode : [> `Read ] t -> char list
explode s returns the list of characters in the string s.
val implode : char list -> 'a t
implode cs returns a string resulting from concatenating the characters in the list cs.

Comparisons

val compare : [> `Read ] t ->
       [> `Read ] t -> int
The comparison function for strings, with the same specification as Standard.compare. Along with the type t, this function compare allows the module String to be passed as argument to the functors Set.Make and Map.Make.
val icompare : [> `Read ] t ->
       [> `Read ] t -> int
Compare two strings, case-insensitive.

Printing

val print : 'a Extlib.InnerIO.output -> [> `Read ] t -> unit
Print a string.
val println : 'a Extlib.InnerIO.output -> [> `Read ] t -> unit
Print a string, end the line.
val print_quoted : 'a Extlib.InnerIO.output -> [> `Read ] t -> unit
Print a string, with quotes.

print_quoted stdout "foo" prints "foo" (with the quotes)

print_quoted stdout "\"bar\"" prints "\"bar\"" (with the quotes)

val t_printer : [> `Read ] t Value_printer.t