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 Deprecated functions
576 val create : int -> bytes
577 Deprecated. This is a deprecated alias of Bytes.create / BytesLa‐
579 bels.create .
580 create n returns a fresh byte sequence of length n . The sequence is
584 uninitialized and contains arbitrary bytes.
585 Raises Invalid_argument if n < 0 or n > Sys.max_string_length .
588 val set : bytes -> int -> char -> unit
592 Deprecated. This is a deprecated alias of Bytes.set / BytesLabels.set
594 .
595 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 Raises Invalid_argument if n is not a valid index in s .
603 val blit : string -> int -> bytes -> int -> int -> unit
607 blit src src_pos dst dst_pos len copies len bytes from the string src ,
610 starting at index src_pos , to byte sequence dst , starting at charac‐
611 ter number dst_pos .
612 Raises Invalid_argument if src_pos and len do not designate a valid
615 range of src , or if dst_pos and len do not designate a valid range of
616 dst .
617 val copy : string -> string
621 Deprecated. Because strings are immutable, it doesn't make much sense
623 to make identical copies of them.
624 Return a copy of the given string.
627 val fill : bytes -> int -> int -> char -> unit
631 Deprecated. This is a deprecated alias of Bytes.fill / BytesLa‐
633 bels.fill .
634 fill s pos len c modifies byte sequence s in place, replacing len bytes
638 by c , starting at pos .
639 Raises Invalid_argument if pos and len do not designate a valid sub‐
642 string of s .
643 val uppercase : string -> string
647 Deprecated. Functions operating on Latin-1 character set are depre‐
649 cated.
650 Return a copy of the argument, with all lowercase letters translated to
653 uppercase, including accented letters of the ISO Latin-1 (8859-1) char‐
654 acter set.
655 val lowercase : string -> string
659 Deprecated. Functions operating on Latin-1 character set are depre‐
661 cated.
662 Return a copy of the argument, with all uppercase letters translated to
665 lowercase, including accented letters of the ISO Latin-1 (8859-1) char‐
666 acter set.
667 val capitalize : string -> string
671 Deprecated. Functions operating on Latin-1 character set are depre‐
673 cated.
674 Return a copy of the argument, with the first character set to upper‐
677 case, using the ISO Latin-1 (8859-1) character set..
678 val uncapitalize : string -> string
682 Deprecated. Functions operating on Latin-1 character set are depre‐
684 cated.
685 Return a copy of the argument, with the first character set to lower‐
688 case, using the ISO Latin-1 (8859-1) character set.
689 Binary decoding of integers
694 The functions in this section binary decode integers from strings.
695 All following functions raise Invalid_argument if the characters needed
697 at index i to decode the integer are not available.
698 Little-endian (resp. big-endian) encoding means that least (resp. most)
700 significant bytes are stored first. Big-endian is also known as net‐
701 work byte order. Native-endian encoding is either little-endian or
702 big-endian depending on Sys.big_endian .
703 32-bit and 64-bit integers are represented by the int32 and int64
705 types, which can be interpreted either as signed or unsigned numbers.
706 8-bit and 16-bit integers are represented by the int type, which has
708 more bits than the binary encoding. These extra bits are sign-extended
709 (or zero-extended) for functions which decode 8-bit or 16-bit integers
710 and represented them with int values.
711 val get_uint8 : string -> int -> int
713 get_uint8 b i is b 's unsigned 8-bit integer starting at character in‐
716 dex i .
717 Since 4.13.0
720 val get_int8 : string -> int -> int
724 get_int8 b i is b 's signed 8-bit integer starting at character index i
727 .
728 Since 4.13.0
731 val get_uint16_ne : string -> int -> int
735 get_uint16_ne b i is b 's native-endian unsigned 16-bit integer start‐
738 ing at character index i .
739 Since 4.13.0
742 val get_uint16_be : string -> int -> int
746 get_uint16_be b i is b 's big-endian unsigned 16-bit integer starting
749 at character index i .
750 Since 4.13.0
753 val get_uint16_le : string -> int -> int
757 get_uint16_le b i is b 's little-endian unsigned 16-bit integer start‐
760 ing at character index i .
761 Since 4.13.0
764 val get_int16_ne : string -> int -> int
768 get_int16_ne b i is b 's native-endian signed 16-bit integer starting
771 at character index i .
772 Since 4.13.0
775 val get_int16_be : string -> int -> int
779 get_int16_be b i is b 's big-endian signed 16-bit integer starting at
782 character index i .
783 Since 4.13.0
786 val get_int16_le : string -> int -> int
790 get_int16_le b i is b 's little-endian signed 16-bit integer starting
793 at character index i .
794 Since 4.13.0
797 val get_int32_ne : string -> int -> int32
801 get_int32_ne b i is b 's native-endian 32-bit integer starting at char‐
804 acter index i .
805 Since 4.13.0
808 val get_int32_be : string -> int -> int32
812 get_int32_be b i is b 's big-endian 32-bit integer starting at charac‐
815 ter index i .
816 Since 4.13.0
819 val get_int32_le : string -> int -> int32
823 get_int32_le b i is b 's little-endian 32-bit integer starting at char‐
826 acter index i .
827 Since 4.13.0
830 val get_int64_ne : string -> int -> int64
834 get_int64_ne b i is b 's native-endian 64-bit integer starting at char‐
837 acter index i .
838 Since 4.13.0
841 val get_int64_be : string -> int -> int64
845 get_int64_be b i is b 's big-endian 64-bit integer starting at charac‐
848 ter index i .
849 Since 4.13.0
852 val get_int64_le : string -> int -> int64
856 get_int64_le b i is b 's little-endian 64-bit integer starting at char‐
859 acter index i .
860 Since 4.13.0
863OCamldoc 2022-02-04 String(3)