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       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
42       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
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       Raise Invalid_argument if n not a valid index in s .
64
65
66
67       val set : bytes -> int -> char -> unit
68
69       Deprecated.  This is a deprecated alias of Bytes.set .
70
71
72
73
74       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
78       Raise Invalid_argument if n is not a valid index in s .
79
80
81
82       val create : int -> bytes
83
84       Deprecated.  This is a deprecated alias of Bytes.create .
85
86
87
88
89       String.create n returns a fresh  byte  sequence  of  length  n  .   The
90       sequence is uninitialized and contains arbitrary bytes.
91
92       Raise Invalid_argument if n < 0 or n > Sys.max_string_length .
93
94
95
96       val make : int -> char -> string
97
98
99       String.make  n  c  returns a fresh string of length n , filled with the
100       character c .
101
102       Raise Invalid_argument if n < 0 or n > Sys.max_string_length .
103
104
105
106       val init : int -> (int -> char) -> string
107
108
109       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
112       Raise Invalid_argument if n < 0 or n > Sys.max_string_length .
113
114
115       Since 4.02.0
116
117
118
119       val copy : string -> string
120
121       Deprecated.   Because strings are immutable, it doesn't make much sense
122       to make identical copies of them.
123
124
125       Return a copy of the given string.
126
127
128
129       val sub : string -> int -> int -> string
130
131
132       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
136       Raise Invalid_argument if start and len do not designate a  valid  sub‐
137       string of s .
138
139
140
141       val fill : bytes -> int -> int -> char -> unit
142
143       Deprecated.  This is a deprecated alias of Bytes.fill .
144
145
146
147
148       String.fill  s start len c modifies byte sequence s in place, replacing
149       len bytes with c , starting at start .
150
151       Raise Invalid_argument if start and len do not designate a valid  range
152       of s .
153
154
155
156       val blit : string -> int -> bytes -> int -> int -> unit
157
158       Same as Bytes.blit_string .
159
160
161
162       val concat : string -> string list -> string
163
164
165       String.concat  sep  sl  concatenates the list of strings sl , inserting
166       the separator string sep between each.
167
168       Raise   Invalid_argument    if    the    result    is    longer    than
169       Sys.max_string_length bytes.
170
171
172
173       val iter : (char -> unit) -> string -> unit
174
175
176       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
180
181
182       val iteri : (int -> char -> unit) -> string -> unit
183
184       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
188
189       Since 4.00.0
190
191
192
193       val map : (char -> char) -> string -> string
194
195
196       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
200
201       Since 4.00.0
202
203
204
205       val mapi : (int -> char -> char) -> string -> string
206
207
208       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
212
213       Since 4.02.0
214
215
216
217       val trim : string -> string
218
219       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
224
225       Since 4.00.0
226
227
228
229       val escaped : string -> string
230
231       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
236       If  there  is no special character in the argument that needs escaping,
237       return the original string itself, not a copy.
238
239       Raise   Invalid_argument    if    the    result    is    longer    than
240       Sys.max_string_length bytes.
241
242       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
246
247
248       val index : string -> char -> int
249
250
251       String.index s c returns the index of the first occurrence of character
252       c in string s .
253
254       Raise Not_found if c does not occur in s .
255
256
257
258       val index_opt : string -> char -> int option
259
260
261       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
264
265       Since 4.05
266
267
268
269       val rindex : string -> char -> int
270
271
272       String.rindex s c returns the index of the last occurrence of character
273       c in string s .
274
275       Raise Not_found if c does not occur in s .
276
277
278
279       val rindex_opt : string -> char -> int option
280
281
282       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
285
286       Since 4.05
287
288
289
290       val index_from : string -> int -> char -> int
291
292
293       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
297       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
300
301
302       val index_from_opt : string -> int -> char -> int option
303
304
305       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
309
310       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
313
314       Since 4.05
315
316
317
318       val rindex_from : string -> int -> char -> int
319
320
321       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
325       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
328
329
330       val rindex_from_opt : string -> int -> char -> int option
331
332
333       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
337
338       String.rindex_opt  s  c  is  equivalent  to  String.rindex_from_opt   s
339       (String.length s - 1) c .
340
341       Raise Invalid_argument if i+1 is not a valid position in s .
342
343
344       Since 4.05
345
346
347
348       val contains : string -> char -> bool
349
350
351       String.contains s c tests if character c appears in the string s .
352
353
354
355       val contains_from : string -> int -> char -> bool
356
357
358       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
362       Raise Invalid_argument if start is not a valid position in s .
363
364
365
366       val rcontains_from : string -> int -> char -> bool
367
368
369       String.rcontains_from s stop c tests if character c appears in s before
370       position stop+1 .
371
372       Raise Invalid_argument if stop < 0 or stop+1 is not a valid position in
373       s .
374
375
376
377       val uppercase : string -> string
378
379       Deprecated.   Functions  operating  on Latin-1 character set are depre‐
380       cated.
381
382
383       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
387
388
389       val lowercase : string -> string
390
391       Deprecated.  Functions operating on Latin-1 character  set  are  depre‐
392       cated.
393
394
395       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
399
400
401       val capitalize : string -> string
402
403       Deprecated.   Functions  operating  on Latin-1 character set are depre‐
404       cated.
405
406
407       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
410
411
412       val uncapitalize : string -> string
413
414       Deprecated.   Functions  operating  on Latin-1 character set are depre‐
415       cated.
416
417
418       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
421
422
423       val uppercase_ascii : string -> string
424
425       Return a copy of the argument, with all lowercase letters translated to
426       uppercase, using the US-ASCII character set.
427
428
429       Since 4.03.0
430
431
432
433       val lowercase_ascii : string -> string
434
435       Return a copy of the argument, with all uppercase letters translated to
436       lowercase, using the US-ASCII character set.
437
438
439       Since 4.03.0
440
441
442
443       val capitalize_ascii : string -> string
444
445       Return  a  copy of the argument, with the first character set to upper‐
446       case, using the US-ASCII character set.
447
448
449       Since 4.03.0
450
451
452
453       val uncapitalize_ascii : string -> string
454
455       Return a copy of the argument, with the first character set  to  lower‐
456       case, using the US-ASCII character set.
457
458
459       Since 4.03.0
460
461
462       type t = string
463
464
465       An alias for the type of strings.
466
467
468
469       val compare : t -> t -> int
470
471       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
476
477
478       val equal : t -> t -> bool
479
480       The equal function for strings.
481
482
483       Since 4.03.0
484
485
486
487       val split_on_char : char -> string -> string list
488
489
490       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
493       The function's output is specified by the following invariants:
494
495
496       -The list is not empty.
497
498       -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
502       -No string in the result contains the sep character.
503
504
505
506       Since 4.04.0
507
508
509
510
511       === Iterators ===
512
513
514       val to_seq : t -> char Seq.t
515
516       Iterate  on the string, in increasing index order. Modifications of the
517       string during iteration will be reflected in the iterator.
518
519
520       Since 4.07
521
522
523
524       val to_seqi : t -> (int * char) Seq.t
525
526       Iterate on the string, in  increasing  order,  yielding  indices  along
527       chars
528
529
530       Since 4.07
531
532
533
534       val of_seq : char Seq.t -> t
535
536       Create a string from the generator
537
538
539       Since 4.07
540
541
542
543
544
545OCamldoc                          2018-07-14                         String(3)
Impressum