1Stdlib.String(3) OCaml library Stdlib.String(3)
2
3
4
6 Stdlib.String - no description
7
9 Module Stdlib.String
10
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 UTF decoding and validations
530 UTF-8
531 val get_utf_8_uchar : t -> int -> Uchar.utf_decode
532
533
534 get_utf_8_uchar b i decodes an UTF-8 character at index i in b .
535
536
537
538 val is_valid_utf_8 : t -> bool
539
540
541 is_valid_utf_8 b is true if and only if b contains valid UTF-8 data.
542
543
544
545
546 UTF-16BE
547 val get_utf_16be_uchar : t -> int -> Uchar.utf_decode
548
549
550 get_utf_16be_uchar b i decodes an UTF-16BE character at index i in b .
551
552
553
554 val is_valid_utf_16be : t -> bool
555
556
557 is_valid_utf_16be b is true if and only if b contains valid UTF-16BE
558 data.
559
560
561
562
563 UTF-16LE
564 val get_utf_16le_uchar : t -> int -> Uchar.utf_decode
565
566
567 get_utf_16le_uchar b i decodes an UTF-16LE character at index i in b .
568
569
570
571 val is_valid_utf_16le : t -> bool
572
573
574 is_valid_utf_16le b is true if and only if b contains valid UTF-16LE
575 data.
576
577
578
579
580 Deprecated functions
581 val create : int -> bytes
582
583 Deprecated. This is a deprecated alias of Bytes.create / BytesLa‐
584 bels.create .
585
586
587
588 create n returns a fresh byte sequence of length n . The sequence is
589 uninitialized and contains arbitrary bytes.
590
591
592 Raises Invalid_argument if n < 0 or n > Sys.max_string_length .
593
594
595
596 val set : bytes -> int -> char -> unit
597
598 Deprecated. This is a deprecated alias of Bytes.set / BytesLabels.set
599 .
600
601
602
603 set s n c modifies byte sequence s in place, replacing the byte at in‐
604 dex n with c . You can also write s.[n] <- c instead of set s n c .
605
606
607 Raises Invalid_argument if n is not a valid index in s .
608
609
610
611 val blit : string -> int -> bytes -> int -> int -> unit
612
613
614 blit src src_pos dst dst_pos len copies len bytes from the string src ,
615 starting at index src_pos , to byte sequence dst , starting at charac‐
616 ter number dst_pos .
617
618
619 Raises Invalid_argument if src_pos and len do not designate a valid
620 range of src , or if dst_pos and len do not designate a valid range of
621 dst .
622
623
624
625 val copy : string -> string
626
627 Deprecated. Because strings are immutable, it doesn't make much sense
628 to make identical copies of them.
629
630
631 Return a copy of the given string.
632
633
634
635 val fill : bytes -> int -> int -> char -> unit
636
637 Deprecated. This is a deprecated alias of Bytes.fill / BytesLa‐
638 bels.fill .
639
640
641
642 fill s pos len c modifies byte sequence s in place, replacing len bytes
643 by c , starting at pos .
644
645
646 Raises Invalid_argument if pos and len do not designate a valid sub‐
647 string of s .
648
649
650
651 val uppercase : string -> string
652
653 Deprecated. Functions operating on Latin-1 character set are depre‐
654 cated.
655
656
657 Return a copy of the argument, with all lowercase letters translated to
658 uppercase, including accented letters of the ISO Latin-1 (8859-1) char‐
659 acter set.
660
661
662
663 val lowercase : string -> string
664
665 Deprecated. Functions operating on Latin-1 character set are depre‐
666 cated.
667
668
669 Return a copy of the argument, with all uppercase letters translated to
670 lowercase, including accented letters of the ISO Latin-1 (8859-1) char‐
671 acter set.
672
673
674
675 val capitalize : string -> string
676
677 Deprecated. Functions operating on Latin-1 character set are depre‐
678 cated.
679
680
681 Return a copy of the argument, with the first character set to upper‐
682 case, using the ISO Latin-1 (8859-1) character set..
683
684
685
686 val uncapitalize : string -> string
687
688 Deprecated. Functions operating on Latin-1 character set are depre‐
689 cated.
690
691
692 Return a copy of the argument, with the first character set to lower‐
693 case, using the ISO Latin-1 (8859-1) character set.
694
695
696
697
698 Binary decoding of integers
699 The functions in this section binary decode integers from strings.
700
701 All following functions raise Invalid_argument if the characters needed
702 at index i to decode the integer are not available.
703
704 Little-endian (resp. big-endian) encoding means that least (resp. most)
705 significant bytes are stored first. Big-endian is also known as net‐
706 work byte order. Native-endian encoding is either little-endian or
707 big-endian depending on Sys.big_endian .
708
709 32-bit and 64-bit integers are represented by the int32 and int64
710 types, which can be interpreted either as signed or unsigned numbers.
711
712 8-bit and 16-bit integers are represented by the int type, which has
713 more bits than the binary encoding. These extra bits are sign-extended
714 (or zero-extended) for functions which decode 8-bit or 16-bit integers
715 and represented them with int values.
716
717 val get_uint8 : string -> int -> int
718
719
720 get_uint8 b i is b 's unsigned 8-bit integer starting at character in‐
721 dex i .
722
723
724 Since 4.13.0
725
726
727
728 val get_int8 : string -> int -> int
729
730
731 get_int8 b i is b 's signed 8-bit integer starting at character index i
732 .
733
734
735 Since 4.13.0
736
737
738
739 val get_uint16_ne : string -> int -> int
740
741
742 get_uint16_ne b i is b 's native-endian unsigned 16-bit integer start‐
743 ing at character index i .
744
745
746 Since 4.13.0
747
748
749
750 val get_uint16_be : string -> int -> int
751
752
753 get_uint16_be b i is b 's big-endian unsigned 16-bit integer starting
754 at character index i .
755
756
757 Since 4.13.0
758
759
760
761 val get_uint16_le : string -> int -> int
762
763
764 get_uint16_le b i is b 's little-endian unsigned 16-bit integer start‐
765 ing at character index i .
766
767
768 Since 4.13.0
769
770
771
772 val get_int16_ne : string -> int -> int
773
774
775 get_int16_ne b i is b 's native-endian signed 16-bit integer starting
776 at character index i .
777
778
779 Since 4.13.0
780
781
782
783 val get_int16_be : string -> int -> int
784
785
786 get_int16_be b i is b 's big-endian signed 16-bit integer starting at
787 character index i .
788
789
790 Since 4.13.0
791
792
793
794 val get_int16_le : string -> int -> int
795
796
797 get_int16_le b i is b 's little-endian signed 16-bit integer starting
798 at character index i .
799
800
801 Since 4.13.0
802
803
804
805 val get_int32_ne : string -> int -> int32
806
807
808 get_int32_ne b i is b 's native-endian 32-bit integer starting at char‐
809 acter index i .
810
811
812 Since 4.13.0
813
814
815
816 val get_int32_be : string -> int -> int32
817
818
819 get_int32_be b i is b 's big-endian 32-bit integer starting at charac‐
820 ter index i .
821
822
823 Since 4.13.0
824
825
826
827 val get_int32_le : string -> int -> int32
828
829
830 get_int32_le b i is b 's little-endian 32-bit integer starting at char‐
831 acter index i .
832
833
834 Since 4.13.0
835
836
837
838 val get_int64_ne : string -> int -> int64
839
840
841 get_int64_ne b i is b 's native-endian 64-bit integer starting at char‐
842 acter index i .
843
844
845 Since 4.13.0
846
847
848
849 val get_int64_be : string -> int -> int64
850
851
852 get_int64_be b i is b 's big-endian 64-bit integer starting at charac‐
853 ter index i .
854
855
856 Since 4.13.0
857
858
859
860 val get_int64_le : string -> int -> int64
861
862
863 get_int64_le b i is b 's little-endian 64-bit integer starting at char‐
864 acter index i .
865
866
867 Since 4.13.0
868
869
870
871
872
873OCamldoc 2022-07-22 Stdlib.String(3)