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 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 val blit : string -> int -> bytes -> int -> int -> unit
580
581
582 blit src src_pos dst dst_pos len copies len bytes from the string src ,
583 starting at index src_pos , to byte sequence dst , starting at charac‐
584 ter number dst_pos .
585
586
587 Raises Invalid_argument if src_pos and len do not designate a valid
588 range of src , or if dst_pos and len do not designate a valid range of
589 dst .
590
591
592
593
594 Binary decoding of integers
595 The functions in this section binary decode integers from strings.
596
597 All following functions raise Invalid_argument if the characters needed
598 at index i to decode the integer are not available.
599
600 Little-endian (resp. big-endian) encoding means that least (resp. most)
601 significant bytes are stored first. Big-endian is also known as net‐
602 work byte order. Native-endian encoding is either little-endian or
603 big-endian depending on Sys.big_endian .
604
605 32-bit and 64-bit integers are represented by the int32 and int64
606 types, which can be interpreted either as signed or unsigned numbers.
607
608 8-bit and 16-bit integers are represented by the int type, which has
609 more bits than the binary encoding. These extra bits are sign-extended
610 (or zero-extended) for functions which decode 8-bit or 16-bit integers
611 and represented them with int values.
612
613 val get_uint8 : string -> int -> int
614
615
616 get_uint8 b i is b 's unsigned 8-bit integer starting at character in‐
617 dex i .
618
619
620 Since 4.13.0
621
622
623
624 val get_int8 : string -> int -> int
625
626
627 get_int8 b i is b 's signed 8-bit integer starting at character index i
628 .
629
630
631 Since 4.13.0
632
633
634
635 val get_uint16_ne : string -> int -> int
636
637
638 get_uint16_ne b i is b 's native-endian unsigned 16-bit integer start‐
639 ing at character index i .
640
641
642 Since 4.13.0
643
644
645
646 val get_uint16_be : string -> int -> int
647
648
649 get_uint16_be b i is b 's big-endian unsigned 16-bit integer starting
650 at character index i .
651
652
653 Since 4.13.0
654
655
656
657 val get_uint16_le : string -> int -> int
658
659
660 get_uint16_le b i is b 's little-endian unsigned 16-bit integer start‐
661 ing at character index i .
662
663
664 Since 4.13.0
665
666
667
668 val get_int16_ne : string -> int -> int
669
670
671 get_int16_ne b i is b 's native-endian signed 16-bit integer starting
672 at character index i .
673
674
675 Since 4.13.0
676
677
678
679 val get_int16_be : string -> int -> int
680
681
682 get_int16_be b i is b 's big-endian signed 16-bit integer starting at
683 character index i .
684
685
686 Since 4.13.0
687
688
689
690 val get_int16_le : string -> int -> int
691
692
693 get_int16_le b i is b 's little-endian signed 16-bit integer starting
694 at character index i .
695
696
697 Since 4.13.0
698
699
700
701 val get_int32_ne : string -> int -> int32
702
703
704 get_int32_ne b i is b 's native-endian 32-bit integer starting at char‐
705 acter index i .
706
707
708 Since 4.13.0
709
710
711
712 val hash : t -> int
713
714 An unseeded hash function for strings, with the same output value as
715 Hashtbl.hash . This function allows this module to be passed as argu‐
716 ment to the functor Hashtbl.Make .
717
718
719 Since 5.0.0
720
721
722
723 val seeded_hash : int -> t -> int
724
725 A seeded hash function for strings, with the same output value as
726 Hashtbl.seeded_hash . This function allows this module to be passed as
727 argument to the functor Hashtbl.MakeSeeded .
728
729
730 Since 5.0.0
731
732
733
734 val get_int32_be : string -> int -> int32
735
736
737 get_int32_be b i is b 's big-endian 32-bit integer starting at charac‐
738 ter index i .
739
740
741 Since 4.13.0
742
743
744
745 val get_int32_le : string -> int -> int32
746
747
748 get_int32_le b i is b 's little-endian 32-bit integer starting at char‐
749 acter index i .
750
751
752 Since 4.13.0
753
754
755
756 val get_int64_ne : string -> int -> int64
757
758
759 get_int64_ne b i is b 's native-endian 64-bit integer starting at char‐
760 acter index i .
761
762
763 Since 4.13.0
764
765
766
767 val get_int64_be : string -> int -> int64
768
769
770 get_int64_be b i is b 's big-endian 64-bit integer starting at charac‐
771 ter index i .
772
773
774 Since 4.13.0
775
776
777
778 val get_int64_le : string -> int -> int64
779
780
781 get_int64_le b i is b 's little-endian 64-bit integer starting at char‐
782 acter index i .
783
784
785 Since 4.13.0
786
787
788
789
790
791OCamldoc 2023-07-20 Stdlib.String(3)