1StringLabels(3) OCaml library StringLabels(3)
2
6 StringLabels - Strings.
7
9 Module StringLabels
10
12 Module StringLabels
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 -> f:(int -> char) -> string
89 init n ~f is a string of length n with index i holding the character f
92 i (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 : sep:string -> string list -> string
125 concat ~sep ss concatenates the list of strings ss , inserting the sep‐
128 arator 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.05.0
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 -> pos:int -> len:int -> string
189 sub s ~pos ~len is a string of length len , containing the substring of
192 s 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 : sep:char -> string -> string list
201 split_on_char ~sep s is the list of all (possibly empty) substrings of
204 s 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.05.0
219 Transforming
224 val map : f:(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 : f:(int -> char -> char) -> string -> string
236 mapi ~f s is like StringLabels.map but the index of the character is
239 also 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.05.0
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.05.0
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.05.0
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.05.0
317 Traversing
322 val iter : f:(char -> unit) -> string -> unit
323 iter ~f s applies function f in turn to all the characters of s . It
326 is equivalent to f s.[0]; f s.[1]; ...; f s.[length s - 1]; () .
327 val iteri : f:(int -> char -> unit) -> string -> unit
331 iteri is like StringLabels.iter , but the function is also given the
334 corresponding 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 StringLabels.to_seq but also tuples the corresponding
451 index.
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 : src:string -> src_pos:int -> dst:bytes -> dst_pos:int ->
501 len:int -> unit
502 blit ~src ~src_pos ~dst ~dst_pos ~len copies len bytes from the string
505 src , starting at index src_pos , to byte sequence dst , starting at
506 character number dst_pos .
507 Raises Invalid_argument if src_pos and len do not designate a valid
510 range of src , or if dst_pos and len do not designate a valid range of
511 dst .
512 val copy : string -> string
516 Deprecated. Because strings are immutable, it doesn't make much sense
518 to make identical copies of them.
519 Return a copy of the given string.
522 val fill : bytes -> pos:int -> len:int -> char -> unit
526 Deprecated. This is a deprecated alias of Bytes.fill / BytesLa‐
528 bels.fill .
529 fill s ~pos ~len c modifies byte sequence s in place, replacing len
533 bytes by c , starting at pos .
534 Raises Invalid_argument if pos and len do not designate a valid sub‐
537 string of s .
538 val uppercase : string -> string
542 Deprecated. Functions operating on Latin-1 character set are depre‐
544 cated.
545 Return a copy of the argument, with all lowercase letters translated to
548 uppercase, including accented letters of the ISO Latin-1 (8859-1) char‐
549 acter set.
550 val lowercase : string -> string
554 Deprecated. Functions operating on Latin-1 character set are depre‐
556 cated.
557 Return a copy of the argument, with all uppercase letters translated to
560 lowercase, including accented letters of the ISO Latin-1 (8859-1) char‐
561 acter set.
562 val capitalize : string -> string
566 Deprecated. Functions operating on Latin-1 character set are depre‐
568 cated.
569 Return a copy of the argument, with the first character set to upper‐
572 case, using the ISO Latin-1 (8859-1) character set..
573 val uncapitalize : string -> string
577 Deprecated. Functions operating on Latin-1 character set are depre‐
579 cated.
580 Return a copy of the argument, with the first character set to lower‐
583 case, using the ISO Latin-1 (8859-1) character set.
584OCamldoc 2021-07-22 StringLabels(3)