1String(3) OCaml library String(3)
2
6 String - Strings.
7
9 Module String
10
12 Module String
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 -> (int -> char) -> string
89 init n f is a string of length n with index i holding the character f i
92 (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 : string -> string list -> string
154 concat sep ss concatenates the list of strings ss , inserting the sepa‐
157 rator 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.03.0 (4.05.0 in StringLabels)
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 -> int -> int -> string
252 sub s pos len is a string of length len , containing the substring of s
255 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 : char -> string -> string list
264 split_on_char sep s is the list of all (possibly empty) substrings of s
267 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.04.0 (4.05.0 in StringLabels)
282 Transforming
287 val map : (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 : (int -> char -> char) -> string -> string
299 mapi f s is like String.map but the index of the character is also
302 passed to f .
303 Since 4.02.0
306 val fold_left : ('a -> char -> 'a) -> '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 : (char -> 'a -> 'a) -> string -> '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 : (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 : (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.03.0 (4.05.0 in StringLabels)
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.03.0 (4.05.0 in StringLabels)
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.03.0 (4.05.0 in StringLabels)
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.03.0 (4.05.0 in StringLabels)
423 Traversing
428 val iter : (char -> unit) -> string -> unit
429 iter f s applies function f in turn to all the characters of s . It is
432 equivalent to f s.[0]; f s.[1]; ...; f s.[length s - 1]; () .
433 val iteri : (int -> char -> unit) -> string -> unit
437 iteri is like String.iter , but the function is also given the corre‐
440 sponding 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 String.to_seq but also tuples the corresponding in‐
557 dex.
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 : string -> int -> bytes -> int -> int -> unit
658 blit src src_pos dst dst_pos len copies len bytes from the string src ,
661 starting at index src_pos , to byte sequence dst , starting at charac‐
662 ter number dst_pos .
663 Raises Invalid_argument if src_pos and len do not designate a valid
666 range of src , or if dst_pos and len do not designate a valid range of
667 dst .
668 val copy : string -> string
672 Deprecated. Because strings are immutable, it doesn't make much sense
674 to make identical copies of them.
675 Return a copy of the given string.
678 val fill : bytes -> int -> int -> char -> unit
682 Deprecated. This is a deprecated alias of Bytes.fill / BytesLa‐
684 bels.fill .
685 fill s pos len c modifies byte sequence s in place, replacing len bytes
689 by c , starting at pos .
690 Raises Invalid_argument if pos and len do not designate a valid sub‐
693 string of s .
694 val uppercase : string -> string
698 Deprecated. Functions operating on Latin-1 character set are depre‐
700 cated.
701 Return a copy of the argument, with all lowercase letters translated to
704 uppercase, including accented letters of the ISO Latin-1 (8859-1) char‐
705 acter set.
706 val lowercase : string -> string
710 Deprecated. Functions operating on Latin-1 character set are depre‐
712 cated.
713 Return a copy of the argument, with all uppercase letters translated to
716 lowercase, including accented letters of the ISO Latin-1 (8859-1) char‐
717 acter set.
718 val capitalize : string -> string
722 Deprecated. Functions operating on Latin-1 character set are depre‐
724 cated.
725 Return a copy of the argument, with the first character set to upper‐
728 case, using the ISO Latin-1 (8859-1) character set..
729 val uncapitalize : string -> string
733 Deprecated. Functions operating on Latin-1 character set are depre‐
735 cated.
736 Return a copy of the argument, with the first character set to lower‐
739 case, using the ISO Latin-1 (8859-1) character set.
740 Binary decoding of integers
745 The functions in this section binary decode integers from strings.
746 All following functions raise Invalid_argument if the characters needed
748 at index i to decode the integer are not available.
749 Little-endian (resp. big-endian) encoding means that least (resp. most)
751 significant bytes are stored first. Big-endian is also known as net‐
752 work byte order. Native-endian encoding is either little-endian or
753 big-endian depending on Sys.big_endian .
754 32-bit and 64-bit integers are represented by the int32 and int64
756 types, which can be interpreted either as signed or unsigned numbers.
757 8-bit and 16-bit integers are represented by the int type, which has
759 more bits than the binary encoding. These extra bits are sign-extended
760 (or zero-extended) for functions which decode 8-bit or 16-bit integers
761 and represented them with int values.
762 val get_uint8 : string -> int -> int
764 get_uint8 b i is b 's unsigned 8-bit integer starting at character in‐
767 dex i .
768 Since 4.13.0
771 val get_int8 : string -> int -> int
775 get_int8 b i is b 's signed 8-bit integer starting at character index i
778 .
779 Since 4.13.0
782 val get_uint16_ne : string -> int -> int
786 get_uint16_ne b i is b 's native-endian unsigned 16-bit integer start‐
789 ing at character index i .
790 Since 4.13.0
793 val get_uint16_be : string -> int -> int
797 get_uint16_be b i is b 's big-endian unsigned 16-bit integer starting
800 at character index i .
801 Since 4.13.0
804 val get_uint16_le : string -> int -> int
808 get_uint16_le b i is b 's little-endian unsigned 16-bit integer start‐
811 ing at character index i .
812 Since 4.13.0
815 val get_int16_ne : string -> int -> int
819 get_int16_ne b i is b 's native-endian signed 16-bit integer starting
822 at character index i .
823 Since 4.13.0
826 val get_int16_be : string -> int -> int
830 get_int16_be b i is b 's big-endian signed 16-bit integer starting at
833 character index i .
834 Since 4.13.0
837 val get_int16_le : string -> int -> int
841 get_int16_le b i is b 's little-endian signed 16-bit integer starting
844 at character index i .
845 Since 4.13.0
848 val get_int32_ne : string -> int -> int32
852 get_int32_ne b i is b 's native-endian 32-bit integer starting at char‐
855 acter index i .
856 Since 4.13.0
859 val get_int32_be : string -> int -> int32
863 get_int32_be b i is b 's big-endian 32-bit integer starting at charac‐
866 ter index i .
867 Since 4.13.0
870 val get_int32_le : string -> int -> int32
874 get_int32_le b i is b 's little-endian 32-bit integer starting at char‐
877 acter index i .
878 Since 4.13.0
881 val get_int64_ne : string -> int -> int64
885 get_int64_ne b i is b 's native-endian 64-bit integer starting at char‐
888 acter index i .
889 Since 4.13.0
892 val get_int64_be : string -> int -> int64
896 get_int64_be b i is b 's big-endian 64-bit integer starting at charac‐
899 ter index i .
900 Since 4.13.0
903 val get_int64_le : string -> int -> int64
907 get_int64_le b i is b 's little-endian 64-bit integer starting at char‐
910 acter index i .
911 Since 4.13.0
914OCamldoc 2022-07-22 String(3)