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 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 : src:string -> src_pos:int -> dst:bytes -> dst_pos:int ->
607 len:int -> unit
608 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 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 val copy : string -> string
622 Deprecated. Because strings are immutable, it doesn't make much sense
624 to make identical copies of them.
625 Return a copy of the given string.
628 val fill : bytes -> pos:int -> len:int -> char -> unit
632 Deprecated. This is a deprecated alias of Bytes.fill / BytesLa‐
634 bels.fill .
635 fill s ~pos ~len c modifies byte sequence s in place, replacing len
639 bytes by c , starting at pos .
640 Raises Invalid_argument if pos and len do not designate a valid sub‐
643 string of s .
644 val uppercase : string -> string
648 Deprecated. Functions operating on Latin-1 character set are depre‐
650 cated.
651 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 val lowercase : string -> string
660 Deprecated. Functions operating on Latin-1 character set are depre‐
662 cated.
663 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 val capitalize : string -> string
672 Deprecated. Functions operating on Latin-1 character set are depre‐
674 cated.
675 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 val uncapitalize : string -> string
683 Deprecated. Functions operating on Latin-1 character set are depre‐
685 cated.
686 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 Binary decoding of integers
695 The functions in this section binary decode integers from strings.
696 All following functions raise Invalid_argument if the characters needed
698 at index i to decode the integer are not available.
699 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 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 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 val get_uint8 : string -> int -> int
714 get_uint8 b i is b 's unsigned 8-bit integer starting at character in‐
717 dex i .
718 Since 4.13.0
721 val get_int8 : string -> int -> int
725 get_int8 b i is b 's signed 8-bit integer starting at character index i
728 .
729 Since 4.13.0
732 val get_uint16_ne : string -> int -> int
736 get_uint16_ne b i is b 's native-endian unsigned 16-bit integer start‐
739 ing at character index i .
740 Since 4.13.0
743 val get_uint16_be : string -> int -> int
747 get_uint16_be b i is b 's big-endian unsigned 16-bit integer starting
750 at character index i .
751 Since 4.13.0
754 val get_uint16_le : string -> int -> int
758 get_uint16_le b i is b 's little-endian unsigned 16-bit integer start‐
761 ing at character index i .
762 Since 4.13.0
765 val get_int16_ne : string -> int -> int
769 get_int16_ne b i is b 's native-endian signed 16-bit integer starting
772 at character index i .
773 Since 4.13.0
776 val get_int16_be : string -> int -> int
780 get_int16_be b i is b 's big-endian signed 16-bit integer starting at
783 character index i .
784 Since 4.13.0
787 val get_int16_le : string -> int -> int
791 get_int16_le b i is b 's little-endian signed 16-bit integer starting
794 at character index i .
795 Since 4.13.0
798 val get_int32_ne : string -> int -> int32
802 get_int32_ne b i is b 's native-endian 32-bit integer starting at char‐
805 acter index i .
806 Since 4.13.0
809 val get_int32_be : string -> int -> int32
813 get_int32_be b i is b 's big-endian 32-bit integer starting at charac‐
816 ter index i .
817 Since 4.13.0
820 val get_int32_le : string -> int -> int32
824 get_int32_le b i is b 's little-endian 32-bit integer starting at char‐
827 acter index i .
828 Since 4.13.0
831 val get_int64_ne : string -> int -> int64
835 get_int64_ne b i is b 's native-endian 64-bit integer starting at char‐
838 acter index i .
839 Since 4.13.0
842 val get_int64_be : string -> int -> int64
846 get_int64_be b i is b 's big-endian 64-bit integer starting at charac‐
849 ter index i .
850 Since 4.13.0
853 val get_int64_le : string -> int -> int64
857 get_int64_le b i is b 's little-endian 64-bit integer starting at char‐
860 acter index i .
861 Since 4.13.0
864OCamldoc 2022-02-04 StringLabels(3)