1String(3) OCaml library String(3)
2
6 String - String operations.
7
9 Module String
10
12 Module String
13 : sig end
14 String operations.
17 A string is an immutable data structure that contains a fixed-length
19 sequence of (single-byte) characters. Each character can be accessed in
20 constant time through its index.
21 Given a string s of length l , we can access each of the l characters
23 of s via its index in the sequence. Indexes start at 0 , and we will
24 call an index valid in s if it falls within the range [0...l-1] (inclu‐
25 sive). A position is the point between two characters or at the begin‐
26 ning or end of the string. We call a position valid in s if it falls
27 within the range [0...l] (inclusive). Note that the character at index
28 n is between positions n and n+1 .
29 Two parameters start and len are said to designate a valid substring of
31 s if len >= 0 and start and start+len are valid positions in s .
32 OCaml strings used to be modifiable in place, for instance via the
34 String.set and String.blit functions described below. This usage is
35 deprecated and only possible when the compiler is put in
36 "unsafe-string" mode by giving the -unsafe-string command-line option
37 (which is currently the default for reasons of backward compatibility).
38 This is done by making the types string and bytes (see module Bytes )
39 interchangeable so that functions expecting byte sequences can also
40 accept strings as arguments and modify them.
41 All new code should avoid this feature and be compiled with the
43 -safe-string command-line option to enforce the separation between the
44 types string and bytes .
45 val length : string -> int
52 Return the length (number of characters) of the given string.
54 val get : string -> int -> char
58 String.get s n returns the character at index n in string s . You can
61 also write s.[n] instead of String.get s n .
62 Raise Invalid_argument if n not a valid index in s .
64 val set : bytes -> int -> char -> unit
68 Deprecated. This is a deprecated alias of Bytes.set .
70 String.set s n c modifies byte sequence s in place, replacing the byte
75 at index n with c . You can also write s.[n] <- c instead of
76 String.set s n c .
77 Raise Invalid_argument if n is not a valid index in s .
79 val create : int -> bytes
83 Deprecated. This is a deprecated alias of Bytes.create .
85 String.create n returns a fresh byte sequence of length n . The
90 sequence is uninitialized and contains arbitrary bytes.
91 Raise Invalid_argument if n < 0 or n > Sys.max_string_length .
93 val make : int -> char -> string
97 String.make n c returns a fresh string of length n , filled with the
100 character c .
101 Raise Invalid_argument if n < 0 or n > Sys.max_string_length .
103 val init : int -> (int -> char) -> string
107 String.init n f returns a string of length n , with character i ini‐
110 tialized to the result of f i (called in increasing index order).
111 Raise Invalid_argument if n < 0 or n > Sys.max_string_length .
113 Since 4.02.0
116 val copy : string -> string
120 Deprecated. Because strings are immutable, it doesn't make much sense
122 to make identical copies of them.
123 Return a copy of the given string.
126 val sub : string -> int -> int -> string
130 String.sub s start len returns a fresh string of length len , contain‐
133 ing the substring of s that starts at position start and has length len
134 .
135 Raise Invalid_argument if start and len do not designate a valid sub‐
137 string of s .
138 val fill : bytes -> int -> int -> char -> unit
142 Deprecated. This is a deprecated alias of Bytes.fill .
144 String.fill s start len c modifies byte sequence s in place, replacing
149 len bytes with c , starting at start .
150 Raise Invalid_argument if start and len do not designate a valid range
152 of s .
153 val blit : string -> int -> bytes -> int -> int -> unit
157 Same as Bytes.blit_string .
159 val concat : string -> string list -> string
163 String.concat sep sl concatenates the list of strings sl , inserting
166 the separator string sep between each.
167 Raise Invalid_argument if the result is longer than
169 Sys.max_string_length bytes.
170 val iter : (char -> unit) -> string -> unit
174 String.iter f s applies function f in turn to all the characters of s .
177 It is equivalent to f s.[0]; f s.[1]; ...; f s.[String.length s - 1];
178 () .
179 val iteri : (int -> char -> unit) -> string -> unit
183 Same as String.iter , but the function is applied to the index of the
185 element as first argument (counting from 0), and the character itself
186 as second argument.
187 Since 4.00.0
190 val map : (char -> char) -> string -> string
194 String.map f s applies function f in turn to all the characters of s
197 (in increasing index order) and stores the results in a new string that
198 is returned.
199 Since 4.00.0
202 val mapi : (int -> char -> char) -> string -> string
206 String.mapi f s calls f with each character of s and its index (in
209 increasing index order) and stores the results in a new string that is
210 returned.
211 Since 4.02.0
214 val trim : string -> string
218 Return a copy of the argument, without leading and trailing whitespace.
220 The characters regarded as whitespace are: ' ' , '\012' , '\n' , '\r' ,
221 and '\t' . If there is neither leading nor trailing whitespace charac‐
222 ter in the argument, return the original string itself, not a copy.
223 Since 4.00.0
226 val escaped : string -> string
230 Return a copy of the argument, with special characters represented by
232 escape sequences, following the lexical conventions of OCaml. All
233 characters outside the ASCII printable range (32..126) are escaped, as
234 well as backslash and double-quote.
235 If there is no special character in the argument that needs escaping,
237 return the original string itself, not a copy.
238 Raise Invalid_argument if the result is longer than
240 Sys.max_string_length bytes.
241 The function Scanf.unescaped is a left inverse of escaped , i.e.
243 Scanf.unescaped (escaped s) = s for any string s (unless escape s
244 fails).
245 val index : string -> char -> int
249 String.index s c returns the index of the first occurrence of character
252 c in string s .
253 Raise Not_found if c does not occur in s .
255 val index_opt : string -> char -> int option
259 String.index_opt s c returns the index of the first occurrence of char‐
262 acter c in string s , or None if c does not occur in s .
263 Since 4.05
266 val rindex : string -> char -> int
270 String.rindex s c returns the index of the last occurrence of character
273 c in string s .
274 Raise Not_found if c does not occur in s .
276 val rindex_opt : string -> char -> int option
280 String.rindex_opt s c returns the index of the last occurrence of char‐
283 acter c in string s , or None if c does not occur in s .
284 Since 4.05
287 val index_from : string -> int -> char -> int
291 String.index_from s i c returns the index of the first occurrence of
294 character c in string s after position i . String.index s c is equiva‐
295 lent to String.index_from s 0 c .
296 Raise Invalid_argument if i is not a valid position in s . Raise
298 Not_found if c does not occur in s after position i .
299 val index_from_opt : string -> int -> char -> int option
303 String.index_from_opt s i c returns the index of the first occurrence
306 of character c in string s after position i or None if c does not occur
307 in s after position i .
308 String.index_opt s c is equivalent to String.index_from_opt s 0 c .
311 Raise Invalid_argument if i is not a valid position in s .
312 Since 4.05
315 val rindex_from : string -> int -> char -> int
319 String.rindex_from s i c returns the index of the last occurrence of
322 character c in string s before position i+1 . String.rindex s c is
323 equivalent to String.rindex_from s (String.length s - 1) c .
324 Raise Invalid_argument if i+1 is not a valid position in s . Raise
326 Not_found if c does not occur in s before position i+1 .
327 val rindex_from_opt : string -> int -> char -> int option
331 String.rindex_from_opt s i c returns the index of the last occurrence
334 of character c in string s before position i+1 or None if c does not
335 occur in s before position i+1 .
336 String.rindex_opt s c is equivalent to String.rindex_from_opt s
339 (String.length s - 1) c .
340 Raise Invalid_argument if i+1 is not a valid position in s .
342 Since 4.05
345 val contains : string -> char -> bool
349 String.contains s c tests if character c appears in the string s .
352 val contains_from : string -> int -> char -> bool
356 String.contains_from s start c tests if character c appears in s after
359 position start . String.contains s c is equivalent to String.con‐
360 tains_from s 0 c .
361 Raise Invalid_argument if start is not a valid position in s .
363 val rcontains_from : string -> int -> char -> bool
367 String.rcontains_from s stop c tests if character c appears in s before
370 position stop+1 .
371 Raise Invalid_argument if stop < 0 or stop+1 is not a valid position in
373 s .
374 val uppercase : string -> string
378 Deprecated. Functions operating on Latin-1 character set are depre‐
380 cated.
381 Return a copy of the argument, with all lowercase letters translated to
384 uppercase, including accented letters of the ISO Latin-1 (8859-1) char‐
385 acter set.
386 val lowercase : string -> string
390 Deprecated. Functions operating on Latin-1 character set are depre‐
392 cated.
393 Return a copy of the argument, with all uppercase letters translated to
396 lowercase, including accented letters of the ISO Latin-1 (8859-1) char‐
397 acter set.
398 val capitalize : string -> string
402 Deprecated. Functions operating on Latin-1 character set are depre‐
404 cated.
405 Return a copy of the argument, with the first character set to upper‐
408 case, using the ISO Latin-1 (8859-1) character set..
409 val uncapitalize : string -> string
413 Deprecated. Functions operating on Latin-1 character set are depre‐
415 cated.
416 Return a copy of the argument, with the first character set to lower‐
419 case, using the ISO Latin-1 (8859-1) character set..
420 val uppercase_ascii : string -> string
424 Return a copy of the argument, with all lowercase letters translated to
426 uppercase, using the US-ASCII character set.
427 Since 4.03.0
430 val lowercase_ascii : string -> string
434 Return a copy of the argument, with all uppercase letters translated to
436 lowercase, using the US-ASCII character set.
437 Since 4.03.0
440 val capitalize_ascii : string -> string
444 Return a copy of the argument, with the first character set to upper‐
446 case, using the US-ASCII character set.
447 Since 4.03.0
450 val uncapitalize_ascii : string -> string
454 Return a copy of the argument, with the first character set to lower‐
456 case, using the US-ASCII character set.
457 Since 4.03.0
460 type t = string
463 An alias for the type of strings.
466 val compare : t -> t -> int
470 The comparison function for strings, with the same specification as
472 Pervasives.compare . Along with the type t , this function compare
473 allows the module String to be passed as argument to the functors
474 Set.Make and Map.Make .
475 val equal : t -> t -> bool
479 The equal function for strings.
481 Since 4.03.0
484 val split_on_char : char -> string -> string list
488 String.split_on_char sep s returns the list of all (possibly empty)
491 substrings of s that are delimited by the sep character.
492 The function's output is specified by the following invariants:
494 -The list is not empty.
497 -Concatenating its elements using sep as a separator returns a string
499 equal to the input ( String.concat (String.make 1 sep)
500 (String.split_on_char sep s) = s ).
501 -No string in the result contains the sep character.
503 Since 4.04.0
507 === Iterators ===
512 val to_seq : t -> char Seq.t
515 Iterate on the string, in increasing index order. Modifications of the
517 string during iteration will be reflected in the iterator.
518 Since 4.07
521 val to_seqi : t -> (int * char) Seq.t
525 Iterate on the string, in increasing order, yielding indices along
527 chars
528 Since 4.07
531 val of_seq : char Seq.t -> t
535 Create a string from the generator
537 Since 4.07
540OCamldoc 2018-07-14 String(3)