1Bytes(3) OCaml library Bytes(3)
2
6 Bytes - Byte sequence operations.
7
9 Module Bytes
10
12 Module Bytes
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 -> (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 -> int -> 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 -> int -> int -> string
150 Same as Bytes.sub but return a string instead of a byte sequence.
152 val extend : bytes -> int -> int -> bytes
156 extend s left right returns a new byte sequence that contains the bytes
159 of s , with left uninitialized bytes prepended and right uninitialized
160 bytes appended to it. If left or right is negative, then bytes are re‐
161 moved (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 -> int -> 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 : bytes -> int -> bytes -> int -> int -> unit
185 blit src src_pos dst dst_pos len copies len bytes from sequence src ,
188 starting at index src_pos , to sequence dst , starting at index dst_pos
189 . It works correctly even if src and dst are the same byte sequence,
190 and the source and destination intervals overlap.
191 Raises Invalid_argument if src_pos and len do not designate a valid
194 range of src , or if dst_pos and len do not designate a valid range of
195 dst .
196 val blit_string : string -> int -> bytes -> int -> int -> unit
200 blit src src_pos dst dst_pos len copies len bytes from string src ,
203 starting at index src_pos , to byte sequence dst , starting at index
204 dst_pos .
205 Since 4.05.0 in BytesLabels
208 Raises Invalid_argument if src_pos and len do not designate a valid
211 range of src , or if dst_pos and len do not designate a valid range of
212 dst .
213 val concat : bytes -> bytes list -> bytes
217 concat sep sl concatenates the list of byte sequences sl , inserting
220 the separator byte sequence sep between each, and returns the result as
221 a new byte sequence.
222 Raises Invalid_argument if the result is longer than
225 Sys.max_string_length bytes.
226 val cat : bytes -> bytes -> bytes
230 cat s1 s2 concatenates s1 and s2 and returns the result as a new byte
233 sequence.
234 Since 4.05.0 in BytesLabels
237 Raises Invalid_argument if the result is longer than
240 Sys.max_string_length bytes.
241 val iter : (char -> unit) -> bytes -> unit
245 iter f s applies function f in turn to all the bytes of s . It is
248 equivalent to f (get s 0); f (get s 1); ...; f (get s
249 (length s - 1)); () .
250 val iteri : (int -> char -> unit) -> bytes -> unit
254 Same as Bytes.iter , but the function is applied to the index of the
256 byte as first argument and the byte itself as second argument.
257 val map : (char -> char) -> bytes -> bytes
261 map f s applies function f in turn to all the bytes of s (in increasing
264 index order) and stores the resulting bytes in a new sequence that is
265 returned as the result.
266 val mapi : (int -> char -> char) -> bytes -> bytes
270 mapi f s calls f with each character of s and its index (in increasing
273 index order) and stores the resulting bytes in a new sequence that is
274 returned as the result.
275 val trim : bytes -> bytes
279 Return a copy of the argument, without leading and trailing whitespace.
281 The bytes regarded as whitespace are the ASCII characters ' ' , '\012'
282 , '\n' , '\r' , and '\t' .
283 val escaped : bytes -> bytes
287 Return a copy of the argument, with special characters represented by
289 escape sequences, following the lexical conventions of OCaml. All
290 characters outside the ASCII printable range (32..126) are escaped, as
291 well as backslash and double-quote.
292 Raises Invalid_argument if the result is longer than
295 Sys.max_string_length bytes.
296 val index : bytes -> char -> int
300 index s c returns the index of the first occurrence of byte c in s .
303 Raises Not_found if c does not occur in s .
306 val index_opt : bytes -> char -> int option
310 index_opt s c returns the index of the first occurrence of byte c in s
313 or None if c does not occur in s .
314 Since 4.05
317 val rindex : bytes -> char -> int
321 rindex s c returns the index of the last occurrence of byte c in s .
324 Raises Not_found if c does not occur in s .
327 val rindex_opt : bytes -> char -> int option
331 rindex_opt s c returns the index of the last occurrence of byte c in s
334 or None if c does not occur in s .
335 Since 4.05
338 val index_from : bytes -> int -> char -> int
342 index_from s i c returns the index of the first occurrence of byte c in
345 s after position i . index s c is equivalent to index_from s 0 c .
346 Raises Invalid_argument if i is not a valid position in s .
349 Raises Not_found if c does not occur in s after position i .
352 val index_from_opt : bytes -> int -> char -> int option
356 index_from_opt s i c returns the index of the first occurrence of byte
359 c in s after position i or None if c does not occur in s after position
360 i . index_opt s c is equivalent to index_from_opt s 0 c .
361 Since 4.05
364 Raises Invalid_argument if i is not a valid position in s .
367 val rindex_from : bytes -> int -> char -> int
371 rindex_from s i c returns the index of the last occurrence of byte c in
374 s before position i+1 . rindex s c is equivalent to rindex_from s
375 (length s - 1) c .
376 Raises Invalid_argument if i+1 is not a valid position in s .
379 Raises Not_found if c does not occur in s before position i+1 .
382 val rindex_from_opt : bytes -> int -> char -> int option
386 rindex_from_opt s i c returns the index of the last occurrence of byte
389 c in s before position i+1 or None if c does not occur in s before po‐
390 sition i+1 . rindex_opt s c is equivalent to rindex_from s (length s -
391 1) c .
392 Since 4.05
395 Raises Invalid_argument if i+1 is not a valid position in s .
398 val contains : bytes -> char -> bool
402 contains s c tests if byte c appears in s .
405 val contains_from : bytes -> int -> char -> bool
409 contains_from s start c tests if byte c appears in s after position
412 start . contains s c is equivalent to contains_from
413 s 0 c .
414 Raises Invalid_argument if start is not a valid position in s .
417 val rcontains_from : bytes -> int -> char -> bool
421 rcontains_from s stop c tests if byte c appears in s before position
424 stop+1 .
425 Raises Invalid_argument if stop < 0 or stop+1 is not a valid position
428 in s .
429 val uppercase : bytes -> bytes
433 Deprecated. Functions operating on Latin-1 character set are depre‐
435 cated.
436 Return a copy of the argument, with all lowercase letters translated to
439 uppercase, including accented letters of the ISO Latin-1 (8859-1) char‐
440 acter set.
441 val lowercase : bytes -> bytes
445 Deprecated. Functions operating on Latin-1 character set are depre‐
447 cated.
448 Return a copy of the argument, with all uppercase letters translated to
451 lowercase, including accented letters of the ISO Latin-1 (8859-1) char‐
452 acter set.
453 val capitalize : bytes -> bytes
457 Deprecated. Functions operating on Latin-1 character set are depre‐
459 cated.
460 Return a copy of the argument, with the first character set to upper‐
463 case, using the ISO Latin-1 (8859-1) character set.
464 val uncapitalize : bytes -> bytes
468 Deprecated. Functions operating on Latin-1 character set are depre‐
470 cated.
471 Return a copy of the argument, with the first character set to lower‐
474 case, using the ISO Latin-1 (8859-1) character set.
475 val uppercase_ascii : bytes -> bytes
479 Return a copy of the argument, with all lowercase letters translated to
481 uppercase, using the US-ASCII character set.
482 Since 4.03.0 (4.05.0 in BytesLabels)
485 val lowercase_ascii : bytes -> bytes
489 Return a copy of the argument, with all uppercase letters translated to
491 lowercase, using the US-ASCII character set.
492 Since 4.03.0 (4.05.0 in BytesLabels)
495 val capitalize_ascii : bytes -> bytes
499 Return a copy of the argument, with the first character set to upper‐
501 case, using the US-ASCII character set.
502 Since 4.03.0 (4.05.0 in BytesLabels)
505 val uncapitalize_ascii : bytes -> bytes
509 Return a copy of the argument, with the first character set to lower‐
511 case, using the US-ASCII character set.
512 Since 4.03.0 (4.05.0 in BytesLabels)
515 type t = bytes
518 An alias for the type of byte sequences.
521 val compare : t -> t -> int
525 The comparison function for byte sequences, with the same specification
527 as compare . Along with the type t , this function compare allows the
528 module Bytes to be passed as argument to the functors Set.Make and
529 Map.Make .
530 val equal : t -> t -> bool
534 The equality function for byte sequences.
536 Since 4.03.0 (4.05.0 in BytesLabels)
539 Unsafe conversions (for advanced users)
544 This section describes unsafe, low-level conversion functions between
545 bytes and string . They do not copy the internal data; used improperly,
546 they can break the immutability invariant on strings provided by the
547 -safe-string option. They are available for expert library authors, but
548 for most purposes you should use the always-correct Bytes.to_string and
549 Bytes.of_string instead.
550 val unsafe_to_string : bytes -> string
552 Unsafely convert a byte sequence into a string.
554 To reason about the use of unsafe_to_string , it is convenient to con‐
556 sider an "ownership" discipline. A piece of code that manipulates some
557 data "owns" it; there are several disjoint ownership modes, including:
558 -Unique ownership: the data may be accessed and mutated
560 -Shared ownership: the data has several owners, that may only access
562 it, not mutate it.
563 Unique ownership is linear: passing the data to another piece of code
565 means giving up ownership (we cannot write the data again). A unique
566 owner may decide to make the data shared (giving up mutation rights on
567 it), but shared data may not become uniquely-owned again.
568 unsafe_to_string s can only be used when the caller owns the byte se‐
571 quence s -- either uniquely or as shared immutable data. The caller
572 gives up ownership of s , and gains ownership of the returned string.
573 There are two valid use-cases that respect this ownership discipline:
575 1. Creating a string by initializing and mutating a byte sequence that
577 is never changed after initialization is performed.
578 let string_init len f : string =
581 let s = Bytes.create len in
582 for i = 0 to len - 1 do Bytes.set s i (f i) done;
583 Bytes.unsafe_to_string s
584 This function is safe because the byte sequence s will never be ac‐
587 cessed or mutated after unsafe_to_string is called. The string_init
588 code gives up ownership of s , and returns the ownership of the result‐
589 ing string to its caller.
590 Note that it would be unsafe if s was passed as an additional parameter
592 to the function f as it could escape this way and be mutated in the fu‐
593 ture -- string_init would give up ownership of s to pass it to f , and
594 could not call unsafe_to_string safely.
595 We have provided the String.init , String.map and String.mapi functions
597 to cover most cases of building new strings. You should prefer those
598 over to_string or unsafe_to_string whenever applicable.
599 2. Temporarily giving ownership of a byte sequence to a function that
601 expects a uniquely owned string and returns ownership back, so that we
602 can mutate the sequence again after the call ended.
603 let bytes_length (s : bytes) =
606 String.length (Bytes.unsafe_to_string s)
607 In this use-case, we do not promise that s will never be mutated after
610 the call to bytes_length s . The String.length function temporarily
611 borrows unique ownership of the byte sequence (and sees it as a string
612 ), but returns this ownership back to the caller, which may assume that
613 s is still a valid byte sequence after the call. Note that this is only
614 correct because we know that String.length does not capture its argu‐
615 ment -- it could escape by a side-channel such as a memoization combi‐
616 nator.
617 The caller may not mutate s while the string is borrowed (it has tempo‐
619 rarily given up ownership). This affects concurrent programs, but also
620 higher-order functions: if String.length returned a closure to be
621 called later, s should not be mutated until this closure is fully ap‐
622 plied and returns ownership.
623 val unsafe_of_string : string -> bytes
627 Unsafely convert a shared string to a byte sequence that should not be
629 mutated.
630 The same ownership discipline that makes unsafe_to_string correct ap‐
632 plies to unsafe_of_string : you may use it if you were the owner of the
633 string value, and you will own the return bytes in the same mode.
634 In practice, unique ownership of string values is extremely difficult
636 to reason about correctly. You should always assume strings are shared,
637 never uniquely owned.
638 For example, string literals are implicitly shared by the compiler, so
640 you never uniquely own them.
641 let incorrect = Bytes.unsafe_of_string "hello"
644 let s = Bytes.of_string "hello"
645 The first declaration is incorrect, because the string literal "hello"
648 could be shared by the compiler with other parts of the program, and
649 mutating incorrect is a bug. You must always use the second version,
650 which performs a copy and is thus correct.
651 Assuming unique ownership of strings that are not string literals, but
653 are (partly) built from string literals, is also incorrect. For exam‐
654 ple, mutating unsafe_of_string ("foo" ^ s) could mutate the shared
655 string "foo" -- assuming a rope-like representation of strings. More
656 generally, functions operating on strings will assume shared ownership,
657 they do not preserve unique ownership. It is thus incorrect to assume
658 unique ownership of the result of unsafe_of_string .
659 The only case we have reasonable confidence is safe is if the produced
661 bytes is shared -- used as an immutable byte sequence. This is possibly
662 useful for incremental migration of low-level programs that manipulate
663 immutable sequences of bytes (for example Marshal.from_bytes ) and pre‐
664 viously used the string type for this purpose.
665 Iterators
670 val to_seq : t -> char Seq.t
671 Iterate on the string, in increasing index order. Modifications of the
673 string during iteration will be reflected in the iterator.
674 Since 4.07
677 val to_seqi : t -> (int * char) Seq.t
681 Iterate on the string, in increasing order, yielding indices along
683 chars
684 Since 4.07
687 val of_seq : char Seq.t -> t
691 Create a string from the generator
693 Since 4.07
696 Binary encoding/decoding of integers
701 The functions in this section binary encode and decode integers to and
702 from byte sequences.
703 All following functions raise Invalid_argument if the space needed at
705 index i to decode or encode the integer is not available.
706 Little-endian (resp. big-endian) encoding means that least (resp. most)
708 significant bytes are stored first. Big-endian is also known as net‐
709 work byte order. Native-endian encoding is either little-endian or
710 big-endian depending on Sys.big_endian .
711 32-bit and 64-bit integers are represented by the int32 and int64
713 types, which can be interpreted either as signed or unsigned numbers.
714 8-bit and 16-bit integers are represented by the int type, which has
716 more bits than the binary encoding. These extra bits are handled as
717 follows:
718 -Functions that decode signed (resp. unsigned) 8-bit or 16-bit integers
720 represented by int values sign-extend (resp. zero-extend) their result.
721 -Functions that encode 8-bit or 16-bit integers represented by int val‐
723 ues truncate their input to their least significant bytes.
724 val get_uint8 : bytes -> int -> int
727 get_uint8 b i is b 's unsigned 8-bit integer starting at byte index i .
730 Since 4.08
733 val get_int8 : bytes -> int -> int
737 get_int8 b i is b 's signed 8-bit integer starting at byte index i .
740 Since 4.08
743 val get_uint16_ne : bytes -> int -> int
747 get_uint16_ne b i is b 's native-endian unsigned 16-bit integer start‐
750 ing at byte index i .
751 Since 4.08
754 val get_uint16_be : bytes -> int -> int
758 get_uint16_be b i is b 's big-endian unsigned 16-bit integer starting
761 at byte index i .
762 Since 4.08
765 val get_uint16_le : bytes -> int -> int
769 get_uint16_le b i is b 's little-endian unsigned 16-bit integer start‐
772 ing at byte index i .
773 Since 4.08
776 val get_int16_ne : bytes -> int -> int
780 get_int16_ne b i is b 's native-endian signed 16-bit integer starting
783 at byte index i .
784 Since 4.08
787 val get_int16_be : bytes -> int -> int
791 get_int16_be b i is b 's big-endian signed 16-bit integer starting at
794 byte index i .
795 Since 4.08
798 val get_int16_le : bytes -> int -> int
802 get_int16_le b i is b 's little-endian signed 16-bit integer starting
805 at byte index i .
806 Since 4.08
809 val get_int32_ne : bytes -> int -> int32
813 get_int32_ne b i is b 's native-endian 32-bit integer starting at byte
816 index i .
817 Since 4.08
820 val get_int32_be : bytes -> int -> int32
824 get_int32_be b i is b 's big-endian 32-bit integer starting at byte in‐
827 dex i .
828 Since 4.08
831 val get_int32_le : bytes -> int -> int32
835 get_int32_le b i is b 's little-endian 32-bit integer starting at byte
838 index i .
839 Since 4.08
842 val get_int64_ne : bytes -> int -> int64
846 get_int64_ne b i is b 's native-endian 64-bit integer starting at byte
849 index i .
850 Since 4.08
853 val get_int64_be : bytes -> int -> int64
857 get_int64_be b i is b 's big-endian 64-bit integer starting at byte in‐
860 dex i .
861 Since 4.08
864 val get_int64_le : bytes -> int -> int64
868 get_int64_le b i is b 's little-endian 64-bit integer starting at byte
871 index i .
872 Since 4.08
875 val set_uint8 : bytes -> int -> int -> unit
879 set_uint8 b i v sets b 's unsigned 8-bit integer starting at byte index
882 i to v .
883 Since 4.08
886 val set_int8 : bytes -> int -> int -> unit
890 set_int8 b i v sets b 's signed 8-bit integer starting at byte index i
893 to v .
894 Since 4.08
897 val set_uint16_ne : bytes -> int -> int -> unit
901 set_uint16_ne b i v sets b 's native-endian unsigned 16-bit integer
904 starting at byte index i to v .
905 Since 4.08
908 val set_uint16_be : bytes -> int -> int -> unit
912 set_uint16_be b i v sets b 's big-endian unsigned 16-bit integer start‐
915 ing at byte index i to v .
916 Since 4.08
919 val set_uint16_le : bytes -> int -> int -> unit
923 set_uint16_le b i v sets b 's little-endian unsigned 16-bit integer
926 starting at byte index i to v .
927 Since 4.08
930 val set_int16_ne : bytes -> int -> int -> unit
934 set_int16_ne b i v sets b 's native-endian signed 16-bit integer start‐
937 ing at byte index i to v .
938 Since 4.08
941 val set_int16_be : bytes -> int -> int -> unit
945 set_int16_be b i v sets b 's big-endian signed 16-bit integer starting
948 at byte index i to v .
949 Since 4.08
952 val set_int16_le : bytes -> int -> int -> unit
956 set_int16_le b i v sets b 's little-endian signed 16-bit integer start‐
959 ing at byte index i to v .
960 Since 4.08
963 val set_int32_ne : bytes -> int -> int32 -> unit
967 set_int32_ne b i v sets b 's native-endian 32-bit integer starting at
970 byte index i to v .
971 Since 4.08
974 val set_int32_be : bytes -> int -> int32 -> unit
978 set_int32_be b i v sets b 's big-endian 32-bit integer starting at byte
981 index i to v .
982 Since 4.08
985 val set_int32_le : bytes -> int -> int32 -> unit
989 set_int32_le b i v sets b 's little-endian 32-bit integer starting at
992 byte index i to v .
993 Since 4.08
996 val set_int64_ne : bytes -> int -> int64 -> unit
1000 set_int64_ne b i v sets b 's native-endian 64-bit integer starting at
1003 byte index i to v .
1004 Since 4.08
1007 val set_int64_be : bytes -> int -> int64 -> unit
1011 set_int64_be b i v sets b 's big-endian 64-bit integer starting at byte
1014 index i to v .
1015 Since 4.08
1018 val set_int64_le : bytes -> int -> int64 -> unit
1022 set_int64_le b i v sets b 's little-endian 64-bit integer starting at
1025 byte index i to v .
1026 Since 4.08
1029OCamldoc 2021-07-22 Bytes(3)