1Stdlib.BytesLabels(3) OCaml library Stdlib.BytesLabels(3)
2
6 Stdlib.BytesLabels - no description
7
9 Module Stdlib.BytesLabels
10
12 Module BytesLabels
13 : (module Stdlib__BytesLabels)
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 -> f:(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 -> pos:int -> len: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 -> pos:int -> len:int -> string
121 Same as BytesLabels.sub but return a string instead of a byte sequence.
123 val extend : bytes -> left:int -> right:int -> bytes
127 extend s ~left ~right returns a new byte sequence that contains the
130 bytes of s , with left uninitialized bytes prepended and right unini‐
131 tialized bytes appended to it. If left or right is negative, then bytes
132 are removed (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 -> pos:int -> len: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 : src:bytes -> src_pos:int -> dst:bytes -> dst_pos:int ->
156 len:int -> unit
157 blit ~src ~src_pos ~dst ~dst_pos ~len copies len bytes from sequence
160 src , starting at index src_pos , to sequence dst , starting at index
161 dst_pos . It works correctly even if src and dst are the same byte se‐
162 quence, and the source and destination intervals overlap.
163 Raises Invalid_argument if src_pos and len do not designate a valid
166 range of src , or if dst_pos and len do not designate a valid range of
167 dst .
168 val blit_string : src:string -> src_pos:int -> dst:bytes -> dst_pos:int
172 -> len:int -> unit
173 blit ~src ~src_pos ~dst ~dst_pos ~len copies len bytes from string src
176 , starting at index src_pos , to byte sequence dst , starting at index
177 dst_pos .
178 Since 4.05.0 in BytesLabels
181 Raises Invalid_argument if src_pos and len do not designate a valid
184 range of src , or if dst_pos and len do not designate a valid range of
185 dst .
186 val concat : sep:bytes -> bytes list -> bytes
190 concat ~sep sl concatenates the list of byte sequences sl , inserting
193 the separator byte sequence sep between each, and returns the result as
194 a new byte sequence.
195 Raises Invalid_argument if the result is longer than
198 Sys.max_string_length bytes.
199 val cat : bytes -> bytes -> bytes
203 cat s1 s2 concatenates s1 and s2 and returns the result as a new byte
206 sequence.
207 Since 4.05.0 in BytesLabels
210 Raises Invalid_argument if the result is longer than
213 Sys.max_string_length bytes.
214 val iter : f:(char -> unit) -> bytes -> unit
218 iter ~f s applies function f in turn to all the bytes of s . It is
221 equivalent to f (get s 0); f (get s 1); ...; f (get s
222 (length s - 1)); () .
223 val iteri : f:(int -> char -> unit) -> bytes -> unit
227 Same as BytesLabels.iter , but the function is applied to the index of
229 the byte as first argument and the byte itself as second argument.
230 val map : f:(char -> char) -> bytes -> bytes
234 map ~f s applies function f in turn to all the bytes of s (in increas‐
237 ing index order) and stores the resulting bytes in a new sequence that
238 is returned as the result.
239 val mapi : f:(int -> char -> char) -> bytes -> bytes
243 mapi ~f s calls f with each character of s and its index (in increasing
246 index order) and stores the resulting bytes in a new sequence that is
247 returned as the result.
248 val fold_left : f:('a -> char -> 'a) -> init:'a -> bytes -> 'a
252 fold_left f x s computes f (... (f (f x (get s 0)) (get s 1)) ...) (get
255 s (n-1)) , where n is the length of s .
256 Since 4.13.0
259 val fold_right : f:(char -> 'a -> 'a) -> bytes -> init:'a -> 'a
263 fold_right f s x computes f (get s 0) (f (get s 1) ( ... (f (get s
266 (n-1)) x) ...)) , where n is the length of s .
267 Since 4.13.0
270 val for_all : f:(char -> bool) -> bytes -> bool
274 for_all p s checks if all characters in s satisfy the predicate p .
277 Since 4.13.0
280 val exists : f:(char -> bool) -> bytes -> bool
284 exists p s checks if at least one character of s satisfies the predi‐
287 cate p .
288 Since 4.13.0
291 val trim : bytes -> bytes
295 Return a copy of the argument, without leading and trailing whitespace.
297 The bytes regarded as whitespace are the ASCII characters ' ' , '\012'
298 , '\n' , '\r' , and '\t' .
299 val escaped : bytes -> bytes
303 Return a copy of the argument, with special characters represented by
305 escape sequences, following the lexical conventions of OCaml. All
306 characters outside the ASCII printable range (32..126) are escaped, as
307 well as backslash and double-quote.
308 Raises Invalid_argument if the result is longer than
311 Sys.max_string_length bytes.
312 val index : bytes -> char -> int
316 index s c returns the index of the first occurrence of byte c in s .
319 Raises Not_found if c does not occur in s .
322 val index_opt : bytes -> char -> int option
326 index_opt s c returns the index of the first occurrence of byte c in s
329 or None if c does not occur in s .
330 Since 4.05
333 val rindex : bytes -> char -> int
337 rindex s c returns the index of the last occurrence of byte c in s .
340 Raises Not_found if c does not occur in s .
343 val rindex_opt : bytes -> char -> int option
347 rindex_opt s c returns the index of the last occurrence of byte c in s
350 or None if c does not occur in s .
351 Since 4.05
354 val index_from : bytes -> int -> char -> int
358 index_from s i c returns the index of the first occurrence of byte c in
361 s after position i . index s c is equivalent to index_from s 0 c .
362 Raises Invalid_argument if i is not a valid position in s .
365 Raises Not_found if c does not occur in s after position i .
368 val index_from_opt : bytes -> int -> char -> int option
372 index_from_opt s i c returns the index of the first occurrence of byte
375 c in s after position i or None if c does not occur in s after position
376 i . index_opt s c is equivalent to index_from_opt s 0 c .
377 Since 4.05
380 Raises Invalid_argument if i is not a valid position in s .
383 val rindex_from : bytes -> int -> char -> int
387 rindex_from s i c returns the index of the last occurrence of byte c in
390 s before position i+1 . rindex s c is equivalent to rindex_from s
391 (length s - 1) c .
392 Raises Invalid_argument if i+1 is not a valid position in s .
395 Raises Not_found if c does not occur in s before position i+1 .
398 val rindex_from_opt : bytes -> int -> char -> int option
402 rindex_from_opt s i c returns the index of the last occurrence of byte
405 c in s before position i+1 or None if c does not occur in s before po‐
406 sition i+1 . rindex_opt s c is equivalent to rindex_from s (length s -
407 1) c .
408 Since 4.05
411 Raises Invalid_argument if i+1 is not a valid position in s .
414 val contains : bytes -> char -> bool
418 contains s c tests if byte c appears in s .
421 val contains_from : bytes -> int -> char -> bool
425 contains_from s start c tests if byte c appears in s after position
428 start . contains s c is equivalent to contains_from
429 s 0 c .
430 Raises Invalid_argument if start is not a valid position in s .
433 val rcontains_from : bytes -> int -> char -> bool
437 rcontains_from s stop c tests if byte c appears in s before position
440 stop+1 .
441 Raises Invalid_argument if stop < 0 or stop+1 is not a valid position
444 in s .
445 val uppercase : bytes -> bytes
449 Deprecated. Functions operating on Latin-1 character set are depre‐
451 cated.
452 Return a copy of the argument, with all lowercase letters translated to
455 uppercase, including accented letters of the ISO Latin-1 (8859-1) char‐
456 acter set.
457 val lowercase : bytes -> bytes
461 Deprecated. Functions operating on Latin-1 character set are depre‐
463 cated.
464 Return a copy of the argument, with all uppercase letters translated to
467 lowercase, including accented letters of the ISO Latin-1 (8859-1) char‐
468 acter set.
469 val capitalize : bytes -> bytes
473 Deprecated. Functions operating on Latin-1 character set are depre‐
475 cated.
476 Return a copy of the argument, with the first character set to upper‐
479 case, using the ISO Latin-1 (8859-1) character set.
480 val uncapitalize : bytes -> bytes
484 Deprecated. Functions operating on Latin-1 character set are depre‐
486 cated.
487 Return a copy of the argument, with the first character set to lower‐
490 case, using the ISO Latin-1 (8859-1) character set.
491 val uppercase_ascii : bytes -> bytes
495 Return a copy of the argument, with all lowercase letters translated to
497 uppercase, using the US-ASCII character set.
498 Since 4.05.0
501 val lowercase_ascii : bytes -> bytes
505 Return a copy of the argument, with all uppercase letters translated to
507 lowercase, using the US-ASCII character set.
508 Since 4.05.0
511 val capitalize_ascii : bytes -> bytes
515 Return a copy of the argument, with the first character set to upper‐
517 case, using the US-ASCII character set.
518 Since 4.05.0
521 val uncapitalize_ascii : bytes -> bytes
525 Return a copy of the argument, with the first character set to lower‐
527 case, using the US-ASCII character set.
528 Since 4.05.0
531 type t = bytes
534 An alias for the type of byte sequences.
537 val compare : t -> t -> int
541 The comparison function for byte sequences, with the same specification
543 as compare . Along with the type t , this function compare allows the
544 module Bytes to be passed as argument to the functors Set.Make and
545 Map.Make .
546 val equal : t -> t -> bool
550 The equality function for byte sequences.
552 Since 4.05.0
555 val starts_with : prefix:bytes -> bytes -> bool
559 starts_with ~ prefix s is true if and only if s starts with prefix .
562 Since 4.13.0
565 val ends_with : suffix:bytes -> bytes -> bool
569 ends_with suffix s is true if and only if s ends with suffix .
572 Since 4.13.0
575 Unsafe conversions (for advanced users)
580 This section describes unsafe, low-level conversion functions between
581 bytes and string . They do not copy the internal data; used improperly,
582 they can break the immutability invariant on strings provided by the
583 -safe-string option. They are available for expert library authors, but
584 for most purposes you should use the always-correct BytesLa‐
585 bels.to_string and BytesLabels.of_string instead.
586 val unsafe_to_string : bytes -> string
588 Unsafely convert a byte sequence into a string.
590 To reason about the use of unsafe_to_string , it is convenient to con‐
592 sider an "ownership" discipline. A piece of code that manipulates some
593 data "owns" it; there are several disjoint ownership modes, including:
594 -Unique ownership: the data may be accessed and mutated
596 -Shared ownership: the data has several owners, that may only access
598 it, not mutate it.
599 Unique ownership is linear: passing the data to another piece of code
601 means giving up ownership (we cannot write the data again). A unique
602 owner may decide to make the data shared (giving up mutation rights on
603 it), but shared data may not become uniquely-owned again.
604 unsafe_to_string s can only be used when the caller owns the byte se‐
607 quence s -- either uniquely or as shared immutable data. The caller
608 gives up ownership of s , and gains ownership of the returned string.
609 There are two valid use-cases that respect this ownership discipline:
611 1. Creating a string by initializing and mutating a byte sequence that
613 is never changed after initialization is performed.
614 let string_init len f : string =
617 let s = Bytes.create len in
618 for i = 0 to len - 1 do Bytes.set s i (f i) done;
619 Bytes.unsafe_to_string s
620 This function is safe because the byte sequence s will never be ac‐
623 cessed or mutated after unsafe_to_string is called. The string_init
624 code gives up ownership of s , and returns the ownership of the result‐
625 ing string to its caller.
626 Note that it would be unsafe if s was passed as an additional parameter
628 to the function f as it could escape this way and be mutated in the fu‐
629 ture -- string_init would give up ownership of s to pass it to f , and
630 could not call unsafe_to_string safely.
631 We have provided the String.init , String.map and String.mapi functions
633 to cover most cases of building new strings. You should prefer those
634 over to_string or unsafe_to_string whenever applicable.
635 2. Temporarily giving ownership of a byte sequence to a function that
637 expects a uniquely owned string and returns ownership back, so that we
638 can mutate the sequence again after the call ended.
639 let bytes_length (s : bytes) =
642 String.length (Bytes.unsafe_to_string s)
643 In this use-case, we do not promise that s will never be mutated after
646 the call to bytes_length s . The String.length function temporarily
647 borrows unique ownership of the byte sequence (and sees it as a string
648 ), but returns this ownership back to the caller, which may assume that
649 s is still a valid byte sequence after the call. Note that this is only
650 correct because we know that String.length does not capture its argu‐
651 ment -- it could escape by a side-channel such as a memoization combi‐
652 nator.
653 The caller may not mutate s while the string is borrowed (it has tempo‐
655 rarily given up ownership). This affects concurrent programs, but also
656 higher-order functions: if String.length returned a closure to be
657 called later, s should not be mutated until this closure is fully ap‐
658 plied and returns ownership.
659 val unsafe_of_string : string -> bytes
663 Unsafely convert a shared string to a byte sequence that should not be
665 mutated.
666 The same ownership discipline that makes unsafe_to_string correct ap‐
668 plies to unsafe_of_string : you may use it if you were the owner of the
669 string value, and you will own the return bytes in the same mode.
670 In practice, unique ownership of string values is extremely difficult
672 to reason about correctly. You should always assume strings are shared,
673 never uniquely owned.
674 For example, string literals are implicitly shared by the compiler, so
676 you never uniquely own them.
677 let incorrect = Bytes.unsafe_of_string "hello"
680 let s = Bytes.of_string "hello"
681 The first declaration is incorrect, because the string literal "hello"
684 could be shared by the compiler with other parts of the program, and
685 mutating incorrect is a bug. You must always use the second version,
686 which performs a copy and is thus correct.
687 Assuming unique ownership of strings that are not string literals, but
689 are (partly) built from string literals, is also incorrect. For exam‐
690 ple, mutating unsafe_of_string ("foo" ^ s) could mutate the shared
691 string "foo" -- assuming a rope-like representation of strings. More
692 generally, functions operating on strings will assume shared ownership,
693 they do not preserve unique ownership. It is thus incorrect to assume
694 unique ownership of the result of unsafe_of_string .
695 The only case we have reasonable confidence is safe is if the produced
697 bytes is shared -- used as an immutable byte sequence. This is possibly
698 useful for incremental migration of low-level programs that manipulate
699 immutable sequences of bytes (for example Marshal.from_bytes ) and pre‐
700 viously used the string type for this purpose.
701 val split_on_char : sep:char -> bytes -> bytes list
705 split_on_char sep s returns the list of all (possibly empty) subse‐
708 quences of s that are delimited by the sep character.
709 The function's output is specified by the following invariants:
711 -The list is not empty.
714 -Concatenating its elements using sep as a separator returns a byte se‐
716 quence equal to the input ( Bytes.concat (Bytes.make 1 sep)
717 (Bytes.split_on_char sep s) = s ).
718 -No byte sequence in the result contains the sep character.
720 Since 4.13.0
724 Iterators
729 val to_seq : t -> char Seq.t
730 Iterate on the string, in increasing index order. Modifications of the
732 string during iteration will be reflected in the sequence.
733 Since 4.07
736 val to_seqi : t -> (int * char) Seq.t
740 Iterate on the string, in increasing order, yielding indices along
742 chars
743 Since 4.07
746 val of_seq : char Seq.t -> t
750 Create a string from the generator
752 Since 4.07
755 Binary encoding/decoding of integers
760 The functions in this section binary encode and decode integers to and
761 from byte sequences.
762 All following functions raise Invalid_argument if the space needed at
764 index i to decode or encode the integer is not available.
765 Little-endian (resp. big-endian) encoding means that least (resp. most)
767 significant bytes are stored first. Big-endian is also known as net‐
768 work byte order. Native-endian encoding is either little-endian or
769 big-endian depending on Sys.big_endian .
770 32-bit and 64-bit integers are represented by the int32 and int64
772 types, which can be interpreted either as signed or unsigned numbers.
773 8-bit and 16-bit integers are represented by the int type, which has
775 more bits than the binary encoding. These extra bits are handled as
776 follows:
777 -Functions that decode signed (resp. unsigned) 8-bit or 16-bit integers
779 represented by int values sign-extend (resp. zero-extend) their result.
780 -Functions that encode 8-bit or 16-bit integers represented by int val‐
782 ues truncate their input to their least significant bytes.
783 val get_uint8 : bytes -> int -> int
786 get_uint8 b i is b 's unsigned 8-bit integer starting at byte index i .
789 Since 4.08
792 val get_int8 : bytes -> int -> int
796 get_int8 b i is b 's signed 8-bit integer starting at byte index i .
799 Since 4.08
802 val get_uint16_ne : bytes -> int -> int
806 get_uint16_ne b i is b 's native-endian unsigned 16-bit integer start‐
809 ing at byte index i .
810 Since 4.08
813 val get_uint16_be : bytes -> int -> int
817 get_uint16_be b i is b 's big-endian unsigned 16-bit integer starting
820 at byte index i .
821 Since 4.08
824 val get_uint16_le : bytes -> int -> int
828 get_uint16_le b i is b 's little-endian unsigned 16-bit integer start‐
831 ing at byte index i .
832 Since 4.08
835 val get_int16_ne : bytes -> int -> int
839 get_int16_ne b i is b 's native-endian signed 16-bit integer starting
842 at byte index i .
843 Since 4.08
846 val get_int16_be : bytes -> int -> int
850 get_int16_be b i is b 's big-endian signed 16-bit integer starting at
853 byte index i .
854 Since 4.08
857 val get_int16_le : bytes -> int -> int
861 get_int16_le b i is b 's little-endian signed 16-bit integer starting
864 at byte index i .
865 Since 4.08
868 val get_int32_ne : bytes -> int -> int32
872 get_int32_ne b i is b 's native-endian 32-bit integer starting at byte
875 index i .
876 Since 4.08
879 val get_int32_be : bytes -> int -> int32
883 get_int32_be b i is b 's big-endian 32-bit integer starting at byte in‐
886 dex i .
887 Since 4.08
890 val get_int32_le : bytes -> int -> int32
894 get_int32_le b i is b 's little-endian 32-bit integer starting at byte
897 index i .
898 Since 4.08
901 val get_int64_ne : bytes -> int -> int64
905 get_int64_ne b i is b 's native-endian 64-bit integer starting at byte
908 index i .
909 Since 4.08
912 val get_int64_be : bytes -> int -> int64
916 get_int64_be b i is b 's big-endian 64-bit integer starting at byte in‐
919 dex i .
920 Since 4.08
923 val get_int64_le : bytes -> int -> int64
927 get_int64_le b i is b 's little-endian 64-bit integer starting at byte
930 index i .
931 Since 4.08
934 val set_uint8 : bytes -> int -> int -> unit
938 set_uint8 b i v sets b 's unsigned 8-bit integer starting at byte index
941 i to v .
942 Since 4.08
945 val set_int8 : bytes -> int -> int -> unit
949 set_int8 b i v sets b 's signed 8-bit integer starting at byte index i
952 to v .
953 Since 4.08
956 val set_uint16_ne : bytes -> int -> int -> unit
960 set_uint16_ne b i v sets b 's native-endian unsigned 16-bit integer
963 starting at byte index i to v .
964 Since 4.08
967 val set_uint16_be : bytes -> int -> int -> unit
971 set_uint16_be b i v sets b 's big-endian unsigned 16-bit integer start‐
974 ing at byte index i to v .
975 Since 4.08
978 val set_uint16_le : bytes -> int -> int -> unit
982 set_uint16_le b i v sets b 's little-endian unsigned 16-bit integer
985 starting at byte index i to v .
986 Since 4.08
989 val set_int16_ne : bytes -> int -> int -> unit
993 set_int16_ne b i v sets b 's native-endian signed 16-bit integer start‐
996 ing at byte index i to v .
997 Since 4.08
1000 val set_int16_be : bytes -> int -> int -> unit
1004 set_int16_be b i v sets b 's big-endian signed 16-bit integer starting
1007 at byte index i to v .
1008 Since 4.08
1011 val set_int16_le : bytes -> int -> int -> unit
1015 set_int16_le b i v sets b 's little-endian signed 16-bit integer start‐
1018 ing at byte index i to v .
1019 Since 4.08
1022 val set_int32_ne : bytes -> int -> int32 -> unit
1026 set_int32_ne b i v sets b 's native-endian 32-bit integer starting at
1029 byte index i to v .
1030 Since 4.08
1033 val set_int32_be : bytes -> int -> int32 -> unit
1037 set_int32_be b i v sets b 's big-endian 32-bit integer starting at byte
1040 index i to v .
1041 Since 4.08
1044 val set_int32_le : bytes -> int -> int32 -> unit
1048 set_int32_le b i v sets b 's little-endian 32-bit integer starting at
1051 byte index i to v .
1052 Since 4.08
1055 val set_int64_ne : bytes -> int -> int64 -> unit
1059 set_int64_ne b i v sets b 's native-endian 64-bit integer starting at
1062 byte index i to v .
1063 Since 4.08
1066 val set_int64_be : bytes -> int -> int64 -> unit
1070 set_int64_be b i v sets b 's big-endian 64-bit integer starting at byte
1073 index i to v .
1074 Since 4.08
1077 val set_int64_le : bytes -> int -> int64 -> unit
1081 set_int64_le b i v sets b 's little-endian 64-bit integer starting at
1084 byte index i to v .
1085 Since 4.08
1088OCamldoc 2022-02-04 Stdlib.BytesLabels(3)