1String(3) OCaml library String(3)
2
6 String - Strings.
7
9 Module String
10
12 Module String
13 : sig end
14 Strings.
17 A string s of length n is an indexable and immutable sequence of n
19 bytes. For historical reasons these bytes are referred to as charac‐
20 ters.
21 The semantics of string functions is defined in terms of indices and
23 positions. These are depicted and described as follows.
24 positions 0 1 2 3 4 n-1 n +---+---+---+---+ +-----+
26 indices | 0 | 1 | 2 | 3 | ... | n-1 | +---+---+---+---+ +-----+
27 -An index i of s is an integer in the range [ 0 ; n-1 ]. It represents
29 the i th byte (character) of s which can be accessed using the constant
30 time string indexing operator s.[i] .
31 -A position i of s is an integer in the range [ 0 ; n ]. It represents
33 either the point at the beginning of the string, or the point between
34 two indices, or the point at the end of the string. The i th byte index
35 is between position i and i+1 .
36 Two integers start and len are said to define a valid substring of s if
39 len >= 0 and start , start+len are positions of s .
40 Unicode text. Strings being arbitrary sequences of bytes, they can hold
42 any kind of textual encoding. However the recommended encoding for
43 storing Unicode text in OCaml strings is UTF-8. This is the encoding
44 used by Unicode escapes in string literals. For example the string
45 "\u{1F42B}" is the UTF-8 encoding of the Unicode character U+1F42B.
46 Past mutability. OCaml strings used to be modifiable in place, for in‐
48 stance via the String.set and String.blit functions. This use is nowa‐
49 days only possible when the compiler is put in "unsafe-string" mode by
50 giving the -unsafe-string command-line option. This compatibility mode
51 makes the types string and bytes (see Bytes.t ) interchangeable so that
52 functions expecting byte sequences can also accept strings as arguments
53 and modify them.
54 The distinction between bytes and string was introduced in OCaml 4.02,
56 and the "unsafe-string" compatibility mode was the default until OCaml
57 4.05. Starting with 4.06, the compatibility mode is opt-in; we intend
58 to remove the option in the future.
59 The labeled version of this module can be used as described in the Std‐
61 Labels module.
62 Strings
70 type t = string
71 The type for strings.
74 val make : int -> char -> string
78 make n c is a string of length n with each index holding the character
81 c .
82 Raises Invalid_argument if n < 0 or n > Sys.max_string_length .
85 val init : int -> (int -> char) -> string
89 init n f is a string of length n with index i holding the character f i
92 (called in increasing index order).
93 Since 4.02.0
96 Raises Invalid_argument if n < 0 or n > Sys.max_string_length .
99 val length : string -> int
103 length s is the length (number of bytes/characters) of s .
106 val get : string -> int -> char
110 get s i is the character at index i in s . This is the same as writing
113 s.[i] .
114 Raises Invalid_argument if i not an index of s .
117 Concatenating
122 Note. The (^) binary operator concatenates two strings.
123 val concat : string -> string list -> string
125 concat sep ss concatenates the list of strings ss , inserting the sepa‐
128 rator string sep between each.
129 Raises Invalid_argument if the result is longer than
132 Sys.max_string_length bytes.
133 Predicates and comparisons
138 val equal : t -> t -> bool
139 equal s0 s1 is true if and only if s0 and s1 are character-wise equal.
142 Since 4.03.0 (4.05.0 in StringLabels)
145 val compare : t -> t -> int
149 compare s0 s1 sorts s0 and s1 in lexicographical order. compare be‐
152 haves like compare on strings but may be more efficient.
153 val contains_from : string -> int -> char -> bool
157 contains_from s start c is true if and only if c appears in s after po‐
160 sition start .
161 Raises Invalid_argument if start is not a valid position in s .
164 val rcontains_from : string -> int -> char -> bool
168 rcontains_from s stop c is true if and only if c appears in s before
171 position stop+1 .
172 Raises Invalid_argument if stop < 0 or stop+1 is not a valid position
175 in s .
176 val contains : string -> char -> bool
180 contains s c is String.contains_from s 0 c .
183 Extracting substrings
188 val sub : string -> int -> int -> string
189 sub s pos len is a string of length len , containing the substring of s
192 that starts at position pos and has length len .
193 Raises Invalid_argument if pos and len do not designate a valid sub‐
196 string of s .
197 val split_on_char : char -> string -> string list
201 split_on_char sep s is the list of all (possibly empty) substrings of s
204 that are delimited by the character sep .
205 The function's result is specified by the following invariants:
207 -The list is not empty.
209 -Concatenating its elements using sep as a separator returns a string
211 equal to the input ( concat (make 1 sep)
212 (split_on_char sep s) = s ).
213 -No string in the result contains the sep character.
215 Since 4.04.0 (4.05.0 in StringLabels)
219 Transforming
224 val map : (char -> char) -> string -> string
225 map f s is the string resulting from applying f to all the characters
228 of s in increasing order.
229 Since 4.00.0
232 val mapi : (int -> char -> char) -> string -> string
236 mapi f s is like String.map but the index of the character is also
239 passed to f .
240 Since 4.02.0
243 val trim : string -> string
247 trim s is s without leading and trailing whitespace. Whitespace charac‐
250 ters are: ' ' , '\x0C' (form feed), '\n' , '\r' , and '\t' .
251 Since 4.00.0
254 val escaped : string -> string
258 escaped s is s with special characters represented by escape sequences,
261 following the lexical conventions of OCaml.
262 All characters outside the US-ASCII printable range [0x20;0x7E] are es‐
264 caped, as well as backslash (0x2F) and double-quote (0x22).
265 The function Scanf.unescaped is a left inverse of escaped , i.e.
267 Scanf.unescaped (escaped s) = s for any string s (unless escaped s
268 fails).
269 Raises Invalid_argument if the result is longer than
272 Sys.max_string_length bytes.
273 val uppercase_ascii : string -> string
277 uppercase_ascii s is s with all lowercase letters translated to upper‐
280 case, using the US-ASCII character set.
281 Since 4.03.0 (4.05.0 in StringLabels)
284 val lowercase_ascii : string -> string
288 lowercase_ascii s is s with all uppercase letters translated to lower‐
291 case, using the US-ASCII character set.
292 Since 4.03.0 (4.05.0 in StringLabels)
295 val capitalize_ascii : string -> string
299 capitalize_ascii s is s with the first character set to uppercase, us‐
302 ing the US-ASCII character set.
303 Since 4.03.0 (4.05.0 in StringLabels)
306 val uncapitalize_ascii : string -> string
310 uncapitalize_ascii s is s with the first character set to lowercase,
313 using the US-ASCII character set.
314 Since 4.03.0 (4.05.0 in StringLabels)
317 Traversing
322 val iter : (char -> unit) -> string -> unit
323 iter f s applies function f in turn to all the characters of s . It is
326 equivalent to f s.[0]; f s.[1]; ...; f s.[length s - 1]; () .
327 val iteri : (int -> char -> unit) -> string -> unit
331 iteri is like String.iter , but the function is also given the corre‐
334 sponding character index.
335 Since 4.00.0
338 Searching
343 val index_from : string -> int -> char -> int
344 index_from s i c is the index of the first occurrence of c in s after
347 position i .
348 Raises Not_found if c does not occur in s after position i .
351 Raises Invalid_argument if i is not a valid position in s .
354 val index_from_opt : string -> int -> char -> int option
358 index_from_opt s i c is the index of the first occurrence of c in s af‐
361 ter position i (if any).
362 Since 4.05
365 Raises Invalid_argument if i is not a valid position in s .
368 val rindex_from : string -> int -> char -> int
372 rindex_from s i c is the index of the last occurrence of c in s before
375 position i+1 .
376 Raises Not_found if c does not occur in s before position i+1 .
379 Raises Invalid_argument if i+1 is not a valid position in s .
382 val rindex_from_opt : string -> int -> char -> int option
386 rindex_from_opt s i c is the index of the last occurrence of c in s be‐
389 fore position i+1 (if any).
390 Since 4.05
393 Raises Invalid_argument if i+1 is not a valid position in s .
396 val index : string -> char -> int
400 index s c is String.index_from s 0 c .
403 val index_opt : string -> char -> int option
407 index_opt s c is String.index_from_opt s 0 c .
410 Since 4.05
413 val rindex : string -> char -> int
417 rindex s c is String.rindex_from s (length s - 1) c .
420 val rindex_opt : string -> char -> int option
424 rindex_opt s c is String.rindex_from_opt s (length s - 1) c .
427 Since 4.05
430 Converting
435 val to_seq : t -> char Seq.t
436 to_seq s is a sequence made of the string's characters in increasing
439 order. In "unsafe-string" mode, modifications of the string during it‐
440 eration will be reflected in the iterator.
441 Since 4.07
444 val to_seqi : t -> (int * char) Seq.t
448 to_seqi s is like String.to_seq but also tuples the corresponding in‐
451 dex.
452 Since 4.07
455 val of_seq : char Seq.t -> t
459 of_seq s is a string made of the sequence's characters.
462 Since 4.07
465 Deprecated functions
470 val create : int -> bytes
471 Deprecated. This is a deprecated alias of Bytes.create / BytesLa‐
473 bels.create .
474 create n returns a fresh byte sequence of length n . The sequence is
478 uninitialized and contains arbitrary bytes.
479 Raises Invalid_argument if n < 0 or n > Sys.max_string_length .
482 val set : bytes -> int -> char -> unit
486 Deprecated. This is a deprecated alias of Bytes.set / BytesLabels.set
488 .
489 set s n c modifies byte sequence s in place, replacing the byte at in‐
493 dex n with c . You can also write s.[n] <- c instead of set s n c .
494 Raises Invalid_argument if n is not a valid index in s .
497 val blit : string -> int -> bytes -> int -> int -> unit
501 blit src src_pos dst dst_pos len copies len bytes from the string src ,
504 starting at index src_pos , to byte sequence dst , starting at charac‐
505 ter number dst_pos .
506 Raises Invalid_argument if src_pos and len do not designate a valid
509 range of src , or if dst_pos and len do not designate a valid range of
510 dst .
511 val copy : string -> string
515 Deprecated. Because strings are immutable, it doesn't make much sense
517 to make identical copies of them.
518 Return a copy of the given string.
521 val fill : bytes -> int -> int -> char -> unit
525 Deprecated. This is a deprecated alias of Bytes.fill / BytesLa‐
527 bels.fill .
528 fill s pos len c modifies byte sequence s in place, replacing len bytes
532 by c , starting at pos .
533 Raises Invalid_argument if pos and len do not designate a valid sub‐
536 string of s .
537 val uppercase : string -> string
541 Deprecated. Functions operating on Latin-1 character set are depre‐
543 cated.
544 Return a copy of the argument, with all lowercase letters translated to
547 uppercase, including accented letters of the ISO Latin-1 (8859-1) char‐
548 acter set.
549 val lowercase : string -> string
553 Deprecated. Functions operating on Latin-1 character set are depre‐
555 cated.
556 Return a copy of the argument, with all uppercase letters translated to
559 lowercase, including accented letters of the ISO Latin-1 (8859-1) char‐
560 acter set.
561 val capitalize : string -> string
565 Deprecated. Functions operating on Latin-1 character set are depre‐
567 cated.
568 Return a copy of the argument, with the first character set to upper‐
571 case, using the ISO Latin-1 (8859-1) character set..
572 val uncapitalize : string -> string
576 Deprecated. Functions operating on Latin-1 character set are depre‐
578 cated.
579 Return a copy of the argument, with the first character set to lower‐
582 case, using the ISO Latin-1 (8859-1) character set.
583OCamldoc 2021-07-22 String(3)