1Stdlib.Bytes(3) OCaml library Stdlib.Bytes(3)
2
6 Stdlib.Bytes - no description
7
9 Module Stdlib.Bytes
10
12 Module Bytes
13 : (module Stdlib__Bytes)
14 val length : bytes -> int
23 Return the length (number of bytes) of the argument.
25 val get : bytes -> int -> char
29 get s n returns the byte at index n in argument s .
32 Raises Invalid_argument if n is not a valid index in s .
35 val set : bytes -> int -> char -> unit
39 set s n c modifies s in place, replacing the byte at index n with c .
42 Raises Invalid_argument if n is not a valid index in s .
45 val create : int -> bytes
49 create n returns a new byte sequence of length n . The sequence is
52 uninitialized and contains arbitrary bytes.
53 Raises Invalid_argument if n < 0 or n > Sys.max_string_length .
56 val make : int -> char -> bytes
60 make n c returns a new byte sequence of length n , filled with the byte
63 c .
64 Raises Invalid_argument if n < 0 or n > Sys.max_string_length .
67 val init : int -> (int -> char) -> bytes
71 init n f returns a fresh byte sequence of length n , with character i
74 initialized to the result of f i (in increasing index order).
75 Raises Invalid_argument if n < 0 or n > Sys.max_string_length .
78 val empty : bytes
82 A byte sequence of size 0.
84 val copy : bytes -> bytes
88 Return a new byte sequence that contains the same bytes as the argu‐
90 ment.
91 val of_string : string -> bytes
95 Return a new byte sequence that contains the same bytes as the given
97 string.
98 val to_string : bytes -> string
102 Return a new string that contains the same bytes as the given byte se‐
104 quence.
105 val sub : bytes -> int -> int -> bytes
109 sub s pos len returns a new byte sequence of length len , containing
112 the subsequence of s that starts at position pos and has length len .
113 Raises Invalid_argument if pos and len do not designate a valid range
116 of s .
117 val sub_string : bytes -> int -> int -> string
121 Same as Bytes.sub but return a string instead of a byte sequence.
123 val extend : bytes -> int -> int -> bytes
127 extend s left right returns a new byte sequence that contains the bytes
130 of s , with left uninitialized bytes prepended and right uninitialized
131 bytes appended to it. If left or right is negative, then bytes are re‐
132 moved (instead of appended) from the corresponding side of s .
133 Since 4.05.0 in BytesLabels
136 Raises Invalid_argument if the result length is negative or longer than
139 Sys.max_string_length bytes.
140 val fill : bytes -> int -> int -> char -> unit
144 fill s pos len c modifies s in place, replacing len characters with c ,
147 starting at pos .
148 Raises Invalid_argument if pos and len do not designate a valid range
151 of s .
152 val blit : bytes -> int -> bytes -> int -> int -> unit
156 blit src src_pos dst dst_pos len copies len bytes from sequence src ,
159 starting at index src_pos , to sequence dst , starting at index dst_pos
160 . It works correctly even if src and dst are the same byte sequence,
161 and the source and destination intervals overlap.
162 Raises Invalid_argument if src_pos and len do not designate a valid
165 range of src , or if dst_pos and len do not designate a valid range of
166 dst .
167 val blit_string : string -> int -> bytes -> int -> int -> unit
171 blit src src_pos dst dst_pos len copies len bytes from string src ,
174 starting at index src_pos , to byte sequence dst , starting at index
175 dst_pos .
176 Since 4.05.0 in BytesLabels
179 Raises Invalid_argument if src_pos and len do not designate a valid
182 range of src , or if dst_pos and len do not designate a valid range of
183 dst .
184 val concat : bytes -> bytes list -> bytes
188 concat sep sl concatenates the list of byte sequences sl , inserting
191 the separator byte sequence sep between each, and returns the result as
192 a new byte sequence.
193 Raises Invalid_argument if the result is longer than
196 Sys.max_string_length bytes.
197 val cat : bytes -> bytes -> bytes
201 cat s1 s2 concatenates s1 and s2 and returns the result as a new byte
204 sequence.
205 Since 4.05.0 in BytesLabels
208 Raises Invalid_argument if the result is longer than
211 Sys.max_string_length bytes.
212 val iter : (char -> unit) -> bytes -> unit
216 iter f s applies function f in turn to all the bytes of s . It is
219 equivalent to f (get s 0); f (get s 1); ...; f (get s
220 (length s - 1)); () .
221 val iteri : (int -> char -> unit) -> bytes -> unit
225 Same as Bytes.iter , but the function is applied to the index of the
227 byte as first argument and the byte itself as second argument.
228 val map : (char -> char) -> bytes -> bytes
232 map f s applies function f in turn to all the bytes of s (in increasing
235 index order) and stores the resulting bytes in a new sequence that is
236 returned as the result.
237 val mapi : (int -> char -> char) -> bytes -> bytes
241 mapi f s calls f with each character of s and its index (in increasing
244 index order) and stores the resulting bytes in a new sequence that is
245 returned as the result.
246 val fold_left : ('a -> char -> 'a) -> 'a -> bytes -> 'a
250 fold_left f x s computes f (... (f (f x (get s 0)) (get s 1)) ...) (get
253 s (n-1)) , where n is the length of s .
254 Since 4.13.0
257 val fold_right : (char -> 'a -> 'a) -> bytes -> 'a -> 'a
261 fold_right f s x computes f (get s 0) (f (get s 1) ( ... (f (get s
264 (n-1)) x) ...)) , where n is the length of s .
265 Since 4.13.0
268 val for_all : (char -> bool) -> bytes -> bool
272 for_all p s checks if all characters in s satisfy the predicate p .
275 Since 4.13.0
278 val exists : (char -> bool) -> bytes -> bool
282 exists p s checks if at least one character of s satisfies the predi‐
285 cate p .
286 Since 4.13.0
289 val trim : bytes -> bytes
293 Return a copy of the argument, without leading and trailing whitespace.
295 The bytes regarded as whitespace are the ASCII characters ' ' , '\012'
296 , '\n' , '\r' , and '\t' .
297 val escaped : bytes -> bytes
301 Return a copy of the argument, with special characters represented by
303 escape sequences, following the lexical conventions of OCaml. All
304 characters outside the ASCII printable range (32..126) are escaped, as
305 well as backslash and double-quote.
306 Raises Invalid_argument if the result is longer than
309 Sys.max_string_length bytes.
310 val index : bytes -> char -> int
314 index s c returns the index of the first occurrence of byte c in s .
317 Raises Not_found if c does not occur in s .
320 val index_opt : bytes -> char -> int option
324 index_opt s c returns the index of the first occurrence of byte c in s
327 or None if c does not occur in s .
328 Since 4.05
331 val rindex : bytes -> char -> int
335 rindex s c returns the index of the last occurrence of byte c in s .
338 Raises Not_found if c does not occur in s .
341 val rindex_opt : bytes -> char -> int option
345 rindex_opt s c returns the index of the last occurrence of byte c in s
348 or None if c does not occur in s .
349 Since 4.05
352 val index_from : bytes -> int -> char -> int
356 index_from s i c returns the index of the first occurrence of byte c in
359 s after position i . index s c is equivalent to index_from s 0 c .
360 Raises Invalid_argument if i is not a valid position in s .
363 Raises Not_found if c does not occur in s after position i .
366 val index_from_opt : bytes -> int -> char -> int option
370 index_from_opt s i c returns the index of the first occurrence of byte
373 c in s after position i or None if c does not occur in s after position
374 i . index_opt s c is equivalent to index_from_opt s 0 c .
375 Since 4.05
378 Raises Invalid_argument if i is not a valid position in s .
381 val rindex_from : bytes -> int -> char -> int
385 rindex_from s i c returns the index of the last occurrence of byte c in
388 s before position i+1 . rindex s c is equivalent to rindex_from s
389 (length s - 1) c .
390 Raises Invalid_argument if i+1 is not a valid position in s .
393 Raises Not_found if c does not occur in s before position i+1 .
396 val rindex_from_opt : bytes -> int -> char -> int option
400 rindex_from_opt s i c returns the index of the last occurrence of byte
403 c in s before position i+1 or None if c does not occur in s before po‐
404 sition i+1 . rindex_opt s c is equivalent to rindex_from s (length s -
405 1) c .
406 Since 4.05
409 Raises Invalid_argument if i+1 is not a valid position in s .
412 val contains : bytes -> char -> bool
416 contains s c tests if byte c appears in s .
419 val contains_from : bytes -> int -> char -> bool
423 contains_from s start c tests if byte c appears in s after position
426 start . contains s c is equivalent to contains_from
427 s 0 c .
428 Raises Invalid_argument if start is not a valid position in s .
431 val rcontains_from : bytes -> int -> char -> bool
435 rcontains_from s stop c tests if byte c appears in s before position
438 stop+1 .
439 Raises Invalid_argument if stop < 0 or stop+1 is not a valid position
442 in s .
443 val uppercase : bytes -> bytes
447 Deprecated. Functions operating on Latin-1 character set are depre‐
449 cated.
450 Return a copy of the argument, with all lowercase letters translated to
453 uppercase, including accented letters of the ISO Latin-1 (8859-1) char‐
454 acter set.
455 val lowercase : bytes -> bytes
459 Deprecated. Functions operating on Latin-1 character set are depre‐
461 cated.
462 Return a copy of the argument, with all uppercase letters translated to
465 lowercase, including accented letters of the ISO Latin-1 (8859-1) char‐
466 acter set.
467 val capitalize : bytes -> bytes
471 Deprecated. Functions operating on Latin-1 character set are depre‐
473 cated.
474 Return a copy of the argument, with the first character set to upper‐
477 case, using the ISO Latin-1 (8859-1) character set.
478 val uncapitalize : bytes -> bytes
482 Deprecated. Functions operating on Latin-1 character set are depre‐
484 cated.
485 Return a copy of the argument, with the first character set to lower‐
488 case, using the ISO Latin-1 (8859-1) character set.
489 val uppercase_ascii : bytes -> bytes
493 Return a copy of the argument, with all lowercase letters translated to
495 uppercase, using the US-ASCII character set.
496 Since 4.03.0 (4.05.0 in BytesLabels)
499 val lowercase_ascii : bytes -> bytes
503 Return a copy of the argument, with all uppercase letters translated to
505 lowercase, using the US-ASCII character set.
506 Since 4.03.0 (4.05.0 in BytesLabels)
509 val capitalize_ascii : bytes -> bytes
513 Return a copy of the argument, with the first character set to upper‐
515 case, using the US-ASCII character set.
516 Since 4.03.0 (4.05.0 in BytesLabels)
519 val uncapitalize_ascii : bytes -> bytes
523 Return a copy of the argument, with the first character set to lower‐
525 case, using the US-ASCII character set.
526 Since 4.03.0 (4.05.0 in BytesLabels)
529 type t = bytes
532 An alias for the type of byte sequences.
535 val compare : t -> t -> int
539 The comparison function for byte sequences, with the same specification
541 as compare . Along with the type t , this function compare allows the
542 module Bytes to be passed as argument to the functors Set.Make and
543 Map.Make .
544 val equal : t -> t -> bool
548 The equality function for byte sequences.
550 Since 4.03.0 (4.05.0 in BytesLabels)
553 val starts_with : prefix:bytes -> bytes -> bool
557 starts_with ~ prefix s is true if and only if s starts with prefix .
560 Since 4.13.0
563 val ends_with : suffix:bytes -> bytes -> bool
567 ends_with suffix s is true if and only if s ends with suffix .
570 Since 4.13.0
573 Unsafe conversions (for advanced users)
578 This section describes unsafe, low-level conversion functions between
579 bytes and string . They do not copy the internal data; used improperly,
580 they can break the immutability invariant on strings provided by the
581 -safe-string option. They are available for expert library authors, but
582 for most purposes you should use the always-correct Bytes.to_string and
583 Bytes.of_string instead.
584 val unsafe_to_string : bytes -> string
586 Unsafely convert a byte sequence into a string.
588 To reason about the use of unsafe_to_string , it is convenient to con‐
590 sider an "ownership" discipline. A piece of code that manipulates some
591 data "owns" it; there are several disjoint ownership modes, including:
592 -Unique ownership: the data may be accessed and mutated
594 -Shared ownership: the data has several owners, that may only access
596 it, not mutate it.
597 Unique ownership is linear: passing the data to another piece of code
599 means giving up ownership (we cannot write the data again). A unique
600 owner may decide to make the data shared (giving up mutation rights on
601 it), but shared data may not become uniquely-owned again.
602 unsafe_to_string s can only be used when the caller owns the byte se‐
605 quence s -- either uniquely or as shared immutable data. The caller
606 gives up ownership of s , and gains ownership of the returned string.
607 There are two valid use-cases that respect this ownership discipline:
609 1. Creating a string by initializing and mutating a byte sequence that
611 is never changed after initialization is performed.
612 let string_init len f : string =
615 let s = Bytes.create len in
616 for i = 0 to len - 1 do Bytes.set s i (f i) done;
617 Bytes.unsafe_to_string s
618 This function is safe because the byte sequence s will never be ac‐
621 cessed or mutated after unsafe_to_string is called. The string_init
622 code gives up ownership of s , and returns the ownership of the result‐
623 ing string to its caller.
624 Note that it would be unsafe if s was passed as an additional parameter
626 to the function f as it could escape this way and be mutated in the fu‐
627 ture -- string_init would give up ownership of s to pass it to f , and
628 could not call unsafe_to_string safely.
629 We have provided the String.init , String.map and String.mapi functions
631 to cover most cases of building new strings. You should prefer those
632 over to_string or unsafe_to_string whenever applicable.
633 2. Temporarily giving ownership of a byte sequence to a function that
635 expects a uniquely owned string and returns ownership back, so that we
636 can mutate the sequence again after the call ended.
637 let bytes_length (s : bytes) =
640 String.length (Bytes.unsafe_to_string s)
641 In this use-case, we do not promise that s will never be mutated after
644 the call to bytes_length s . The String.length function temporarily
645 borrows unique ownership of the byte sequence (and sees it as a string
646 ), but returns this ownership back to the caller, which may assume that
647 s is still a valid byte sequence after the call. Note that this is only
648 correct because we know that String.length does not capture its argu‐
649 ment -- it could escape by a side-channel such as a memoization combi‐
650 nator.
651 The caller may not mutate s while the string is borrowed (it has tempo‐
653 rarily given up ownership). This affects concurrent programs, but also
654 higher-order functions: if String.length returned a closure to be
655 called later, s should not be mutated until this closure is fully ap‐
656 plied and returns ownership.
657 val unsafe_of_string : string -> bytes
661 Unsafely convert a shared string to a byte sequence that should not be
663 mutated.
664 The same ownership discipline that makes unsafe_to_string correct ap‐
666 plies to unsafe_of_string : you may use it if you were the owner of the
667 string value, and you will own the return bytes in the same mode.
668 In practice, unique ownership of string values is extremely difficult
670 to reason about correctly. You should always assume strings are shared,
671 never uniquely owned.
672 For example, string literals are implicitly shared by the compiler, so
674 you never uniquely own them.
675 let incorrect = Bytes.unsafe_of_string "hello"
678 let s = Bytes.of_string "hello"
679 The first declaration is incorrect, because the string literal "hello"
682 could be shared by the compiler with other parts of the program, and
683 mutating incorrect is a bug. You must always use the second version,
684 which performs a copy and is thus correct.
685 Assuming unique ownership of strings that are not string literals, but
687 are (partly) built from string literals, is also incorrect. For exam‐
688 ple, mutating unsafe_of_string ("foo" ^ s) could mutate the shared
689 string "foo" -- assuming a rope-like representation of strings. More
690 generally, functions operating on strings will assume shared ownership,
691 they do not preserve unique ownership. It is thus incorrect to assume
692 unique ownership of the result of unsafe_of_string .
693 The only case we have reasonable confidence is safe is if the produced
695 bytes is shared -- used as an immutable byte sequence. This is possibly
696 useful for incremental migration of low-level programs that manipulate
697 immutable sequences of bytes (for example Marshal.from_bytes ) and pre‐
698 viously used the string type for this purpose.
699 val split_on_char : char -> bytes -> bytes list
703 split_on_char sep s returns the list of all (possibly empty) subse‐
706 quences of s that are delimited by the sep character.
707 The function's output is specified by the following invariants:
709 -The list is not empty.
712 -Concatenating its elements using sep as a separator returns a byte se‐
714 quence equal to the input ( Bytes.concat (Bytes.make 1 sep)
715 (Bytes.split_on_char sep s) = s ).
716 -No byte sequence in the result contains the sep character.
718 Since 4.13.0
722 Iterators
727 val to_seq : t -> char Seq.t
728 Iterate on the string, in increasing index order. Modifications of the
730 string during iteration will be reflected in the sequence.
731 Since 4.07
734 val to_seqi : t -> (int * char) Seq.t
738 Iterate on the string, in increasing order, yielding indices along
740 chars
741 Since 4.07
744 val of_seq : char Seq.t -> t
748 Create a string from the generator
750 Since 4.07
753 Binary encoding/decoding of integers
758 The functions in this section binary encode and decode integers to and
759 from byte sequences.
760 All following functions raise Invalid_argument if the space needed at
762 index i to decode or encode the integer is not available.
763 Little-endian (resp. big-endian) encoding means that least (resp. most)
765 significant bytes are stored first. Big-endian is also known as net‐
766 work byte order. Native-endian encoding is either little-endian or
767 big-endian depending on Sys.big_endian .
768 32-bit and 64-bit integers are represented by the int32 and int64
770 types, which can be interpreted either as signed or unsigned numbers.
771 8-bit and 16-bit integers are represented by the int type, which has
773 more bits than the binary encoding. These extra bits are handled as
774 follows:
775 -Functions that decode signed (resp. unsigned) 8-bit or 16-bit integers
777 represented by int values sign-extend (resp. zero-extend) their result.
778 -Functions that encode 8-bit or 16-bit integers represented by int val‐
780 ues truncate their input to their least significant bytes.
781 val get_uint8 : bytes -> int -> int
784 get_uint8 b i is b 's unsigned 8-bit integer starting at byte index i .
787 Since 4.08
790 val get_int8 : bytes -> int -> int
794 get_int8 b i is b 's signed 8-bit integer starting at byte index i .
797 Since 4.08
800 val get_uint16_ne : bytes -> int -> int
804 get_uint16_ne b i is b 's native-endian unsigned 16-bit integer start‐
807 ing at byte index i .
808 Since 4.08
811 val get_uint16_be : bytes -> int -> int
815 get_uint16_be b i is b 's big-endian unsigned 16-bit integer starting
818 at byte index i .
819 Since 4.08
822 val get_uint16_le : bytes -> int -> int
826 get_uint16_le b i is b 's little-endian unsigned 16-bit integer start‐
829 ing at byte index i .
830 Since 4.08
833 val get_int16_ne : bytes -> int -> int
837 get_int16_ne b i is b 's native-endian signed 16-bit integer starting
840 at byte index i .
841 Since 4.08
844 val get_int16_be : bytes -> int -> int
848 get_int16_be b i is b 's big-endian signed 16-bit integer starting at
851 byte index i .
852 Since 4.08
855 val get_int16_le : bytes -> int -> int
859 get_int16_le b i is b 's little-endian signed 16-bit integer starting
862 at byte index i .
863 Since 4.08
866 val get_int32_ne : bytes -> int -> int32
870 get_int32_ne b i is b 's native-endian 32-bit integer starting at byte
873 index i .
874 Since 4.08
877 val get_int32_be : bytes -> int -> int32
881 get_int32_be b i is b 's big-endian 32-bit integer starting at byte in‐
884 dex i .
885 Since 4.08
888 val get_int32_le : bytes -> int -> int32
892 get_int32_le b i is b 's little-endian 32-bit integer starting at byte
895 index i .
896 Since 4.08
899 val get_int64_ne : bytes -> int -> int64
903 get_int64_ne b i is b 's native-endian 64-bit integer starting at byte
906 index i .
907 Since 4.08
910 val get_int64_be : bytes -> int -> int64
914 get_int64_be b i is b 's big-endian 64-bit integer starting at byte in‐
917 dex i .
918 Since 4.08
921 val get_int64_le : bytes -> int -> int64
925 get_int64_le b i is b 's little-endian 64-bit integer starting at byte
928 index i .
929 Since 4.08
932 val set_uint8 : bytes -> int -> int -> unit
936 set_uint8 b i v sets b 's unsigned 8-bit integer starting at byte index
939 i to v .
940 Since 4.08
943 val set_int8 : bytes -> int -> int -> unit
947 set_int8 b i v sets b 's signed 8-bit integer starting at byte index i
950 to v .
951 Since 4.08
954 val set_uint16_ne : bytes -> int -> int -> unit
958 set_uint16_ne b i v sets b 's native-endian unsigned 16-bit integer
961 starting at byte index i to v .
962 Since 4.08
965 val set_uint16_be : bytes -> int -> int -> unit
969 set_uint16_be b i v sets b 's big-endian unsigned 16-bit integer start‐
972 ing at byte index i to v .
973 Since 4.08
976 val set_uint16_le : bytes -> int -> int -> unit
980 set_uint16_le b i v sets b 's little-endian unsigned 16-bit integer
983 starting at byte index i to v .
984 Since 4.08
987 val set_int16_ne : bytes -> int -> int -> unit
991 set_int16_ne b i v sets b 's native-endian signed 16-bit integer start‐
994 ing at byte index i to v .
995 Since 4.08
998 val set_int16_be : bytes -> int -> int -> unit
1002 set_int16_be b i v sets b 's big-endian signed 16-bit integer starting
1005 at byte index i to v .
1006 Since 4.08
1009 val set_int16_le : bytes -> int -> int -> unit
1013 set_int16_le b i v sets b 's little-endian signed 16-bit integer start‐
1016 ing at byte index i to v .
1017 Since 4.08
1020 val set_int32_ne : bytes -> int -> int32 -> unit
1024 set_int32_ne b i v sets b 's native-endian 32-bit integer starting at
1027 byte index i to v .
1028 Since 4.08
1031 val set_int32_be : bytes -> int -> int32 -> unit
1035 set_int32_be b i v sets b 's big-endian 32-bit integer starting at byte
1038 index i to v .
1039 Since 4.08
1042 val set_int32_le : bytes -> int -> int32 -> unit
1046 set_int32_le b i v sets b 's little-endian 32-bit integer starting at
1049 byte index i to v .
1050 Since 4.08
1053 val set_int64_ne : bytes -> int -> int64 -> unit
1057 set_int64_ne b i v sets b 's native-endian 64-bit integer starting at
1060 byte index i to v .
1061 Since 4.08
1064 val set_int64_be : bytes -> int -> int64 -> unit
1068 set_int64_be b i v sets b 's big-endian 64-bit integer starting at byte
1071 index i to v .
1072 Since 4.08
1075 val set_int64_le : bytes -> int -> int64 -> unit
1079 set_int64_le b i v sets b 's little-endian 64-bit integer starting at
1082 byte index i to v .
1083 Since 4.08
1086OCamldoc 2022-02-04 Stdlib.Bytes(3)