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 Note: OCaml strings used to be modifiable in place, for instance via
34 the String.set and String.blit functions described below. This usage is
35 only possible when the compiler is put in "unsafe-string" mode by giv‐
36 ing the -unsafe-string command-line option. This compatibility mode
37 makes the types string and bytes (see module Bytes ) interchangeable so
38 that functions expecting byte sequences can also accept strings as ar‐
39 guments and modify them.
40 The distinction between bytes and string was introduced in OCaml 4.02,
42 and the "unsafe-string" compatibility mode was the default until OCaml
43 4.05. Starting with 4.06, the compatibility mode is opt-in; we intend
44 to remove the option in the future.
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 Raises Invalid_argument if n not a valid index in s .
65 val set : bytes -> int -> char -> unit
69 Deprecated. This is a deprecated alias of Bytes.set .
71 String.set s n c modifies byte sequence s in place, replacing the byte
76 at index n with c . You can also write s.[n] <- c instead of
77 String.set s n c .
78 Raises Invalid_argument if n is not a valid index in s .
81 val create : int -> bytes
85 Deprecated. This is a deprecated alias of Bytes.create .
87 String.create n returns a fresh byte sequence of length n . The se‐
92 quence is uninitialized and contains arbitrary bytes.
93 Raises Invalid_argument if n < 0 or n > Sys.max_string_length .
96 val make : int -> char -> string
100 String.make n c returns a fresh string of length n , filled with the
103 character c .
104 Raises Invalid_argument if n < 0 or n > Sys.max_string_length .
107 val init : int -> (int -> char) -> string
111 String.init n f returns a string of length n , with character i ini‐
114 tialized to the result of f i (called in increasing index order).
115 Since 4.02.0
118 Raises Invalid_argument if n < 0 or n > Sys.max_string_length .
121 val copy : string -> string
125 Deprecated. Because strings are immutable, it doesn't make much sense
127 to make identical copies of them.
128 Return a copy of the given string.
131 val sub : string -> int -> int -> string
135 String.sub s start len returns a fresh string of length len , contain‐
138 ing the substring of s that starts at position start and has length len
139 .
140 Raises Invalid_argument if start and len do not designate a valid sub‐
143 string of s .
144 val fill : bytes -> int -> int -> char -> unit
148 Deprecated. This is a deprecated alias of Bytes.fill .
150 String.fill s start len c modifies byte sequence s in place, replacing
155 len bytes with c , starting at start .
156 Raises Invalid_argument if start and len do not designate a valid range
159 of s .
160 val blit : string -> int -> bytes -> int -> int -> unit
164 Same as Bytes.blit_string .
166 val concat : string -> string list -> string
170 String.concat sep sl concatenates the list of strings sl , inserting
173 the separator string sep between each.
174 Raises Invalid_argument if the result is longer than
177 Sys.max_string_length bytes.
178 val iter : (char -> unit) -> string -> unit
182 String.iter f s applies function f in turn to all the characters of s .
185 It is equivalent to f s.[0]; f s.[1]; ...; f s.[String.length s - 1];
186 () .
187 val iteri : (int -> char -> unit) -> string -> unit
191 Same as String.iter , but the function is applied to the index of the
193 element as first argument (counting from 0), and the character itself
194 as second argument.
195 Since 4.00.0
198 val map : (char -> char) -> string -> string
202 String.map f s applies function f in turn to all the characters of s
205 (in increasing index order) and stores the results in a new string that
206 is returned.
207 Since 4.00.0
210 val mapi : (int -> char -> char) -> string -> string
214 String.mapi f s calls f with each character of s and its index (in in‐
217 creasing index order) and stores the results in a new string that is
218 returned.
219 Since 4.02.0
222 val trim : string -> string
226 Return a copy of the argument, without leading and trailing whitespace.
228 The characters regarded as whitespace are: ' ' , '\012' , '\n' , '\r' ,
229 and '\t' . If there is neither leading nor trailing whitespace charac‐
230 ter in the argument, return the original string itself, not a copy.
231 Since 4.00.0
234 val escaped : string -> string
238 Return a copy of the argument, with special characters represented by
240 escape sequences, following the lexical conventions of OCaml. All
241 characters outside the ASCII printable range (32..126) are escaped, as
242 well as backslash and double-quote.
243 If there is no special character in the argument that needs escaping,
245 return the original string itself, not a copy.
246 Raises Invalid_argument if the result is longer than
249 Sys.max_string_length bytes.
250 The function Scanf.unescaped is a left inverse of escaped , i.e.
252 Scanf.unescaped (escaped s) = s for any string s (unless escape s
253 fails).
254 val index : string -> char -> int
258 String.index s c returns the index of the first occurrence of character
261 c in string s .
262 Raises Not_found if c does not occur in s .
265 val index_opt : string -> char -> int option
269 String.index_opt s c returns the index of the first occurrence of char‐
272 acter c in string s , or None if c does not occur in s .
273 Since 4.05
276 val rindex : string -> char -> int
280 String.rindex s c returns the index of the last occurrence of character
283 c in string s .
284 Raises Not_found if c does not occur in s .
287 val rindex_opt : string -> char -> int option
291 String.rindex_opt s c returns the index of the last occurrence of char‐
294 acter c in string s , or None if c does not occur in s .
295 Since 4.05
298 val index_from : string -> int -> char -> int
302 String.index_from s i c returns the index of the first occurrence of
305 character c in string s after position i . String.index s c is equiva‐
306 lent to String.index_from s 0 c .
307 Raises Invalid_argument if i is not a valid position in s .
310 Raises Not_found if c does not occur in s after position i .
313 val index_from_opt : string -> int -> char -> int option
317 String.index_from_opt s i c returns the index of the first occurrence
320 of character c in string s after position i or None if c does not occur
321 in s after position i .
322 String.index_opt s c is equivalent to String.index_from_opt s 0 c .
325 Since 4.05
328 Raises Invalid_argument if i is not a valid position in s .
331 val rindex_from : string -> int -> char -> int
335 String.rindex_from s i c returns the index of the last occurrence of
338 character c in string s before position i+1 . String.rindex s c is
339 equivalent to String.rindex_from s (String.length s - 1) c .
340 Raises Invalid_argument if i+1 is not a valid position in s .
343 Raises Not_found if c does not occur in s before position i+1 .
346 val rindex_from_opt : string -> int -> char -> int option
350 String.rindex_from_opt s i c returns the index of the last occurrence
353 of character c in string s before position i+1 or None if c does not
354 occur in s before position i+1 .
355 String.rindex_opt s c is equivalent to String.rindex_from_opt s
358 (String.length s - 1) c .
359 Since 4.05
362 Raises Invalid_argument if i+1 is not a valid position in s .
365 val contains : string -> char -> bool
369 String.contains s c tests if character c appears in the string s .
372 val contains_from : string -> int -> char -> bool
376 String.contains_from s start c tests if character c appears in s after
379 position start . String.contains s c is equivalent to String.con‐
380 tains_from s 0 c .
381 Raises Invalid_argument if start is not a valid position in s .
384 val rcontains_from : string -> int -> char -> bool
388 String.rcontains_from s stop c tests if character c appears in s before
391 position stop+1 .
392 Raises Invalid_argument if stop < 0 or stop+1 is not a valid position
395 in s .
396 val uppercase : string -> string
400 Deprecated. Functions operating on Latin-1 character set are depre‐
402 cated.
403 Return a copy of the argument, with all lowercase letters translated to
406 uppercase, including accented letters of the ISO Latin-1 (8859-1) char‐
407 acter set.
408 val lowercase : string -> string
412 Deprecated. Functions operating on Latin-1 character set are depre‐
414 cated.
415 Return a copy of the argument, with all uppercase letters translated to
418 lowercase, including accented letters of the ISO Latin-1 (8859-1) char‐
419 acter set.
420 val capitalize : string -> string
424 Deprecated. Functions operating on Latin-1 character set are depre‐
426 cated.
427 Return a copy of the argument, with the first character set to upper‐
430 case, using the ISO Latin-1 (8859-1) character set..
431 val uncapitalize : string -> string
435 Deprecated. Functions operating on Latin-1 character set are depre‐
437 cated.
438 Return a copy of the argument, with the first character set to lower‐
441 case, using the ISO Latin-1 (8859-1) character set..
442 val uppercase_ascii : string -> string
446 Return a copy of the argument, with all lowercase letters translated to
448 uppercase, using the US-ASCII character set.
449 Since 4.03.0
452 val lowercase_ascii : string -> string
456 Return a copy of the argument, with all uppercase letters translated to
458 lowercase, using the US-ASCII character set.
459 Since 4.03.0
462 val capitalize_ascii : string -> string
466 Return a copy of the argument, with the first character set to upper‐
468 case, using the US-ASCII character set.
469 Since 4.03.0
472 val uncapitalize_ascii : string -> string
476 Return a copy of the argument, with the first character set to lower‐
478 case, using the US-ASCII character set.
479 Since 4.03.0
482 type t = string
485 An alias for the type of strings.
488 val compare : t -> t -> int
492 The comparison function for strings, with the same specification as
494 compare . Along with the type t , this function compare allows the
495 module String to be passed as argument to the functors Set.Make and
496 Map.Make .
497 val equal : t -> t -> bool
501 The equal function for strings.
503 Since 4.03.0
506 val split_on_char : char -> string -> string list
510 String.split_on_char sep s returns the list of all (possibly empty)
513 substrings of s that are delimited by the sep character.
514 The function's output is specified by the following invariants:
516 -The list is not empty.
519 -Concatenating its elements using sep as a separator returns a string
521 equal to the input ( String.concat (String.make 1 sep)
522 (String.split_on_char sep s) = s ).
523 -No string in the result contains the sep character.
525 Since 4.04.0
529 Iterators
534 val to_seq : t -> char Seq.t
535 Iterate on the string, in increasing index order. Modifications of the
537 string during iteration will be reflected in the iterator.
538 Since 4.07
541 val to_seqi : t -> (int * char) Seq.t
545 Iterate on the string, in increasing order, yielding indices along
547 chars
548 Since 4.07
551 val of_seq : char Seq.t -> t
555 Create a string from the generator
557 Since 4.07
560OCamldoc 2021-01-26 String(3)