1String(3)                        OCaml library                       String(3)
2
3
4

NAME

6       String - String operations.
7

Module

9       Module   String
10

Documentation

12       Module String
13        : sig end
14
15
16       String operations.
17
18       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
22       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
30       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
33       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
41       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
46
47
48
49
50
51       val length : string -> int
52
53       Return the length (number of characters) of the given string.
54
55
56
57       val get : string -> int -> char
58
59
60       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
63
64       Raises Invalid_argument if n not a valid index in s .
65
66
67
68       val set : bytes -> int -> char -> unit
69
70       Deprecated.  This is a deprecated alias of Bytes.set .
71
72
73
74
75       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
79
80       Raises Invalid_argument if n is not a valid index in s .
81
82
83
84       val create : int -> bytes
85
86       Deprecated.  This is a deprecated alias of Bytes.create .
87
88
89
90
91       String.create n returns a fresh byte sequence of length n  .   The  se‐
92       quence is uninitialized and contains arbitrary bytes.
93
94
95       Raises Invalid_argument if n < 0 or n > Sys.max_string_length .
96
97
98
99       val make : int -> char -> string
100
101
102       String.make  n  c  returns a fresh string of length n , filled with the
103       character c .
104
105
106       Raises Invalid_argument if n < 0 or n > Sys.max_string_length .
107
108
109
110       val init : int -> (int -> char) -> string
111
112
113       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
116
117       Since 4.02.0
118
119
120       Raises Invalid_argument if n < 0 or n > Sys.max_string_length .
121
122
123
124       val copy : string -> string
125
126       Deprecated.   Because strings are immutable, it doesn't make much sense
127       to make identical copies of them.
128
129
130       Return a copy of the given string.
131
132
133
134       val sub : string -> int -> int -> string
135
136
137       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
141
142       Raises Invalid_argument if start and len do not designate a valid  sub‐
143       string of s .
144
145
146
147       val fill : bytes -> int -> int -> char -> unit
148
149       Deprecated.  This is a deprecated alias of Bytes.fill .
150
151
152
153
154       String.fill  s start len c modifies byte sequence s in place, replacing
155       len bytes with c , starting at start .
156
157
158       Raises Invalid_argument if start and len do not designate a valid range
159       of s .
160
161
162
163       val blit : string -> int -> bytes -> int -> int -> unit
164
165       Same as Bytes.blit_string .
166
167
168
169       val concat : string -> string list -> string
170
171
172       String.concat  sep  sl  concatenates the list of strings sl , inserting
173       the separator string sep between each.
174
175
176       Raises   Invalid_argument   if    the    result    is    longer    than
177       Sys.max_string_length bytes.
178
179
180
181       val iter : (char -> unit) -> string -> unit
182
183
184       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
188
189
190       val iteri : (int -> char -> unit) -> string -> unit
191
192       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
196
197       Since 4.00.0
198
199
200
201       val map : (char -> char) -> string -> string
202
203
204       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
208
209       Since 4.00.0
210
211
212
213       val mapi : (int -> char -> char) -> string -> string
214
215
216       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
220
221       Since 4.02.0
222
223
224
225       val trim : string -> string
226
227       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
232
233       Since 4.00.0
234
235
236
237       val escaped : string -> string
238
239       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
244       If  there  is no special character in the argument that needs escaping,
245       return the original string itself, not a copy.
246
247
248       Raises   Invalid_argument   if    the    result    is    longer    than
249       Sys.max_string_length bytes.
250
251       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
255
256
257       val index : string -> char -> int
258
259
260       String.index s c returns the index of the first occurrence of character
261       c in string s .
262
263
264       Raises Not_found if c does not occur in s .
265
266
267
268       val index_opt : string -> char -> int option
269
270
271       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
274
275       Since 4.05
276
277
278
279       val rindex : string -> char -> int
280
281
282       String.rindex s c returns the index of the last occurrence of character
283       c in string s .
284
285
286       Raises Not_found if c does not occur in s .
287
288
289
290       val rindex_opt : string -> char -> int option
291
292
293       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
296
297       Since 4.05
298
299
300
301       val index_from : string -> int -> char -> int
302
303
304       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
308
309       Raises Invalid_argument if i is not a valid position in s .
310
311
312       Raises Not_found if c does not occur in s after position i .
313
314
315
316       val index_from_opt : string -> int -> char -> int option
317
318
319       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
323
324       String.index_opt s c is equivalent to String.index_from_opt s 0 c .
325
326
327       Since 4.05
328
329
330       Raises Invalid_argument if i is not a valid position in s .
331
332
333
334       val rindex_from : string -> int -> char -> int
335
336
337       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
341
342       Raises Invalid_argument if i+1 is not a valid position in s .
343
344
345       Raises Not_found if c does not occur in s before position i+1 .
346
347
348
349       val rindex_from_opt : string -> int -> char -> int option
350
351
352       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
356
357       String.rindex_opt   s  c  is  equivalent  to  String.rindex_from_opt  s
358       (String.length s - 1) c .
359
360
361       Since 4.05
362
363
364       Raises Invalid_argument if i+1 is not a valid position in s .
365
366
367
368       val contains : string -> char -> bool
369
370
371       String.contains s c tests if character c appears in the string s .
372
373
374
375       val contains_from : string -> int -> char -> bool
376
377
378       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
382
383       Raises Invalid_argument if start is not a valid position in s .
384
385
386
387       val rcontains_from : string -> int -> char -> bool
388
389
390       String.rcontains_from s stop c tests if character c appears in s before
391       position stop+1 .
392
393
394       Raises  Invalid_argument  if stop < 0 or stop+1 is not a valid position
395       in s .
396
397
398
399       val uppercase : string -> string
400
401       Deprecated.  Functions operating on Latin-1 character  set  are  depre‐
402       cated.
403
404
405       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
409
410
411       val lowercase : string -> string
412
413       Deprecated.   Functions  operating  on Latin-1 character set are depre‐
414       cated.
415
416
417       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
421
422
423       val capitalize : string -> string
424
425       Deprecated.  Functions operating on Latin-1 character  set  are  depre‐
426       cated.
427
428
429       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
432
433
434       val uncapitalize : string -> string
435
436       Deprecated.  Functions operating on Latin-1 character  set  are  depre‐
437       cated.
438
439
440       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
443
444
445       val uppercase_ascii : string -> string
446
447       Return a copy of the argument, with all lowercase letters translated to
448       uppercase, using the US-ASCII character set.
449
450
451       Since 4.03.0
452
453
454
455       val lowercase_ascii : string -> string
456
457       Return a copy of the argument, with all uppercase letters translated to
458       lowercase, using the US-ASCII character set.
459
460
461       Since 4.03.0
462
463
464
465       val capitalize_ascii : string -> string
466
467       Return a copy of the argument, with the first character set  to  upper‐
468       case, using the US-ASCII character set.
469
470
471       Since 4.03.0
472
473
474
475       val uncapitalize_ascii : string -> string
476
477       Return  a  copy of the argument, with the first character set to lower‐
478       case, using the US-ASCII character set.
479
480
481       Since 4.03.0
482
483
484       type t = string
485
486
487       An alias for the type of strings.
488
489
490
491       val compare : t -> t -> int
492
493       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
498
499
500       val equal : t -> t -> bool
501
502       The equal function for strings.
503
504
505       Since 4.03.0
506
507
508
509       val split_on_char : char -> string -> string list
510
511
512       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
515       The function's output is specified by the following invariants:
516
517
518       -The list is not empty.
519
520       -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
524       -No string in the result contains the sep character.
525
526
527
528       Since 4.04.0
529
530
531
532
533   Iterators
534       val to_seq : t -> char Seq.t
535
536       Iterate  on the string, in increasing index order. Modifications of the
537       string during iteration will be reflected in the iterator.
538
539
540       Since 4.07
541
542
543
544       val to_seqi : t -> (int * char) Seq.t
545
546       Iterate on the string, in  increasing  order,  yielding  indices  along
547       chars
548
549
550       Since 4.07
551
552
553
554       val of_seq : char Seq.t -> t
555
556       Create a string from the generator
557
558
559       Since 4.07
560
561
562
563
564
565OCamldoc                          2021-01-26                         String(3)
Impressum