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

NAME

6       Stdlib.String - no description
7

Module

9       Module   Stdlib.String
10

Documentation

12       Module String
13        : (module Stdlib__String)
14
15
16
17
18
19
20
21
22
23   Strings
24       type t = string
25
26
27       The type for strings.
28
29
30
31       val make : int -> char -> string
32
33
34       make  n c is a string of length n with each index holding the character
35       c .
36
37
38       Raises Invalid_argument if n < 0 or n > Sys.max_string_length .
39
40
41
42       val init : int -> (int -> char) -> string
43
44
45       init n f is a string of length n with index i holding the character f i
46       (called in increasing index order).
47
48
49       Since 4.02.0
50
51
52       Raises Invalid_argument if n < 0 or n > Sys.max_string_length .
53
54
55
56       val empty : string
57
58       The empty string.
59
60
61       Since 4.13.0
62
63
64
65       val of_bytes : bytes -> string
66
67       Return  a new string that contains the same bytes as the given byte se‐
68       quence.
69
70
71       Since 4.13.0
72
73
74
75       val to_bytes : string -> bytes
76
77       Return a new byte sequence that contains the same bytes  as  the  given
78       string.
79
80
81       Since 4.13.0
82
83
84
85       val length : string -> int
86
87
88       length s is the length (number of bytes/characters) of s .
89
90
91
92       val get : string -> int -> char
93
94
95       get  s i is the character at index i in s . This is the same as writing
96       s.[i] .
97
98
99       Raises Invalid_argument if i not an index of s .
100
101
102
103
104   Concatenating
105       Note. The (^) binary operator concatenates two strings.
106
107       val concat : string -> string list -> string
108
109
110       concat sep ss concatenates the list of strings ss , inserting the sepa‐
111       rator string sep between each.
112
113
114       Raises    Invalid_argument    if    the    result    is   longer   than
115       Sys.max_string_length bytes.
116
117
118
119       val cat : string -> string -> string
120
121
122       cat s1 s2 concatenates s1 and s2 ( s1 ^ s2 ).
123
124
125       Since 4.13.0
126
127
128       Raises  Invalid_argument  if   the   result   is   longer   then   than
129       Sys.max_string_length bytes.
130
131
132
133
134   Predicates and comparisons
135       val equal : t -> t -> bool
136
137
138       equal s0 s1 is true if and only if s0 and s1 are character-wise equal.
139
140
141       Since 4.03.0 (4.05.0 in StringLabels)
142
143
144
145       val compare : t -> t -> int
146
147
148       compare  s0  s1  sorts s0 and s1 in lexicographical order.  compare be‐
149       haves like compare on strings but may be more efficient.
150
151
152
153       val starts_with : prefix:string -> string -> bool
154
155
156       starts_with ~ prefix s is true if and only if s starts with prefix .
157
158
159       Since 4.13.0
160
161
162
163       val ends_with : suffix:string -> string -> bool
164
165
166       ends_with suffix s is true if and only if s ends with suffix .
167
168
169       Since 4.13.0
170
171
172
173       val contains_from : string -> int -> char -> bool
174
175
176       contains_from s start c is true if and only if c appears in s after po‐
177       sition start .
178
179
180       Raises Invalid_argument if start is not a valid position in s .
181
182
183
184       val rcontains_from : string -> int -> char -> bool
185
186
187       rcontains_from  s  stop  c is true if and only if c appears in s before
188       position stop+1 .
189
190
191       Raises Invalid_argument if stop < 0 or stop+1 is not a  valid  position
192       in s .
193
194
195
196       val contains : string -> char -> bool
197
198
199       contains s c is String.contains_from s 0 c .
200
201
202
203
204   Extracting substrings
205       val sub : string -> int -> int -> string
206
207
208       sub s pos len is a string of length len , containing the substring of s
209       that starts at position pos and has length len .
210
211
212       Raises Invalid_argument if pos and len do not designate  a  valid  sub‐
213       string of s .
214
215
216
217       val split_on_char : char -> string -> string list
218
219
220       split_on_char sep s is the list of all (possibly empty) substrings of s
221       that are delimited by the character sep .
222
223       The function's result is specified by the following invariants:
224
225       -The list is not empty.
226
227       -Concatenating its elements using sep as a separator returns  a  string
228       equal to the input ( concat (make 1 sep)
229             (split_on_char sep s) = s ).
230
231       -No string in the result contains the sep character.
232
233
234
235       Since 4.04.0 (4.05.0 in StringLabels)
236
237
238
239
240   Transforming
241       val map : (char -> char) -> string -> string
242
243
244       map  f  s is the string resulting from applying f to all the characters
245       of s in increasing order.
246
247
248       Since 4.00.0
249
250
251
252       val mapi : (int -> char -> char) -> string -> string
253
254
255       mapi f s is like String.map but the index  of  the  character  is  also
256       passed to f .
257
258
259       Since 4.02.0
260
261
262
263       val fold_left : ('a -> char -> 'a) -> 'a -> string -> 'a
264
265
266       fold_left  f  x  s computes f (... (f (f x s.[0]) s.[1]) ...) s.[n-1] ,
267       where n is the length of the string s .
268
269
270       Since 4.13.0
271
272
273
274       val fold_right : (char -> 'a -> 'a) -> string -> 'a -> 'a
275
276
277       fold_right f s x computes f s.[0] (f s.[1] ( ... (f s.[n-1] x) ...))  ,
278       where n is the length of the string s .
279
280
281       Since 4.13.0
282
283
284
285       val for_all : (char -> bool) -> string -> bool
286
287
288       for_all p s checks if all characters in s satisfy the predicate p .
289
290
291       Since 4.13.0
292
293
294
295       val exists : (char -> bool) -> string -> bool
296
297
298       exists  p  s checks if at least one character of s satisfies the predi‐
299       cate p .
300
301
302       Since 4.13.0
303
304
305
306       val trim : string -> string
307
308
309       trim s is s without leading and trailing whitespace. Whitespace charac‐
310       ters are: ' ' , '\x0C' (form feed), '\n' , '\r' , and '\t' .
311
312
313       Since 4.00.0
314
315
316
317       val escaped : string -> string
318
319
320       escaped s is s with special characters represented by escape sequences,
321       following the lexical conventions of OCaml.
322
323       All characters outside the US-ASCII printable range [0x20;0x7E] are es‐
324       caped, as well as backslash (0x2F) and double-quote (0x22).
325
326       The  function  Scanf.unescaped  is  a  left  inverse  of escaped , i.e.
327       Scanf.unescaped (escaped s) = s for any  string  s  (unless  escaped  s
328       fails).
329
330
331       Raises    Invalid_argument    if    the    result    is   longer   than
332       Sys.max_string_length bytes.
333
334
335
336       val uppercase_ascii : string -> string
337
338
339       uppercase_ascii s is s with all lowercase letters translated to  upper‐
340       case, using the US-ASCII character set.
341
342
343       Since 4.03.0 (4.05.0 in StringLabels)
344
345
346
347       val lowercase_ascii : string -> string
348
349
350       lowercase_ascii  s is s with all uppercase letters translated to lower‐
351       case, using the US-ASCII character set.
352
353
354       Since 4.03.0 (4.05.0 in StringLabels)
355
356
357
358       val capitalize_ascii : string -> string
359
360
361       capitalize_ascii s is s with the first character set to uppercase,  us‐
362       ing the US-ASCII character set.
363
364
365       Since 4.03.0 (4.05.0 in StringLabels)
366
367
368
369       val uncapitalize_ascii : string -> string
370
371
372       uncapitalize_ascii  s  is  s with the first character set to lowercase,
373       using the US-ASCII character set.
374
375
376       Since 4.03.0 (4.05.0 in StringLabels)
377
378
379
380
381   Traversing
382       val iter : (char -> unit) -> string -> unit
383
384
385       iter f s applies function f in turn to all the characters of s .  It is
386       equivalent to f s.[0]; f s.[1]; ...; f s.[length s - 1]; () .
387
388
389
390       val iteri : (int -> char -> unit) -> string -> unit
391
392
393       iteri  is  like String.iter , but the function is also given the corre‐
394       sponding character index.
395
396
397       Since 4.00.0
398
399
400
401
402   Searching
403       val index_from : string -> int -> char -> int
404
405
406       index_from s i c is the index of the first occurrence of c in  s  after
407       position i .
408
409
410       Raises Not_found if c does not occur in s after position i .
411
412
413       Raises Invalid_argument if i is not a valid position in s .
414
415
416
417       val index_from_opt : string -> int -> char -> int option
418
419
420       index_from_opt s i c is the index of the first occurrence of c in s af‐
421       ter position i (if any).
422
423
424       Since 4.05
425
426
427       Raises Invalid_argument if i is not a valid position in s .
428
429
430
431       val rindex_from : string -> int -> char -> int
432
433
434       rindex_from s i c is the index of the last occurrence of c in s  before
435       position i+1 .
436
437
438       Raises Not_found if c does not occur in s before position i+1 .
439
440
441       Raises Invalid_argument if i+1 is not a valid position in s .
442
443
444
445       val rindex_from_opt : string -> int -> char -> int option
446
447
448       rindex_from_opt s i c is the index of the last occurrence of c in s be‐
449       fore position i+1 (if any).
450
451
452       Since 4.05
453
454
455       Raises Invalid_argument if i+1 is not a valid position in s .
456
457
458
459       val index : string -> char -> int
460
461
462       index s c is String.index_from s 0 c .
463
464
465
466       val index_opt : string -> char -> int option
467
468
469       index_opt s c is String.index_from_opt s 0 c .
470
471
472       Since 4.05
473
474
475
476       val rindex : string -> char -> int
477
478
479       rindex s c is String.rindex_from s (length s - 1) c .
480
481
482
483       val rindex_opt : string -> char -> int option
484
485
486       rindex_opt s c is String.rindex_from_opt s (length s - 1) c .
487
488
489       Since 4.05
490
491
492
493
494   Strings and Sequences
495       val to_seq : t -> char Seq.t
496
497
498       to_seq s is a sequence made of the string's  characters  in  increasing
499       order.  In "unsafe-string" mode, modifications of the string during it‐
500       eration will be reflected in the sequence.
501
502
503       Since 4.07
504
505
506
507       val to_seqi : t -> (int * char) Seq.t
508
509
510       to_seqi s is like String.to_seq but also tuples the  corresponding  in‐
511       dex.
512
513
514       Since 4.07
515
516
517
518       val of_seq : char Seq.t -> t
519
520
521       of_seq s is a string made of the sequence's characters.
522
523
524       Since 4.07
525
526
527
528
529   Deprecated functions
530       val create : int -> bytes
531
532       Deprecated.   This  is  a  deprecated  alias of Bytes.create / BytesLa‐
533       bels.create .
534
535
536
537       create n returns a fresh byte sequence of length n .  The  sequence  is
538       uninitialized and contains arbitrary bytes.
539
540
541       Raises Invalid_argument if n < 0 or n > Sys.max_string_length .
542
543
544
545       val set : bytes -> int -> char -> unit
546
547       Deprecated.   This is a deprecated alias of Bytes.set / BytesLabels.set
548       .
549
550
551
552       set s n c modifies byte sequence s in place, replacing the byte at  in‐
553       dex n with c .  You can also write s.[n] <- c instead of set s n c .
554
555
556       Raises Invalid_argument if n is not a valid index in s .
557
558
559
560       val blit : string -> int -> bytes -> int -> int -> unit
561
562
563       blit src src_pos dst dst_pos len copies len bytes from the string src ,
564       starting at index src_pos , to byte sequence dst , starting at  charac‐
565       ter number dst_pos .
566
567
568       Raises  Invalid_argument  if  src_pos  and len do not designate a valid
569       range of src , or if dst_pos and len do not designate a valid range  of
570       dst .
571
572
573
574       val copy : string -> string
575
576       Deprecated.   Because strings are immutable, it doesn't make much sense
577       to make identical copies of them.
578
579
580       Return a copy of the given string.
581
582
583
584       val fill : bytes -> int -> int -> char -> unit
585
586       Deprecated.  This is  a  deprecated  alias  of  Bytes.fill  /  BytesLa‐
587       bels.fill .
588
589
590
591       fill s pos len c modifies byte sequence s in place, replacing len bytes
592       by c , starting at pos .
593
594
595       Raises Invalid_argument if pos and len do not designate  a  valid  sub‐
596       string of s .
597
598
599
600       val uppercase : string -> string
601
602       Deprecated.   Functions  operating  on Latin-1 character set are depre‐
603       cated.
604
605
606       Return a copy of the argument, with all lowercase letters translated to
607       uppercase, including accented letters of the ISO Latin-1 (8859-1) char‐
608       acter set.
609
610
611
612       val lowercase : string -> string
613
614       Deprecated.  Functions operating on Latin-1 character  set  are  depre‐
615       cated.
616
617
618       Return a copy of the argument, with all uppercase letters translated to
619       lowercase, including accented letters of the ISO Latin-1 (8859-1) char‐
620       acter set.
621
622
623
624       val capitalize : string -> string
625
626       Deprecated.   Functions  operating  on Latin-1 character set are depre‐
627       cated.
628
629
630       Return a copy of the argument, with the first character set  to  upper‐
631       case, using the ISO Latin-1 (8859-1) character set..
632
633
634
635       val uncapitalize : string -> string
636
637       Deprecated.   Functions  operating  on Latin-1 character set are depre‐
638       cated.
639
640
641       Return a copy of the argument, with the first character set  to  lower‐
642       case, using the ISO Latin-1 (8859-1) character set.
643
644
645
646
647   Binary decoding of integers
648       The functions in this section binary decode integers from strings.
649
650       All following functions raise Invalid_argument if the characters needed
651       at index i to decode the integer are not available.
652
653       Little-endian (resp. big-endian) encoding means that least (resp. most)
654       significant  bytes  are stored first.  Big-endian is also known as net‐
655       work byte order.  Native-endian encoding  is  either  little-endian  or
656       big-endian depending on Sys.big_endian .
657
658       32-bit  and  64-bit  integers  are  represented  by the int32 and int64
659       types, which can be interpreted either as signed or unsigned numbers.
660
661       8-bit and 16-bit integers are represented by the int  type,  which  has
662       more bits than the binary encoding.  These extra bits are sign-extended
663       (or zero-extended) for functions which decode 8-bit or 16-bit  integers
664       and represented them with int values.
665
666       val get_uint8 : string -> int -> int
667
668
669       get_uint8  b i is b 's unsigned 8-bit integer starting at character in‐
670       dex i .
671
672
673       Since 4.13.0
674
675
676
677       val get_int8 : string -> int -> int
678
679
680       get_int8 b i is b 's signed 8-bit integer starting at character index i
681       .
682
683
684       Since 4.13.0
685
686
687
688       val get_uint16_ne : string -> int -> int
689
690
691       get_uint16_ne  b i is b 's native-endian unsigned 16-bit integer start‐
692       ing at character index i .
693
694
695       Since 4.13.0
696
697
698
699       val get_uint16_be : string -> int -> int
700
701
702       get_uint16_be b i is b 's big-endian unsigned 16-bit  integer  starting
703       at character index i .
704
705
706       Since 4.13.0
707
708
709
710       val get_uint16_le : string -> int -> int
711
712
713       get_uint16_le  b i is b 's little-endian unsigned 16-bit integer start‐
714       ing at character index i .
715
716
717       Since 4.13.0
718
719
720
721       val get_int16_ne : string -> int -> int
722
723
724       get_int16_ne b i is b 's native-endian signed 16-bit  integer  starting
725       at character index i .
726
727
728       Since 4.13.0
729
730
731
732       val get_int16_be : string -> int -> int
733
734
735       get_int16_be  b  i is b 's big-endian signed 16-bit integer starting at
736       character index i .
737
738
739       Since 4.13.0
740
741
742
743       val get_int16_le : string -> int -> int
744
745
746       get_int16_le b i is b 's little-endian signed 16-bit  integer  starting
747       at character index i .
748
749
750       Since 4.13.0
751
752
753
754       val get_int32_ne : string -> int -> int32
755
756
757       get_int32_ne b i is b 's native-endian 32-bit integer starting at char‐
758       acter index i .
759
760
761       Since 4.13.0
762
763
764
765       val get_int32_be : string -> int -> int32
766
767
768       get_int32_be b i is b 's big-endian 32-bit integer starting at  charac‐
769       ter index i .
770
771
772       Since 4.13.0
773
774
775
776       val get_int32_le : string -> int -> int32
777
778
779       get_int32_le b i is b 's little-endian 32-bit integer starting at char‐
780       acter index i .
781
782
783       Since 4.13.0
784
785
786
787       val get_int64_ne : string -> int -> int64
788
789
790       get_int64_ne b i is b 's native-endian 64-bit integer starting at char‐
791       acter index i .
792
793
794       Since 4.13.0
795
796
797
798       val get_int64_be : string -> int -> int64
799
800
801       get_int64_be  b i is b 's big-endian 64-bit integer starting at charac‐
802       ter index i .
803
804
805       Since 4.13.0
806
807
808
809       val get_int64_le : string -> int -> int64
810
811
812       get_int64_le b i is b 's little-endian 64-bit integer starting at char‐
813       acter index i .
814
815
816       Since 4.13.0
817
818
819
820
821
822OCamldoc                          2022-02-04                  Stdlib.String(3)
Impressum