1BytesLabels(3) OCaml library BytesLabels(3)
2
6 BytesLabels - Byte sequence operations.
7
9 Module BytesLabels
10
12 Module BytesLabels
13 : sig end
14 Byte sequence operations.
17 A byte sequence is a mutable data structure that contains a
19 fixed-length sequence of bytes. Each byte can be indexed in constant
20 time for reading or writing.
21 Given a byte sequence s of length l , we can access each of the l bytes
23 of s via its index in the sequence. Indexes start at 0 , and we will
24 call an index valid in s if it falls within the range [0...l-1] (inclu‐
25 sive). A position is the point between two bytes or at the beginning or
26 end of the sequence. We call a position valid in s if it falls within
27 the range [0...l] (inclusive). Note that the byte at index n is between
28 positions n and n+1 .
29 Two parameters start and len are said to designate a valid range of s
31 if len >= 0 and start and start+len are valid positions in s .
32 Byte sequences can be modified in place, for instance via the set and
34 blit functions described below. See also strings (module String ),
35 which are almost the same data structure, but cannot be modified in
36 place.
37 Bytes are represented by the OCaml type char .
39 The labeled version of this module can be used as described in the Std‐
41 Labels module.
42 Since 4.02.0
45 val length : bytes -> int
52 Return the length (number of bytes) of the argument.
54 val get : bytes -> int -> char
58 get s n returns the byte at index n in argument s .
61 Raises Invalid_argument if n is not a valid index in s .
64 val set : bytes -> int -> char -> unit
68 set s n c modifies s in place, replacing the byte at index n with c .
71 Raises Invalid_argument if n is not a valid index in s .
74 val create : int -> bytes
78 create n returns a new byte sequence of length n . The sequence is
81 uninitialized and contains arbitrary bytes.
82 Raises Invalid_argument if n < 0 or n > Sys.max_string_length .
85 val make : int -> char -> bytes
89 make n c returns a new byte sequence of length n , filled with the byte
92 c .
93 Raises Invalid_argument if n < 0 or n > Sys.max_string_length .
96 val init : int -> f:(int -> char) -> bytes
100 init n f returns a fresh byte sequence of length n , with character i
103 initialized to the result of f i (in increasing index order).
104 Raises Invalid_argument if n < 0 or n > Sys.max_string_length .
107 val empty : bytes
111 A byte sequence of size 0.
113 val copy : bytes -> bytes
117 Return a new byte sequence that contains the same bytes as the argu‐
119 ment.
120 val of_string : string -> bytes
124 Return a new byte sequence that contains the same bytes as the given
126 string.
127 val to_string : bytes -> string
131 Return a new string that contains the same bytes as the given byte se‐
133 quence.
134 val sub : bytes -> pos:int -> len:int -> bytes
138 sub s ~pos ~len returns a new byte sequence of length len , containing
141 the subsequence of s that starts at position pos and has length len .
142 Raises Invalid_argument if pos and len do not designate a valid range
145 of s .
146 val sub_string : bytes -> pos:int -> len:int -> string
150 Same as BytesLabels.sub but return a string instead of a byte sequence.
152 val extend : bytes -> left:int -> right:int -> bytes
156 extend s ~left ~right returns a new byte sequence that contains the
159 bytes of s , with left uninitialized bytes prepended and right unini‐
160 tialized bytes appended to it. If left or right is negative, then bytes
161 are removed (instead of appended) from the corresponding side of s .
162 Since 4.05.0 in BytesLabels
165 Raises Invalid_argument if the result length is negative or longer than
168 Sys.max_string_length bytes.
169 val fill : bytes -> pos:int -> len:int -> char -> unit
173 fill s ~pos ~len c modifies s in place, replacing len characters with c
176 , starting at pos .
177 Raises Invalid_argument if pos and len do not designate a valid range
180 of s .
181 val blit : src:bytes -> src_pos:int -> dst:bytes -> dst_pos:int ->
185 len:int -> unit
186 blit ~src ~src_pos ~dst ~dst_pos ~len copies len bytes from sequence
189 src , starting at index src_pos , to sequence dst , starting at index
190 dst_pos . It works correctly even if src and dst are the same byte se‐
191 quence, and the source and destination intervals overlap.
192 Raises Invalid_argument if src_pos and len do not designate a valid
195 range of src , or if dst_pos and len do not designate a valid range of
196 dst .
197 val blit_string : src:string -> src_pos:int -> dst:bytes -> dst_pos:int
201 -> len:int -> unit
202 blit ~src ~src_pos ~dst ~dst_pos ~len copies len bytes from string src
205 , starting at index src_pos , to byte sequence dst , starting at index
206 dst_pos .
207 Since 4.05.0 in BytesLabels
210 Raises Invalid_argument if src_pos and len do not designate a valid
213 range of src , or if dst_pos and len do not designate a valid range of
214 dst .
215 val concat : sep:bytes -> bytes list -> bytes
219 concat ~sep sl concatenates the list of byte sequences sl , inserting
222 the separator byte sequence sep between each, and returns the result as
223 a new byte sequence.
224 Raises Invalid_argument if the result is longer than
227 Sys.max_string_length bytes.
228 val cat : bytes -> bytes -> bytes
232 cat s1 s2 concatenates s1 and s2 and returns the result as a new byte
235 sequence.
236 Since 4.05.0 in BytesLabels
239 Raises Invalid_argument if the result is longer than
242 Sys.max_string_length bytes.
243 val iter : f:(char -> unit) -> bytes -> unit
247 iter ~f s applies function f in turn to all the bytes of s . It is
250 equivalent to f (get s 0); f (get s 1); ...; f (get s
251 (length s - 1)); () .
252 val iteri : f:(int -> char -> unit) -> bytes -> unit
256 Same as BytesLabels.iter , but the function is applied to the index of
258 the byte as first argument and the byte itself as second argument.
259 val map : f:(char -> char) -> bytes -> bytes
263 map ~f s applies function f in turn to all the bytes of s (in increas‐
266 ing index order) and stores the resulting bytes in a new sequence that
267 is returned as the result.
268 val mapi : f:(int -> char -> char) -> bytes -> bytes
272 mapi ~f s calls f with each character of s and its index (in increasing
275 index order) and stores the resulting bytes in a new sequence that is
276 returned as the result.
277 val fold_left : f:('a -> char -> 'a) -> init:'a -> bytes -> 'a
281 fold_left f x s computes f (... (f (f x (get s 0)) (get s 1)) ...) (get
284 s (n-1)) , where n is the length of s .
285 Since 4.13.0
288 val fold_right : f:(char -> 'a -> 'a) -> bytes -> init:'a -> 'a
292 fold_right f s x computes f (get s 0) (f (get s 1) ( ... (f (get s
295 (n-1)) x) ...)) , where n is the length of s .
296 Since 4.13.0
299 val for_all : f:(char -> bool) -> bytes -> bool
303 for_all p s checks if all characters in s satisfy the predicate p .
306 Since 4.13.0
309 val exists : f:(char -> bool) -> bytes -> bool
313 exists p s checks if at least one character of s satisfies the predi‐
316 cate p .
317 Since 4.13.0
320 val trim : bytes -> bytes
324 Return a copy of the argument, without leading and trailing whitespace.
326 The bytes regarded as whitespace are the ASCII characters ' ' , '\012'
327 , '\n' , '\r' , and '\t' .
328 val escaped : bytes -> bytes
332 Return a copy of the argument, with special characters represented by
334 escape sequences, following the lexical conventions of OCaml. All
335 characters outside the ASCII printable range (32..126) are escaped, as
336 well as backslash and double-quote.
337 Raises Invalid_argument if the result is longer than
340 Sys.max_string_length bytes.
341 val index : bytes -> char -> int
345 index s c returns the index of the first occurrence of byte c in s .
348 Raises Not_found if c does not occur in s .
351 val index_opt : bytes -> char -> int option
355 index_opt s c returns the index of the first occurrence of byte c in s
358 or None if c does not occur in s .
359 Since 4.05
362 val rindex : bytes -> char -> int
366 rindex s c returns the index of the last occurrence of byte c in s .
369 Raises Not_found if c does not occur in s .
372 val rindex_opt : bytes -> char -> int option
376 rindex_opt s c returns the index of the last occurrence of byte c in s
379 or None if c does not occur in s .
380 Since 4.05
383 val index_from : bytes -> int -> char -> int
387 index_from s i c returns the index of the first occurrence of byte c in
390 s after position i . index s c is equivalent to index_from s 0 c .
391 Raises Invalid_argument if i is not a valid position in s .
394 Raises Not_found if c does not occur in s after position i .
397 val index_from_opt : bytes -> int -> char -> int option
401 index_from_opt s i c returns the index of the first occurrence of byte
404 c in s after position i or None if c does not occur in s after position
405 i . index_opt s c is equivalent to index_from_opt s 0 c .
406 Since 4.05
409 Raises Invalid_argument if i is not a valid position in s .
412 val rindex_from : bytes -> int -> char -> int
416 rindex_from s i c returns the index of the last occurrence of byte c in
419 s before position i+1 . rindex s c is equivalent to rindex_from s
420 (length s - 1) c .
421 Raises Invalid_argument if i+1 is not a valid position in s .
424 Raises Not_found if c does not occur in s before position i+1 .
427 val rindex_from_opt : bytes -> int -> char -> int option
431 rindex_from_opt s i c returns the index of the last occurrence of byte
434 c in s before position i+1 or None if c does not occur in s before po‐
435 sition i+1 . rindex_opt s c is equivalent to rindex_from s (length s -
436 1) c .
437 Since 4.05
440 Raises Invalid_argument if i+1 is not a valid position in s .
443 val contains : bytes -> char -> bool
447 contains s c tests if byte c appears in s .
450 val contains_from : bytes -> int -> char -> bool
454 contains_from s start c tests if byte c appears in s after position
457 start . contains s c is equivalent to contains_from
458 s 0 c .
459 Raises Invalid_argument if start is not a valid position in s .
462 val rcontains_from : bytes -> int -> char -> bool
466 rcontains_from s stop c tests if byte c appears in s before position
469 stop+1 .
470 Raises Invalid_argument if stop < 0 or stop+1 is not a valid position
473 in s .
474 val uppercase : bytes -> bytes
478 Deprecated. Functions operating on Latin-1 character set are depre‐
480 cated.
481 Return a copy of the argument, with all lowercase letters translated to
484 uppercase, including accented letters of the ISO Latin-1 (8859-1) char‐
485 acter set.
486 val lowercase : bytes -> bytes
490 Deprecated. Functions operating on Latin-1 character set are depre‐
492 cated.
493 Return a copy of the argument, with all uppercase letters translated to
496 lowercase, including accented letters of the ISO Latin-1 (8859-1) char‐
497 acter set.
498 val capitalize : bytes -> bytes
502 Deprecated. Functions operating on Latin-1 character set are depre‐
504 cated.
505 Return a copy of the argument, with the first character set to upper‐
508 case, using the ISO Latin-1 (8859-1) character set.
509 val uncapitalize : bytes -> bytes
513 Deprecated. Functions operating on Latin-1 character set are depre‐
515 cated.
516 Return a copy of the argument, with the first character set to lower‐
519 case, using the ISO Latin-1 (8859-1) character set.
520 val uppercase_ascii : bytes -> bytes
524 Return a copy of the argument, with all lowercase letters translated to
526 uppercase, using the US-ASCII character set.
527 Since 4.05.0
530 val lowercase_ascii : bytes -> bytes
534 Return a copy of the argument, with all uppercase letters translated to
536 lowercase, using the US-ASCII character set.
537 Since 4.05.0
540 val capitalize_ascii : bytes -> bytes
544 Return a copy of the argument, with the first character set to upper‐
546 case, using the US-ASCII character set.
547 Since 4.05.0
550 val uncapitalize_ascii : bytes -> bytes
554 Return a copy of the argument, with the first character set to lower‐
556 case, using the US-ASCII character set.
557 Since 4.05.0
560 type t = bytes
563 An alias for the type of byte sequences.
566 val compare : t -> t -> int
570 The comparison function for byte sequences, with the same specification
572 as compare . Along with the type t , this function compare allows the
573 module Bytes to be passed as argument to the functors Set.Make and
574 Map.Make .
575 val equal : t -> t -> bool
579 The equality function for byte sequences.
581 Since 4.05.0
584 val starts_with : prefix:bytes -> bytes -> bool
588 starts_with ~ prefix s is true if and only if s starts with prefix .
591 Since 4.13.0
594 val ends_with : suffix:bytes -> bytes -> bool
598 ends_with suffix s is true if and only if s ends with suffix .
601 Since 4.13.0
604 Unsafe conversions (for advanced users)
609 This section describes unsafe, low-level conversion functions between
610 bytes and string . They do not copy the internal data; used improperly,
611 they can break the immutability invariant on strings provided by the
612 -safe-string option. They are available for expert library authors, but
613 for most purposes you should use the always-correct BytesLa‐
614 bels.to_string and BytesLabels.of_string instead.
615 val unsafe_to_string : bytes -> string
617 Unsafely convert a byte sequence into a string.
619 To reason about the use of unsafe_to_string , it is convenient to con‐
621 sider an "ownership" discipline. A piece of code that manipulates some
622 data "owns" it; there are several disjoint ownership modes, including:
623 -Unique ownership: the data may be accessed and mutated
625 -Shared ownership: the data has several owners, that may only access
627 it, not mutate it.
628 Unique ownership is linear: passing the data to another piece of code
630 means giving up ownership (we cannot write the data again). A unique
631 owner may decide to make the data shared (giving up mutation rights on
632 it), but shared data may not become uniquely-owned again.
633 unsafe_to_string s can only be used when the caller owns the byte se‐
636 quence s -- either uniquely or as shared immutable data. The caller
637 gives up ownership of s , and gains ownership of the returned string.
638 There are two valid use-cases that respect this ownership discipline:
640 1. Creating a string by initializing and mutating a byte sequence that
642 is never changed after initialization is performed.
643 let string_init len f : string =
646 let s = Bytes.create len in
647 for i = 0 to len - 1 do Bytes.set s i (f i) done;
648 Bytes.unsafe_to_string s
649 This function is safe because the byte sequence s will never be ac‐
652 cessed or mutated after unsafe_to_string is called. The string_init
653 code gives up ownership of s , and returns the ownership of the result‐
654 ing string to its caller.
655 Note that it would be unsafe if s was passed as an additional parameter
657 to the function f as it could escape this way and be mutated in the fu‐
658 ture -- string_init would give up ownership of s to pass it to f , and
659 could not call unsafe_to_string safely.
660 We have provided the String.init , String.map and String.mapi functions
662 to cover most cases of building new strings. You should prefer those
663 over to_string or unsafe_to_string whenever applicable.
664 2. Temporarily giving ownership of a byte sequence to a function that
666 expects a uniquely owned string and returns ownership back, so that we
667 can mutate the sequence again after the call ended.
668 let bytes_length (s : bytes) =
671 String.length (Bytes.unsafe_to_string s)
672 In this use-case, we do not promise that s will never be mutated after
675 the call to bytes_length s . The String.length function temporarily
676 borrows unique ownership of the byte sequence (and sees it as a string
677 ), but returns this ownership back to the caller, which may assume that
678 s is still a valid byte sequence after the call. Note that this is only
679 correct because we know that String.length does not capture its argu‐
680 ment -- it could escape by a side-channel such as a memoization combi‐
681 nator.
682 The caller may not mutate s while the string is borrowed (it has tempo‐
684 rarily given up ownership). This affects concurrent programs, but also
685 higher-order functions: if String.length returned a closure to be
686 called later, s should not be mutated until this closure is fully ap‐
687 plied and returns ownership.
688 val unsafe_of_string : string -> bytes
692 Unsafely convert a shared string to a byte sequence that should not be
694 mutated.
695 The same ownership discipline that makes unsafe_to_string correct ap‐
697 plies to unsafe_of_string : you may use it if you were the owner of the
698 string value, and you will own the return bytes in the same mode.
699 In practice, unique ownership of string values is extremely difficult
701 to reason about correctly. You should always assume strings are shared,
702 never uniquely owned.
703 For example, string literals are implicitly shared by the compiler, so
705 you never uniquely own them.
706 let incorrect = Bytes.unsafe_of_string "hello"
709 let s = Bytes.of_string "hello"
710 The first declaration is incorrect, because the string literal "hello"
713 could be shared by the compiler with other parts of the program, and
714 mutating incorrect is a bug. You must always use the second version,
715 which performs a copy and is thus correct.
716 Assuming unique ownership of strings that are not string literals, but
718 are (partly) built from string literals, is also incorrect. For exam‐
719 ple, mutating unsafe_of_string ("foo" ^ s) could mutate the shared
720 string "foo" -- assuming a rope-like representation of strings. More
721 generally, functions operating on strings will assume shared ownership,
722 they do not preserve unique ownership. It is thus incorrect to assume
723 unique ownership of the result of unsafe_of_string .
724 The only case we have reasonable confidence is safe is if the produced
726 bytes is shared -- used as an immutable byte sequence. This is possibly
727 useful for incremental migration of low-level programs that manipulate
728 immutable sequences of bytes (for example Marshal.from_bytes ) and pre‐
729 viously used the string type for this purpose.
730 val split_on_char : sep:char -> bytes -> bytes list
734 split_on_char sep s returns the list of all (possibly empty) subse‐
737 quences of s that are delimited by the sep character.
738 The function's output is specified by the following invariants:
740 -The list is not empty.
743 -Concatenating its elements using sep as a separator returns a byte se‐
745 quence equal to the input ( Bytes.concat (Bytes.make 1 sep)
746 (Bytes.split_on_char sep s) = s ).
747 -No byte sequence in the result contains the sep character.
749 Since 4.13.0
753 Iterators
758 val to_seq : t -> char Seq.t
759 Iterate on the string, in increasing index order. Modifications of the
761 string during iteration will be reflected in the sequence.
762 Since 4.07
765 val to_seqi : t -> (int * char) Seq.t
769 Iterate on the string, in increasing order, yielding indices along
771 chars
772 Since 4.07
775 val of_seq : char Seq.t -> t
779 Create a string from the generator
781 Since 4.07
784 Binary encoding/decoding of integers
789 The functions in this section binary encode and decode integers to and
790 from byte sequences.
791 All following functions raise Invalid_argument if the space needed at
793 index i to decode or encode the integer is not available.
794 Little-endian (resp. big-endian) encoding means that least (resp. most)
796 significant bytes are stored first. Big-endian is also known as net‐
797 work byte order. Native-endian encoding is either little-endian or
798 big-endian depending on Sys.big_endian .
799 32-bit and 64-bit integers are represented by the int32 and int64
801 types, which can be interpreted either as signed or unsigned numbers.
802 8-bit and 16-bit integers are represented by the int type, which has
804 more bits than the binary encoding. These extra bits are handled as
805 follows:
806 -Functions that decode signed (resp. unsigned) 8-bit or 16-bit integers
808 represented by int values sign-extend (resp. zero-extend) their result.
809 -Functions that encode 8-bit or 16-bit integers represented by int val‐
811 ues truncate their input to their least significant bytes.
812 val get_uint8 : bytes -> int -> int
815 get_uint8 b i is b 's unsigned 8-bit integer starting at byte index i .
818 Since 4.08
821 val get_int8 : bytes -> int -> int
825 get_int8 b i is b 's signed 8-bit integer starting at byte index i .
828 Since 4.08
831 val get_uint16_ne : bytes -> int -> int
835 get_uint16_ne b i is b 's native-endian unsigned 16-bit integer start‐
838 ing at byte index i .
839 Since 4.08
842 val get_uint16_be : bytes -> int -> int
846 get_uint16_be b i is b 's big-endian unsigned 16-bit integer starting
849 at byte index i .
850 Since 4.08
853 val get_uint16_le : bytes -> int -> int
857 get_uint16_le b i is b 's little-endian unsigned 16-bit integer start‐
860 ing at byte index i .
861 Since 4.08
864 val get_int16_ne : bytes -> int -> int
868 get_int16_ne b i is b 's native-endian signed 16-bit integer starting
871 at byte index i .
872 Since 4.08
875 val get_int16_be : bytes -> int -> int
879 get_int16_be b i is b 's big-endian signed 16-bit integer starting at
882 byte index i .
883 Since 4.08
886 val get_int16_le : bytes -> int -> int
890 get_int16_le b i is b 's little-endian signed 16-bit integer starting
893 at byte index i .
894 Since 4.08
897 val get_int32_ne : bytes -> int -> int32
901 get_int32_ne b i is b 's native-endian 32-bit integer starting at byte
904 index i .
905 Since 4.08
908 val get_int32_be : bytes -> int -> int32
912 get_int32_be b i is b 's big-endian 32-bit integer starting at byte in‐
915 dex i .
916 Since 4.08
919 val get_int32_le : bytes -> int -> int32
923 get_int32_le b i is b 's little-endian 32-bit integer starting at byte
926 index i .
927 Since 4.08
930 val get_int64_ne : bytes -> int -> int64
934 get_int64_ne b i is b 's native-endian 64-bit integer starting at byte
937 index i .
938 Since 4.08
941 val get_int64_be : bytes -> int -> int64
945 get_int64_be b i is b 's big-endian 64-bit integer starting at byte in‐
948 dex i .
949 Since 4.08
952 val get_int64_le : bytes -> int -> int64
956 get_int64_le b i is b 's little-endian 64-bit integer starting at byte
959 index i .
960 Since 4.08
963 val set_uint8 : bytes -> int -> int -> unit
967 set_uint8 b i v sets b 's unsigned 8-bit integer starting at byte index
970 i to v .
971 Since 4.08
974 val set_int8 : bytes -> int -> int -> unit
978 set_int8 b i v sets b 's signed 8-bit integer starting at byte index i
981 to v .
982 Since 4.08
985 val set_uint16_ne : bytes -> int -> int -> unit
989 set_uint16_ne b i v sets b 's native-endian unsigned 16-bit integer
992 starting at byte index i to v .
993 Since 4.08
996 val set_uint16_be : bytes -> int -> int -> unit
1000 set_uint16_be b i v sets b 's big-endian unsigned 16-bit integer start‐
1003 ing at byte index i to v .
1004 Since 4.08
1007 val set_uint16_le : bytes -> int -> int -> unit
1011 set_uint16_le b i v sets b 's little-endian unsigned 16-bit integer
1014 starting at byte index i to v .
1015 Since 4.08
1018 val set_int16_ne : bytes -> int -> int -> unit
1022 set_int16_ne b i v sets b 's native-endian signed 16-bit integer start‐
1025 ing at byte index i to v .
1026 Since 4.08
1029 val set_int16_be : bytes -> int -> int -> unit
1033 set_int16_be b i v sets b 's big-endian signed 16-bit integer starting
1036 at byte index i to v .
1037 Since 4.08
1040 val set_int16_le : bytes -> int -> int -> unit
1044 set_int16_le b i v sets b 's little-endian signed 16-bit integer start‐
1047 ing at byte index i to v .
1048 Since 4.08
1051 val set_int32_ne : bytes -> int -> int32 -> unit
1055 set_int32_ne b i v sets b 's native-endian 32-bit integer starting at
1058 byte index i to v .
1059 Since 4.08
1062 val set_int32_be : bytes -> int -> int32 -> unit
1066 set_int32_be b i v sets b 's big-endian 32-bit integer starting at byte
1069 index i to v .
1070 Since 4.08
1073 val set_int32_le : bytes -> int -> int32 -> unit
1077 set_int32_le b i v sets b 's little-endian 32-bit integer starting at
1080 byte index i to v .
1081 Since 4.08
1084 val set_int64_ne : bytes -> int -> int64 -> unit
1088 set_int64_ne b i v sets b 's native-endian 64-bit integer starting at
1091 byte index i to v .
1092 Since 4.08
1095 val set_int64_be : bytes -> int -> int64 -> unit
1099 set_int64_be b i v sets b 's big-endian 64-bit integer starting at byte
1102 index i to v .
1103 Since 4.08
1106 val set_int64_le : bytes -> int -> int64 -> unit
1110 set_int64_le b i v sets b 's little-endian 64-bit integer starting at
1113 byte index i to v .
1114 Since 4.08
1117OCamldoc 2022-02-04 BytesLabels(3)