1StringLabels(3) OCaml library StringLabels(3)
2
6 StringLabels - Strings.
7
9 Module StringLabels
10
12 Module StringLabels
13 : sig end
14 Strings.
17 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 The semantics of string functions is defined in terms of indices and
23 positions. These are depicted and described as follows.
24 positions 0 1 2 3 4 n-1 n +---+---+---+---+ +-----+
26 indices | 0 | 1 | 2 | 3 | ... | n-1 | +---+---+---+---+ +-----+
27 -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 -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 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 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 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 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 The labeled version of this module can be used as described in the Std‐
61 Labels module.
62 Strings
70 type t = string
71 The type for strings.
74 val make : int -> char -> string
78 make n c is a string of length n with each index holding the character
81 c .
82 Raises Invalid_argument if n < 0 or n > Sys.max_string_length .
85 val init : int -> f:(int -> char) -> string
89 init n ~f is a string of length n with index i holding the character f
92 i (called in increasing index order).
93 Since 4.02.0
96 Raises Invalid_argument if n < 0 or n > Sys.max_string_length .
99 val empty : string
103 The empty string.
105 Since 4.13.0
108 val of_bytes : bytes -> string
112 Return a new string that contains the same bytes as the given byte se‐
114 quence.
115 Since 4.13.0
118 val to_bytes : string -> bytes
122 Return a new byte sequence that contains the same bytes as the given
124 string.
125 Since 4.13.0
128 val length : string -> int
132 length s is the length (number of bytes/characters) of s .
135 val get : string -> int -> char
139 get s i is the character at index i in s . This is the same as writing
142 s.[i] .
143 Raises Invalid_argument if i not an index of s .
146 Concatenating
151 Note. The (^) binary operator concatenates two strings.
152 val concat : sep:string -> string list -> string
154 concat ~sep ss concatenates the list of strings ss , inserting the sep‐
157 arator string sep between each.
158 Raises Invalid_argument if the result is longer than
161 Sys.max_string_length bytes.
162 val cat : string -> string -> string
166 cat s1 s2 concatenates s1 and s2 ( s1 ^ s2 ).
169 Since 4.13.0
172 Raises Invalid_argument if the result is longer then than
175 Sys.max_string_length bytes.
176 Predicates and comparisons
181 val equal : t -> t -> bool
182 equal s0 s1 is true if and only if s0 and s1 are character-wise equal.
185 Since 4.05.0
188 val compare : t -> t -> int
192 compare s0 s1 sorts s0 and s1 in lexicographical order. compare be‐
195 haves like compare on strings but may be more efficient.
196 val starts_with : prefix:string -> string -> bool
200 starts_with ~ prefix s is true if and only if s starts with prefix .
203 Since 4.13.0
206 val ends_with : suffix:string -> string -> bool
210 ends_with ~suffix s is true if and only if s ends with suffix .
213 Since 4.13.0
216 val contains_from : string -> int -> char -> bool
220 contains_from s start c is true if and only if c appears in s after po‐
223 sition start .
224 Raises Invalid_argument if start is not a valid position in s .
227 val rcontains_from : string -> int -> char -> bool
231 rcontains_from s stop c is true if and only if c appears in s before
234 position stop+1 .
235 Raises Invalid_argument if stop < 0 or stop+1 is not a valid position
238 in s .
239 val contains : string -> char -> bool
243 contains s c is String.contains_from s 0 c .
246 Extracting substrings
251 val sub : string -> pos:int -> len:int -> string
252 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 Raises Invalid_argument if pos and len do not designate a valid sub‐
259 string of s .
260 val split_on_char : sep:char -> string -> string list
264 split_on_char ~sep s is the list of all (possibly empty) substrings of
267 s that are delimited by the character sep .
268 The function's result is specified by the following invariants:
270 -The list is not empty.
272 -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 -No string in the result contains the sep character.
278 Since 4.05.0
282 Transforming
287 val map : f:(char -> char) -> string -> string
288 map f s is the string resulting from applying f to all the characters
291 of s in increasing order.
292 Since 4.00.0
295 val mapi : f:(int -> char -> char) -> string -> string
299 mapi ~f s is like StringLabels.map but the index of the character is
302 also passed to f .
303 Since 4.02.0
306 val fold_left : f:('a -> char -> 'a) -> init:'a -> string -> 'a
310 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 Since 4.13.0
317 val fold_right : f:(char -> 'a -> 'a) -> string -> init:'a -> 'a
321 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 Since 4.13.0
328 val for_all : f:(char -> bool) -> string -> bool
332 for_all p s checks if all characters in s satisfy the predicate p .
335 Since 4.13.0
338 val exists : f:(char -> bool) -> string -> bool
342 exists p s checks if at least one character of s satisfies the predi‐
345 cate p .
346 Since 4.13.0
349 val trim : string -> string
353 trim s is s without leading and trailing whitespace. Whitespace charac‐
356 ters are: ' ' , '\x0C' (form feed), '\n' , '\r' , and '\t' .
357 Since 4.00.0
360 val escaped : string -> string
364 escaped s is s with special characters represented by escape sequences,
367 following the lexical conventions of OCaml.
368 All characters outside the US-ASCII printable range [0x20;0x7E] are es‐
370 caped, as well as backslash (0x2F) and double-quote (0x22).
371 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 Raises Invalid_argument if the result is longer than
378 Sys.max_string_length bytes.
379 val uppercase_ascii : string -> string
383 uppercase_ascii s is s with all lowercase letters translated to upper‐
386 case, using the US-ASCII character set.
387 Since 4.05.0
390 val lowercase_ascii : string -> string
394 lowercase_ascii s is s with all uppercase letters translated to lower‐
397 case, using the US-ASCII character set.
398 Since 4.05.0
401 val capitalize_ascii : string -> string
405 capitalize_ascii s is s with the first character set to uppercase, us‐
408 ing the US-ASCII character set.
409 Since 4.05.0
412 val uncapitalize_ascii : string -> string
416 uncapitalize_ascii s is s with the first character set to lowercase,
419 using the US-ASCII character set.
420 Since 4.05.0
423 Traversing
428 val iter : f:(char -> unit) -> string -> unit
429 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 val iteri : f:(int -> char -> unit) -> string -> unit
437 iteri is like StringLabels.iter , but the function is also given the
440 corresponding character index.
441 Since 4.00.0
444 Searching
449 val index_from : string -> int -> char -> int
450 index_from s i c is the index of the first occurrence of c in s after
453 position i .
454 Raises Not_found if c does not occur in s after position i .
457 Raises Invalid_argument if i is not a valid position in s .
460 val index_from_opt : string -> int -> char -> int option
464 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 Since 4.05
471 Raises Invalid_argument if i is not a valid position in s .
474 val rindex_from : string -> int -> char -> int
478 rindex_from s i c is the index of the last occurrence of c in s before
481 position i+1 .
482 Raises Not_found if c does not occur in s before position i+1 .
485 Raises Invalid_argument if i+1 is not a valid position in s .
488 val rindex_from_opt : string -> int -> char -> int option
492 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 Since 4.05
499 Raises Invalid_argument if i+1 is not a valid position in s .
502 val index : string -> char -> int
506 index s c is String.index_from s 0 c .
509 val index_opt : string -> char -> int option
513 index_opt s c is String.index_from_opt s 0 c .
516 Since 4.05
519 val rindex : string -> char -> int
523 rindex s c is String.rindex_from s (length s - 1) c .
526 val rindex_opt : string -> char -> int option
530 rindex_opt s c is String.rindex_from_opt s (length s - 1) c .
533 Since 4.05
536 Strings and Sequences
541 val to_seq : t -> char Seq.t
542 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 Since 4.07
550 val to_seqi : t -> (int * char) Seq.t
554 to_seqi s is like StringLabels.to_seq but also tuples the corresponding
557 index.
558 Since 4.07
561 val of_seq : char Seq.t -> t
565 of_seq s is a string made of the sequence's characters.
568 Since 4.07
571 UTF decoding and validations
576 UTF-8
577 val get_utf_8_uchar : t -> int -> Uchar.utf_decode
578 get_utf_8_uchar b i decodes an UTF-8 character at index i in b .
581 val is_valid_utf_8 : t -> bool
585 is_valid_utf_8 b is true if and only if b contains valid UTF-8 data.
588 UTF-16BE
593 val get_utf_16be_uchar : t -> int -> Uchar.utf_decode
594 get_utf_16be_uchar b i decodes an UTF-16BE character at index i in b .
597 val is_valid_utf_16be : t -> bool
601 is_valid_utf_16be b is true if and only if b contains valid UTF-16BE
604 data.
605 UTF-16LE
610 val get_utf_16le_uchar : t -> int -> Uchar.utf_decode
611 get_utf_16le_uchar b i decodes an UTF-16LE character at index i in b .
614 val is_valid_utf_16le : t -> bool
618 is_valid_utf_16le b is true if and only if b contains valid UTF-16LE
621 data.
622 Deprecated functions
627 val create : int -> bytes
628 Deprecated. This is a deprecated alias of Bytes.create / BytesLa‐
630 bels.create .
631 create n returns a fresh byte sequence of length n . The sequence is
635 uninitialized and contains arbitrary bytes.
636 Raises Invalid_argument if n < 0 or n > Sys.max_string_length .
639 val set : bytes -> int -> char -> unit
643 Deprecated. This is a deprecated alias of Bytes.set / BytesLabels.set
645 .
646 set s n c modifies byte sequence s in place, replacing the byte at in‐
650 dex n with c . You can also write s.[n] <- c instead of set s n c .
651 Raises Invalid_argument if n is not a valid index in s .
654 val blit : src:string -> src_pos:int -> dst:bytes -> dst_pos:int ->
658 len:int -> unit
659 blit ~src ~src_pos ~dst ~dst_pos ~len copies len bytes from the string
662 src , starting at index src_pos , to byte sequence dst , starting at
663 character number dst_pos .
664 Raises Invalid_argument if src_pos and len do not designate a valid
667 range of src , or if dst_pos and len do not designate a valid range of
668 dst .
669 val copy : string -> string
673 Deprecated. Because strings are immutable, it doesn't make much sense
675 to make identical copies of them.
676 Return a copy of the given string.
679 val fill : bytes -> pos:int -> len:int -> char -> unit
683 Deprecated. This is a deprecated alias of Bytes.fill / BytesLa‐
685 bels.fill .
686 fill s ~pos ~len c modifies byte sequence s in place, replacing len
690 bytes by c , starting at pos .
691 Raises Invalid_argument if pos and len do not designate a valid sub‐
694 string of s .
695 val uppercase : string -> string
699 Deprecated. Functions operating on Latin-1 character set are depre‐
701 cated.
702 Return a copy of the argument, with all lowercase letters translated to
705 uppercase, including accented letters of the ISO Latin-1 (8859-1) char‐
706 acter set.
707 val lowercase : string -> string
711 Deprecated. Functions operating on Latin-1 character set are depre‐
713 cated.
714 Return a copy of the argument, with all uppercase letters translated to
717 lowercase, including accented letters of the ISO Latin-1 (8859-1) char‐
718 acter set.
719 val capitalize : string -> string
723 Deprecated. Functions operating on Latin-1 character set are depre‐
725 cated.
726 Return a copy of the argument, with the first character set to upper‐
729 case, using the ISO Latin-1 (8859-1) character set..
730 val uncapitalize : string -> string
734 Deprecated. Functions operating on Latin-1 character set are depre‐
736 cated.
737 Return a copy of the argument, with the first character set to lower‐
740 case, using the ISO Latin-1 (8859-1) character set.
741 Binary decoding of integers
746 The functions in this section binary decode integers from strings.
747 All following functions raise Invalid_argument if the characters needed
749 at index i to decode the integer are not available.
750 Little-endian (resp. big-endian) encoding means that least (resp. most)
752 significant bytes are stored first. Big-endian is also known as net‐
753 work byte order. Native-endian encoding is either little-endian or
754 big-endian depending on Sys.big_endian .
755 32-bit and 64-bit integers are represented by the int32 and int64
757 types, which can be interpreted either as signed or unsigned numbers.
758 8-bit and 16-bit integers are represented by the int type, which has
760 more bits than the binary encoding. These extra bits are sign-extended
761 (or zero-extended) for functions which decode 8-bit or 16-bit integers
762 and represented them with int values.
763 val get_uint8 : string -> int -> int
765 get_uint8 b i is b 's unsigned 8-bit integer starting at character in‐
768 dex i .
769 Since 4.13.0
772 val get_int8 : string -> int -> int
776 get_int8 b i is b 's signed 8-bit integer starting at character index i
779 .
780 Since 4.13.0
783 val get_uint16_ne : string -> int -> int
787 get_uint16_ne b i is b 's native-endian unsigned 16-bit integer start‐
790 ing at character index i .
791 Since 4.13.0
794 val get_uint16_be : string -> int -> int
798 get_uint16_be b i is b 's big-endian unsigned 16-bit integer starting
801 at character index i .
802 Since 4.13.0
805 val get_uint16_le : string -> int -> int
809 get_uint16_le b i is b 's little-endian unsigned 16-bit integer start‐
812 ing at character index i .
813 Since 4.13.0
816 val get_int16_ne : string -> int -> int
820 get_int16_ne b i is b 's native-endian signed 16-bit integer starting
823 at character index i .
824 Since 4.13.0
827 val get_int16_be : string -> int -> int
831 get_int16_be b i is b 's big-endian signed 16-bit integer starting at
834 character index i .
835 Since 4.13.0
838 val get_int16_le : string -> int -> int
842 get_int16_le b i is b 's little-endian signed 16-bit integer starting
845 at character index i .
846 Since 4.13.0
849 val get_int32_ne : string -> int -> int32
853 get_int32_ne b i is b 's native-endian 32-bit integer starting at char‐
856 acter index i .
857 Since 4.13.0
860 val get_int32_be : string -> int -> int32
864 get_int32_be b i is b 's big-endian 32-bit integer starting at charac‐
867 ter index i .
868 Since 4.13.0
871 val get_int32_le : string -> int -> int32
875 get_int32_le b i is b 's little-endian 32-bit integer starting at char‐
878 acter index i .
879 Since 4.13.0
882 val get_int64_ne : string -> int -> int64
886 get_int64_ne b i is b 's native-endian 64-bit integer starting at char‐
889 acter index i .
890 Since 4.13.0
893 val get_int64_be : string -> int -> int64
897 get_int64_be b i is b 's big-endian 64-bit integer starting at charac‐
900 ter index i .
901 Since 4.13.0
904 val get_int64_le : string -> int -> int64
908 get_int64_le b i is b 's little-endian 64-bit integer starting at char‐
911 acter index i .
912 Since 4.13.0
915OCamldoc 2023-01-23 StringLabels(3)