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 Bytes.init n f returns a fresh byte sequence of length n , with charac‐
74 ter i 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
104 sequence.
105 val sub : bytes -> int -> int -> bytes
109 sub s start len returns a new byte sequence of length len , containing
112 the subsequence of s that starts at position start and has length len .
113 Raises Invalid_argument if start and len do not designate a valid range
116 of s .
117 val sub_string : bytes -> int -> int -> string
121 Same as 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
132 removed (instead of appended) from the corresponding side of s .
133 Raises Invalid_argument if the result length is negative or longer than
136 Sys.max_string_length bytes.
137 val fill : bytes -> int -> int -> char -> unit
141 fill s start len c modifies s in place, replacing len characters with c
144 , starting at start .
145 Raises Invalid_argument if start and len do not designate a valid range
148 of s .
149 val blit : bytes -> int -> bytes -> int -> int -> unit
153 blit src srcoff dst dstoff len copies len bytes from sequence src ,
156 starting at index srcoff , to sequence dst , starting at index dstoff .
157 It works correctly even if src and dst are the same byte sequence, and
158 the source and destination intervals overlap.
159 Raises Invalid_argument if srcoff and len do not designate a valid
162 range of src , or if dstoff and len do not designate a valid range of
163 dst .
164 val blit_string : string -> int -> bytes -> int -> int -> unit
168 blit_string src srcoff dst dstoff len copies len bytes from string src
171 , starting at index srcoff , to byte sequence dst , starting at index
172 dstoff .
173 Raises Invalid_argument if srcoff and len do not designate a valid
176 range of src , or if dstoff and len do not designate a valid range of
177 dst .
178 val concat : bytes -> bytes list -> bytes
182 concat sep sl concatenates the list of byte sequences sl , inserting
185 the separator byte sequence sep between each, and returns the result as
186 a new byte sequence.
187 Raises Invalid_argument if the result is longer than
190 Sys.max_string_length bytes.
191 val cat : bytes -> bytes -> bytes
195 cat s1 s2 concatenates s1 and s2 and returns the result as a new byte
198 sequence.
199 Raises Invalid_argument if the result is longer than
202 Sys.max_string_length bytes.
203 val iter : (char -> unit) -> bytes -> unit
207 iter f s applies function f in turn to all the bytes of s . It is
210 equivalent to f (get s 0); f (get s 1); ...; f (get s
211 (length s - 1)); () .
212 val iteri : (int -> char -> unit) -> bytes -> unit
216 Same as Bytes.iter , but the function is applied to the index of the
218 byte as first argument and the byte itself as second argument.
219 val map : (char -> char) -> bytes -> bytes
223 map f s applies function f in turn to all the bytes of s (in increasing
226 index order) and stores the resulting bytes in a new sequence that is
227 returned as the result.
228 val mapi : (int -> char -> char) -> bytes -> bytes
232 mapi f s calls f with each character of s and its index (in increasing
235 index order) and stores the resulting bytes in a new sequence that is
236 returned as the result.
237 val trim : bytes -> bytes
241 Return a copy of the argument, without leading and trailing whitespace.
243 The bytes regarded as whitespace are the ASCII characters ' ' , '\012'
244 , '\n' , '\r' , and '\t' .
245 val escaped : bytes -> bytes
249 Return a copy of the argument, with special characters represented by
251 escape sequences, following the lexical conventions of OCaml. All
252 characters outside the ASCII printable range (32..126) are escaped, as
253 well as backslash and double-quote.
254 Raises Invalid_argument if the result is longer than
257 Sys.max_string_length bytes.
258 val index : bytes -> char -> int
262 index s c returns the index of the first occurrence of byte c in s .
265 Raises Not_found if c does not occur in s .
268 val index_opt : bytes -> char -> int option
272 index_opt s c returns the index of the first occurrence of byte c in s
275 or None if c does not occur in s .
276 Since 4.05
279 val rindex : bytes -> char -> int
283 rindex s c returns the index of the last occurrence of byte c in s .
286 Raises Not_found if c does not occur in s .
289 val rindex_opt : bytes -> char -> int option
293 rindex_opt s c returns the index of the last occurrence of byte c in s
296 or None if c does not occur in s .
297 Since 4.05
300 val index_from : bytes -> int -> char -> int
304 index_from s i c returns the index of the first occurrence of byte c in
307 s after position i . Bytes.index s c is equivalent to Bytes.index_from
308 s 0 c .
309 Raises Invalid_argument if i is not a valid position in s .
312 Raises Not_found if c does not occur in s after position i .
315 val index_from_opt : bytes -> int -> char -> int option
319 index_from_opt s i c returns the index of the first occurrence of byte
322 c in s after position i or None if c does not occur in s after position
323 i . Bytes.index_opt s c is equivalent to Bytes.index_from_opt s 0 c .
324 Since 4.05
327 Raises Invalid_argument if i is not a valid position in s .
330 val rindex_from : bytes -> int -> char -> int
334 rindex_from s i c returns the index of the last occurrence of byte c in
337 s before position i+1 . rindex s c is equivalent to rindex_from s
338 (Bytes.length s - 1) c .
339 Raises Invalid_argument if i+1 is not a valid position in s .
342 Raises Not_found if c does not occur in s before position i+1 .
345 val rindex_from_opt : bytes -> int -> char -> int option
349 rindex_from_opt s i c returns the index of the last occurrence of byte
352 c in s before position i+1 or None if c does not occur in s before
353 position i+1 . rindex_opt s c is equivalent to rindex_from s
354 (Bytes.length s - 1) c .
355 Since 4.05
358 Raises Invalid_argument if i+1 is not a valid position in s .
361 val contains : bytes -> char -> bool
365 contains s c tests if byte c appears in s .
368 val contains_from : bytes -> int -> char -> bool
372 contains_from s start c tests if byte c appears in s after position
375 start . contains s c is equivalent to contains_from
376 s 0 c .
377 Raises Invalid_argument if start is not a valid position in s .
380 val rcontains_from : bytes -> int -> char -> bool
384 rcontains_from s stop c tests if byte c appears in s before position
387 stop+1 .
388 Raises Invalid_argument if stop < 0 or stop+1 is not a valid position
391 in s .
392 val uppercase : bytes -> bytes
396 Deprecated. Functions operating on Latin-1 character set are depre‐
398 cated.
399 Return a copy of the argument, with all lowercase letters translated to
402 uppercase, including accented letters of the ISO Latin-1 (8859-1) char‐
403 acter set.
404 val lowercase : bytes -> bytes
408 Deprecated. Functions operating on Latin-1 character set are depre‐
410 cated.
411 Return a copy of the argument, with all uppercase letters translated to
414 lowercase, including accented letters of the ISO Latin-1 (8859-1) char‐
415 acter set.
416 val capitalize : bytes -> bytes
420 Deprecated. Functions operating on Latin-1 character set are depre‐
422 cated.
423 Return a copy of the argument, with the first character set to upper‐
426 case, using the ISO Latin-1 (8859-1) character set..
427 val uncapitalize : bytes -> bytes
431 Deprecated. Functions operating on Latin-1 character set are depre‐
433 cated.
434 Return a copy of the argument, with the first character set to lower‐
437 case, using the ISO Latin-1 (8859-1) character set..
438 val uppercase_ascii : bytes -> bytes
442 Return a copy of the argument, with all lowercase letters translated to
444 uppercase, using the US-ASCII character set.
445 Since 4.03.0
448 val lowercase_ascii : bytes -> bytes
452 Return a copy of the argument, with all uppercase letters translated to
454 lowercase, using the US-ASCII character set.
455 Since 4.03.0
458 val capitalize_ascii : bytes -> bytes
462 Return a copy of the argument, with the first character set to upper‐
464 case, using the US-ASCII character set.
465 Since 4.03.0
468 val uncapitalize_ascii : bytes -> bytes
472 Return a copy of the argument, with the first character set to lower‐
474 case, using the US-ASCII character set.
475 Since 4.03.0
478 type t = bytes
481 An alias for the type of byte sequences.
484 val compare : t -> t -> int
488 The comparison function for byte sequences, with the same specification
490 as compare . Along with the type t , this function compare allows the
491 module Bytes to be passed as argument to the functors Set.Make and
492 Map.Make .
493 val equal : t -> t -> bool
497 The equality function for byte sequences.
499 Since 4.03.0
502 Unsafe conversions (for advanced users)
507 This section describes unsafe, low-level conversion functions between
508 bytes and string . They do not copy the internal data; used improperly,
509 they can break the immutability invariant on strings provided by the
510 -safe-string option. They are available for expert library authors, but
511 for most purposes you should use the always-correct Bytes.to_string and
512 Bytes.of_string instead.
513 val unsafe_to_string : bytes -> string
515 Unsafely convert a byte sequence into a string.
517 To reason about the use of unsafe_to_string , it is convenient to con‐
519 sider an "ownership" discipline. A piece of code that manipulates some
520 data "owns" it; there are several disjoint ownership modes, including:
521 -Unique ownership: the data may be accessed and mutated
523 -Shared ownership: the data has several owners, that may only access
525 it, not mutate it.
526 Unique ownership is linear: passing the data to another piece of code
528 means giving up ownership (we cannot write the data again). A unique
529 owner may decide to make the data shared (giving up mutation rights on
530 it), but shared data may not become uniquely-owned again.
531 unsafe_to_string s can only be used when the caller owns the byte
534 sequence s -- either uniquely or as shared immutable data. The caller
535 gives up ownership of s , and gains ownership of the returned string.
536 There are two valid use-cases that respect this ownership discipline:
538 1. Creating a string by initializing and mutating a byte sequence that
540 is never changed after initialization is performed.
541 let string_init len f : string =
544 let s = Bytes.create len in
545 for i = 0 to len - 1 do Bytes.set s i (f i) done;
546 Bytes.unsafe_to_string s
547 This function is safe because the byte sequence s will never be
550 accessed or mutated after unsafe_to_string is called. The string_init
551 code gives up ownership of s , and returns the ownership of the result‐
552 ing string to its caller.
553 Note that it would be unsafe if s was passed as an additional parameter
555 to the function f as it could escape this way and be mutated in the
556 future -- string_init would give up ownership of s to pass it to f ,
557 and could not call unsafe_to_string safely.
558 We have provided the String.init , String.map and String.mapi functions
560 to cover most cases of building new strings. You should prefer those
561 over to_string or unsafe_to_string whenever applicable.
562 2. Temporarily giving ownership of a byte sequence to a function that
564 expects a uniquely owned string and returns ownership back, so that we
565 can mutate the sequence again after the call ended.
566 let bytes_length (s : bytes) =
569 String.length (Bytes.unsafe_to_string s)
570 In this use-case, we do not promise that s will never be mutated after
573 the call to bytes_length s . The String.length function temporarily
574 borrows unique ownership of the byte sequence (and sees it as a string
575 ), but returns this ownership back to the caller, which may assume that
576 s is still a valid byte sequence after the call. Note that this is only
577 correct because we know that String.length does not capture its argu‐
578 ment -- it could escape by a side-channel such as a memoization combi‐
579 nator.
580 The caller may not mutate s while the string is borrowed (it has tempo‐
582 rarily given up ownership). This affects concurrent programs, but also
583 higher-order functions: if String.length returned a closure to be
584 called later, s should not be mutated until this closure is fully
585 applied and returns ownership.
586 val unsafe_of_string : string -> bytes
590 Unsafely convert a shared string to a byte sequence that should not be
592 mutated.
593 The same ownership discipline that makes unsafe_to_string correct
595 applies to unsafe_of_string : you may use it if you were the owner of
596 the string value, and you will own the return bytes in the same mode.
597 In practice, unique ownership of string values is extremely difficult
599 to reason about correctly. You should always assume strings are shared,
600 never uniquely owned.
601 For example, string literals are implicitly shared by the compiler, so
603 you never uniquely own them.
604 let incorrect = Bytes.unsafe_of_string "hello"
607 let s = Bytes.of_string "hello"
608 The first declaration is incorrect, because the string literal "hello"
611 could be shared by the compiler with other parts of the program, and
612 mutating incorrect is a bug. You must always use the second version,
613 which performs a copy and is thus correct.
614 Assuming unique ownership of strings that are not string literals, but
616 are (partly) built from string literals, is also incorrect. For exam‐
617 ple, mutating unsafe_of_string ("foo" ^ s) could mutate the shared
618 string "foo" -- assuming a rope-like representation of strings. More
619 generally, functions operating on strings will assume shared ownership,
620 they do not preserve unique ownership. It is thus incorrect to assume
621 unique ownership of the result of unsafe_of_string .
622 The only case we have reasonable confidence is safe is if the produced
624 bytes is shared -- used as an immutable byte sequence. This is possibly
625 useful for incremental migration of low-level programs that manipulate
626 immutable sequences of bytes (for example Marshal.from_bytes ) and pre‐
627 viously used the string type for this purpose.
628 Iterators
633 val to_seq : t -> char Seq.t
634 Iterate on the string, in increasing index order. Modifications of the
636 string during iteration will be reflected in the iterator.
637 Since 4.07
640 val to_seqi : t -> (int * char) Seq.t
644 Iterate on the string, in increasing order, yielding indices along
646 chars
647 Since 4.07
650 val of_seq : char Seq.t -> t
654 Create a string from the generator
656 Since 4.07
659 Binary encoding/decoding of integers
664 The functions in this section binary encode and decode integers to and
665 from byte sequences.
666 All following functions raise Invalid_argument if the space needed at
668 index i to decode or encode the integer is not available.
669 Little-endian (resp. big-endian) encoding means that least (resp. most)
671 significant bytes are stored first. Big-endian is also known as net‐
672 work byte order. Native-endian encoding is either little-endian or
673 big-endian depending on Sys.big_endian .
674 32-bit and 64-bit integers are represented by the int32 and int64
676 types, which can be interpreted either as signed or unsigned numbers.
677 8-bit and 16-bit integers are represented by the int type, which has
679 more bits than the binary encoding. These extra bits are handled as
680 follows:
681 -Functions that decode signed (resp. unsigned) 8-bit or 16-bit integers
683 represented by int values sign-extend (resp. zero-extend) their result.
684 -Functions that encode 8-bit or 16-bit integers represented by int val‐
686 ues truncate their input to their least significant bytes.
687 val get_uint8 : bytes -> int -> int
690 get_uint8 b i is b 's unsigned 8-bit integer starting at byte index i .
693 Since 4.08
696 val get_int8 : bytes -> int -> int
700 get_int8 b i is b 's signed 8-bit integer starting at byte index i .
703 Since 4.08
706 val get_uint16_ne : bytes -> int -> int
710 get_uint16_ne b i is b 's native-endian unsigned 16-bit integer start‐
713 ing at byte index i .
714 Since 4.08
717 val get_uint16_be : bytes -> int -> int
721 get_uint16_be b i is b 's big-endian unsigned 16-bit integer starting
724 at byte index i .
725 Since 4.08
728 val get_uint16_le : bytes -> int -> int
732 get_uint16_le b i is b 's little-endian unsigned 16-bit integer start‐
735 ing at byte index i .
736 Since 4.08
739 val get_int16_ne : bytes -> int -> int
743 get_int16_ne b i is b 's native-endian signed 16-bit integer starting
746 at byte index i .
747 Since 4.08
750 val get_int16_be : bytes -> int -> int
754 get_int16_be b i is b 's big-endian signed 16-bit integer starting at
757 byte index i .
758 Since 4.08
761 val get_int16_le : bytes -> int -> int
765 get_int16_le b i is b 's little-endian signed 16-bit integer starting
768 at byte index i .
769 Since 4.08
772 val get_int32_ne : bytes -> int -> int32
776 get_int32_ne b i is b 's native-endian 32-bit integer starting at byte
779 index i .
780 Since 4.08
783 val get_int32_be : bytes -> int -> int32
787 get_int32_be b i is b 's big-endian 32-bit integer starting at byte
790 index i .
791 Since 4.08
794 val get_int32_le : bytes -> int -> int32
798 get_int32_le b i is b 's little-endian 32-bit integer starting at byte
801 index i .
802 Since 4.08
805 val get_int64_ne : bytes -> int -> int64
809 get_int64_ne b i is b 's native-endian 64-bit integer starting at byte
812 index i .
813 Since 4.08
816 val get_int64_be : bytes -> int -> int64
820 get_int64_be b i is b 's big-endian 64-bit integer starting at byte
823 index i .
824 Since 4.08
827 val get_int64_le : bytes -> int -> int64
831 get_int64_le b i is b 's little-endian 64-bit integer starting at byte
834 index i .
835 Since 4.08
838 val set_uint8 : bytes -> int -> int -> unit
842 set_uint8 b i v sets b 's unsigned 8-bit integer starting at byte index
845 i to v .
846 Since 4.08
849 val set_int8 : bytes -> int -> int -> unit
853 set_int8 b i v sets b 's signed 8-bit integer starting at byte index i
856 to v .
857 Since 4.08
860 val set_uint16_ne : bytes -> int -> int -> unit
864 set_uint16_ne b i v sets b 's native-endian unsigned 16-bit integer
867 starting at byte index i to v .
868 Since 4.08
871 val set_uint16_be : bytes -> int -> int -> unit
875 set_uint16_be b i v sets b 's big-endian unsigned 16-bit integer start‐
878 ing at byte index i to v .
879 Since 4.08
882 val set_uint16_le : bytes -> int -> int -> unit
886 set_uint16_le b i v sets b 's little-endian unsigned 16-bit integer
889 starting at byte index i to v .
890 Since 4.08
893 val set_int16_ne : bytes -> int -> int -> unit
897 set_int16_ne b i v sets b 's native-endian signed 16-bit integer start‐
900 ing at byte index i to v .
901 Since 4.08
904 val set_int16_be : bytes -> int -> int -> unit
908 set_int16_be b i v sets b 's big-endian signed 16-bit integer starting
911 at byte index i to v .
912 Since 4.08
915 val set_int16_le : bytes -> int -> int -> unit
919 set_int16_le b i v sets b 's little-endian signed 16-bit integer start‐
922 ing at byte index i to v .
923 Since 4.08
926 val set_int32_ne : bytes -> int -> int32 -> unit
930 set_int32_ne b i v sets b 's native-endian 32-bit integer starting at
933 byte index i to v .
934 Since 4.08
937 val set_int32_be : bytes -> int -> int32 -> unit
941 set_int32_be b i v sets b 's big-endian 32-bit integer starting at byte
944 index i to v .
945 Since 4.08
948 val set_int32_le : bytes -> int -> int32 -> unit
952 set_int32_le b i v sets b 's little-endian 32-bit integer starting at
955 byte index i to v .
956 Since 4.08
959 val set_int64_ne : bytes -> int -> int64 -> unit
963 set_int64_ne b i v sets b 's native-endian 64-bit integer starting at
966 byte index i to v .
967 Since 4.08
970 val set_int64_be : bytes -> int -> int64 -> unit
974 set_int64_be b i v sets b 's big-endian 64-bit integer starting at byte
977 index i to v .
978 Since 4.08
981 val set_int64_le : bytes -> int -> int64 -> unit
985 set_int64_le b i v sets b 's little-endian 64-bit integer starting at
988 byte index i to v .
989 Since 4.08
992OCamldoc 2020-09-01 Stdlib.Bytes(3)