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

NAME

6       StringLabels - Strings.
7

Module

9       Module   StringLabels
10

Documentation

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