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 trim : bytes -> bytes
281 Return a copy of the argument, without leading and trailing whitespace.
283 The bytes regarded as whitespace are the ASCII characters ' ' , '\012'
284 , '\n' , '\r' , and '\t' .
285 val escaped : bytes -> bytes
289 Return a copy of the argument, with special characters represented by
291 escape sequences, following the lexical conventions of OCaml. All
292 characters outside the ASCII printable range (32..126) are escaped, as
293 well as backslash and double-quote.
294 Raises Invalid_argument if the result is longer than
297 Sys.max_string_length bytes.
298 val index : bytes -> char -> int
302 index s c returns the index of the first occurrence of byte c in s .
305 Raises Not_found if c does not occur in s .
308 val index_opt : bytes -> char -> int option
312 index_opt s c returns the index of the first occurrence of byte c in s
315 or None if c does not occur in s .
316 Since 4.05
319 val rindex : bytes -> char -> int
323 rindex s c returns the index of the last occurrence of byte c in s .
326 Raises Not_found if c does not occur in s .
329 val rindex_opt : bytes -> char -> int option
333 rindex_opt s c returns the index of the last occurrence of byte c in s
336 or None if c does not occur in s .
337 Since 4.05
340 val index_from : bytes -> int -> char -> int
344 index_from s i c returns the index of the first occurrence of byte c in
347 s after position i . index s c is equivalent to index_from s 0 c .
348 Raises Invalid_argument if i is not a valid position in s .
351 Raises Not_found if c does not occur in s after position i .
354 val index_from_opt : bytes -> int -> char -> int option
358 index_from_opt s i c returns the index of the first occurrence of byte
361 c in s after position i or None if c does not occur in s after position
362 i . index_opt s c is equivalent to index_from_opt s 0 c .
363 Since 4.05
366 Raises Invalid_argument if i is not a valid position in s .
369 val rindex_from : bytes -> int -> char -> int
373 rindex_from s i c returns the index of the last occurrence of byte c in
376 s before position i+1 . rindex s c is equivalent to rindex_from s
377 (length s - 1) c .
378 Raises Invalid_argument if i+1 is not a valid position in s .
381 Raises Not_found if c does not occur in s before position i+1 .
384 val rindex_from_opt : bytes -> int -> char -> int option
388 rindex_from_opt s i c returns the index of the last occurrence of byte
391 c in s before position i+1 or None if c does not occur in s before po‐
392 sition i+1 . rindex_opt s c is equivalent to rindex_from s (length s -
393 1) c .
394 Since 4.05
397 Raises Invalid_argument if i+1 is not a valid position in s .
400 val contains : bytes -> char -> bool
404 contains s c tests if byte c appears in s .
407 val contains_from : bytes -> int -> char -> bool
411 contains_from s start c tests if byte c appears in s after position
414 start . contains s c is equivalent to contains_from
415 s 0 c .
416 Raises Invalid_argument if start is not a valid position in s .
419 val rcontains_from : bytes -> int -> char -> bool
423 rcontains_from s stop c tests if byte c appears in s before position
426 stop+1 .
427 Raises Invalid_argument if stop < 0 or stop+1 is not a valid position
430 in s .
431 val uppercase : bytes -> bytes
435 Deprecated. Functions operating on Latin-1 character set are depre‐
437 cated.
438 Return a copy of the argument, with all lowercase letters translated to
441 uppercase, including accented letters of the ISO Latin-1 (8859-1) char‐
442 acter set.
443 val lowercase : bytes -> bytes
447 Deprecated. Functions operating on Latin-1 character set are depre‐
449 cated.
450 Return a copy of the argument, with all uppercase letters translated to
453 lowercase, including accented letters of the ISO Latin-1 (8859-1) char‐
454 acter set.
455 val capitalize : bytes -> bytes
459 Deprecated. Functions operating on Latin-1 character set are depre‐
461 cated.
462 Return a copy of the argument, with the first character set to upper‐
465 case, using the ISO Latin-1 (8859-1) character set.
466 val uncapitalize : bytes -> bytes
470 Deprecated. Functions operating on Latin-1 character set are depre‐
472 cated.
473 Return a copy of the argument, with the first character set to lower‐
476 case, using the ISO Latin-1 (8859-1) character set.
477 val uppercase_ascii : bytes -> bytes
481 Return a copy of the argument, with all lowercase letters translated to
483 uppercase, using the US-ASCII character set.
484 Since 4.05.0
487 val lowercase_ascii : bytes -> bytes
491 Return a copy of the argument, with all uppercase letters translated to
493 lowercase, using the US-ASCII character set.
494 Since 4.05.0
497 val capitalize_ascii : bytes -> bytes
501 Return a copy of the argument, with the first character set to upper‐
503 case, using the US-ASCII character set.
504 Since 4.05.0
507 val uncapitalize_ascii : bytes -> bytes
511 Return a copy of the argument, with the first character set to lower‐
513 case, using the US-ASCII character set.
514 Since 4.05.0
517 type t = bytes
520 An alias for the type of byte sequences.
523 val compare : t -> t -> int
527 The comparison function for byte sequences, with the same specification
529 as compare . Along with the type t , this function compare allows the
530 module Bytes to be passed as argument to the functors Set.Make and
531 Map.Make .
532 val equal : t -> t -> bool
536 The equality function for byte sequences.
538 Since 4.05.0
541 Unsafe conversions (for advanced users)
546 This section describes unsafe, low-level conversion functions between
547 bytes and string . They do not copy the internal data; used improperly,
548 they can break the immutability invariant on strings provided by the
549 -safe-string option. They are available for expert library authors, but
550 for most purposes you should use the always-correct BytesLa‐
551 bels.to_string and BytesLabels.of_string instead.
552 val unsafe_to_string : bytes -> string
554 Unsafely convert a byte sequence into a string.
556 To reason about the use of unsafe_to_string , it is convenient to con‐
558 sider an "ownership" discipline. A piece of code that manipulates some
559 data "owns" it; there are several disjoint ownership modes, including:
560 -Unique ownership: the data may be accessed and mutated
562 -Shared ownership: the data has several owners, that may only access
564 it, not mutate it.
565 Unique ownership is linear: passing the data to another piece of code
567 means giving up ownership (we cannot write the data again). A unique
568 owner may decide to make the data shared (giving up mutation rights on
569 it), but shared data may not become uniquely-owned again.
570 unsafe_to_string s can only be used when the caller owns the byte se‐
573 quence s -- either uniquely or as shared immutable data. The caller
574 gives up ownership of s , and gains ownership of the returned string.
575 There are two valid use-cases that respect this ownership discipline:
577 1. Creating a string by initializing and mutating a byte sequence that
579 is never changed after initialization is performed.
580 let string_init len f : string =
583 let s = Bytes.create len in
584 for i = 0 to len - 1 do Bytes.set s i (f i) done;
585 Bytes.unsafe_to_string s
586 This function is safe because the byte sequence s will never be ac‐
589 cessed or mutated after unsafe_to_string is called. The string_init
590 code gives up ownership of s , and returns the ownership of the result‐
591 ing string to its caller.
592 Note that it would be unsafe if s was passed as an additional parameter
594 to the function f as it could escape this way and be mutated in the fu‐
595 ture -- string_init would give up ownership of s to pass it to f , and
596 could not call unsafe_to_string safely.
597 We have provided the String.init , String.map and String.mapi functions
599 to cover most cases of building new strings. You should prefer those
600 over to_string or unsafe_to_string whenever applicable.
601 2. Temporarily giving ownership of a byte sequence to a function that
603 expects a uniquely owned string and returns ownership back, so that we
604 can mutate the sequence again after the call ended.
605 let bytes_length (s : bytes) =
608 String.length (Bytes.unsafe_to_string s)
609 In this use-case, we do not promise that s will never be mutated after
612 the call to bytes_length s . The String.length function temporarily
613 borrows unique ownership of the byte sequence (and sees it as a string
614 ), but returns this ownership back to the caller, which may assume that
615 s is still a valid byte sequence after the call. Note that this is only
616 correct because we know that String.length does not capture its argu‐
617 ment -- it could escape by a side-channel such as a memoization combi‐
618 nator.
619 The caller may not mutate s while the string is borrowed (it has tempo‐
621 rarily given up ownership). This affects concurrent programs, but also
622 higher-order functions: if String.length returned a closure to be
623 called later, s should not be mutated until this closure is fully ap‐
624 plied and returns ownership.
625 val unsafe_of_string : string -> bytes
629 Unsafely convert a shared string to a byte sequence that should not be
631 mutated.
632 The same ownership discipline that makes unsafe_to_string correct ap‐
634 plies to unsafe_of_string : you may use it if you were the owner of the
635 string value, and you will own the return bytes in the same mode.
636 In practice, unique ownership of string values is extremely difficult
638 to reason about correctly. You should always assume strings are shared,
639 never uniquely owned.
640 For example, string literals are implicitly shared by the compiler, so
642 you never uniquely own them.
643 let incorrect = Bytes.unsafe_of_string "hello"
646 let s = Bytes.of_string "hello"
647 The first declaration is incorrect, because the string literal "hello"
650 could be shared by the compiler with other parts of the program, and
651 mutating incorrect is a bug. You must always use the second version,
652 which performs a copy and is thus correct.
653 Assuming unique ownership of strings that are not string literals, but
655 are (partly) built from string literals, is also incorrect. For exam‐
656 ple, mutating unsafe_of_string ("foo" ^ s) could mutate the shared
657 string "foo" -- assuming a rope-like representation of strings. More
658 generally, functions operating on strings will assume shared ownership,
659 they do not preserve unique ownership. It is thus incorrect to assume
660 unique ownership of the result of unsafe_of_string .
661 The only case we have reasonable confidence is safe is if the produced
663 bytes is shared -- used as an immutable byte sequence. This is possibly
664 useful for incremental migration of low-level programs that manipulate
665 immutable sequences of bytes (for example Marshal.from_bytes ) and pre‐
666 viously used the string type for this purpose.
667 Iterators
672 val to_seq : t -> char Seq.t
673 Iterate on the string, in increasing index order. Modifications of the
675 string during iteration will be reflected in the iterator.
676 Since 4.07
679 val to_seqi : t -> (int * char) Seq.t
683 Iterate on the string, in increasing order, yielding indices along
685 chars
686 Since 4.07
689 val of_seq : char Seq.t -> t
693 Create a string from the generator
695 Since 4.07
698 Binary encoding/decoding of integers
703 The functions in this section binary encode and decode integers to and
704 from byte sequences.
705 All following functions raise Invalid_argument if the space needed at
707 index i to decode or encode the integer is not available.
708 Little-endian (resp. big-endian) encoding means that least (resp. most)
710 significant bytes are stored first. Big-endian is also known as net‐
711 work byte order. Native-endian encoding is either little-endian or
712 big-endian depending on Sys.big_endian .
713 32-bit and 64-bit integers are represented by the int32 and int64
715 types, which can be interpreted either as signed or unsigned numbers.
716 8-bit and 16-bit integers are represented by the int type, which has
718 more bits than the binary encoding. These extra bits are handled as
719 follows:
720 -Functions that decode signed (resp. unsigned) 8-bit or 16-bit integers
722 represented by int values sign-extend (resp. zero-extend) their result.
723 -Functions that encode 8-bit or 16-bit integers represented by int val‐
725 ues truncate their input to their least significant bytes.
726 val get_uint8 : bytes -> int -> int
729 get_uint8 b i is b 's unsigned 8-bit integer starting at byte index i .
732 Since 4.08
735 val get_int8 : bytes -> int -> int
739 get_int8 b i is b 's signed 8-bit integer starting at byte index i .
742 Since 4.08
745 val get_uint16_ne : bytes -> int -> int
749 get_uint16_ne b i is b 's native-endian unsigned 16-bit integer start‐
752 ing at byte index i .
753 Since 4.08
756 val get_uint16_be : bytes -> int -> int
760 get_uint16_be b i is b 's big-endian unsigned 16-bit integer starting
763 at byte index i .
764 Since 4.08
767 val get_uint16_le : bytes -> int -> int
771 get_uint16_le b i is b 's little-endian unsigned 16-bit integer start‐
774 ing at byte index i .
775 Since 4.08
778 val get_int16_ne : bytes -> int -> int
782 get_int16_ne b i is b 's native-endian signed 16-bit integer starting
785 at byte index i .
786 Since 4.08
789 val get_int16_be : bytes -> int -> int
793 get_int16_be b i is b 's big-endian signed 16-bit integer starting at
796 byte index i .
797 Since 4.08
800 val get_int16_le : bytes -> int -> int
804 get_int16_le b i is b 's little-endian signed 16-bit integer starting
807 at byte index i .
808 Since 4.08
811 val get_int32_ne : bytes -> int -> int32
815 get_int32_ne b i is b 's native-endian 32-bit integer starting at byte
818 index i .
819 Since 4.08
822 val get_int32_be : bytes -> int -> int32
826 get_int32_be b i is b 's big-endian 32-bit integer starting at byte in‐
829 dex i .
830 Since 4.08
833 val get_int32_le : bytes -> int -> int32
837 get_int32_le b i is b 's little-endian 32-bit integer starting at byte
840 index i .
841 Since 4.08
844 val get_int64_ne : bytes -> int -> int64
848 get_int64_ne b i is b 's native-endian 64-bit integer starting at byte
851 index i .
852 Since 4.08
855 val get_int64_be : bytes -> int -> int64
859 get_int64_be b i is b 's big-endian 64-bit integer starting at byte in‐
862 dex i .
863 Since 4.08
866 val get_int64_le : bytes -> int -> int64
870 get_int64_le b i is b 's little-endian 64-bit integer starting at byte
873 index i .
874 Since 4.08
877 val set_uint8 : bytes -> int -> int -> unit
881 set_uint8 b i v sets b 's unsigned 8-bit integer starting at byte index
884 i to v .
885 Since 4.08
888 val set_int8 : bytes -> int -> int -> unit
892 set_int8 b i v sets b 's signed 8-bit integer starting at byte index i
895 to v .
896 Since 4.08
899 val set_uint16_ne : bytes -> int -> int -> unit
903 set_uint16_ne b i v sets b 's native-endian unsigned 16-bit integer
906 starting at byte index i to v .
907 Since 4.08
910 val set_uint16_be : bytes -> int -> int -> unit
914 set_uint16_be b i v sets b 's big-endian unsigned 16-bit integer start‐
917 ing at byte index i to v .
918 Since 4.08
921 val set_uint16_le : bytes -> int -> int -> unit
925 set_uint16_le b i v sets b 's little-endian unsigned 16-bit integer
928 starting at byte index i to v .
929 Since 4.08
932 val set_int16_ne : bytes -> int -> int -> unit
936 set_int16_ne b i v sets b 's native-endian signed 16-bit integer start‐
939 ing at byte index i to v .
940 Since 4.08
943 val set_int16_be : bytes -> int -> int -> unit
947 set_int16_be b i v sets b 's big-endian signed 16-bit integer starting
950 at byte index i to v .
951 Since 4.08
954 val set_int16_le : bytes -> int -> int -> unit
958 set_int16_le b i v sets b 's little-endian signed 16-bit integer start‐
961 ing at byte index i to v .
962 Since 4.08
965 val set_int32_ne : bytes -> int -> int32 -> unit
969 set_int32_ne b i v sets b 's native-endian 32-bit integer starting at
972 byte index i to v .
973 Since 4.08
976 val set_int32_be : bytes -> int -> int32 -> unit
980 set_int32_be b i v sets b 's big-endian 32-bit integer starting at byte
983 index i to v .
984 Since 4.08
987 val set_int32_le : bytes -> int -> int32 -> unit
991 set_int32_le b i v sets b 's little-endian 32-bit integer starting at
994 byte index i to v .
995 Since 4.08
998 val set_int64_ne : bytes -> int -> int64 -> unit
1002 set_int64_ne b i v sets b 's native-endian 64-bit integer starting at
1005 byte index i to v .
1006 Since 4.08
1009 val set_int64_be : bytes -> int -> int64 -> unit
1013 set_int64_be b i v sets b 's big-endian 64-bit integer starting at byte
1016 index i to v .
1017 Since 4.08
1020 val set_int64_le : bytes -> int -> int64 -> unit
1024 set_int64_le b i v sets b 's little-endian 64-bit integer starting at
1027 byte index i to v .
1028 Since 4.08
1031OCamldoc 2021-07-22 BytesLabels(3)