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 trim : bytes -> bytes
252 Return a copy of the argument, without leading and trailing whitespace.
254 The bytes regarded as whitespace are the ASCII characters ' ' , '\012'
255 , '\n' , '\r' , and '\t' .
256 val escaped : bytes -> bytes
260 Return a copy of the argument, with special characters represented by
262 escape sequences, following the lexical conventions of OCaml. All
263 characters outside the ASCII printable range (32..126) are escaped, as
264 well as backslash and double-quote.
265 Raises Invalid_argument if the result is longer than
268 Sys.max_string_length bytes.
269 val index : bytes -> char -> int
273 index s c returns the index of the first occurrence of byte c in s .
276 Raises Not_found if c does not occur in s .
279 val index_opt : bytes -> char -> int option
283 index_opt s c returns the index of the first occurrence of byte c in s
286 or None if c does not occur in s .
287 Since 4.05
290 val rindex : bytes -> char -> int
294 rindex s c returns the index of the last occurrence of byte c in s .
297 Raises Not_found if c does not occur in s .
300 val rindex_opt : bytes -> char -> int option
304 rindex_opt s c returns the index of the last occurrence of byte c in s
307 or None if c does not occur in s .
308 Since 4.05
311 val index_from : bytes -> int -> char -> int
315 index_from s i c returns the index of the first occurrence of byte c in
318 s after position i . index s c is equivalent to index_from s 0 c .
319 Raises Invalid_argument if i is not a valid position in s .
322 Raises Not_found if c does not occur in s after position i .
325 val index_from_opt : bytes -> int -> char -> int option
329 index_from_opt s i c returns the index of the first occurrence of byte
332 c in s after position i or None if c does not occur in s after position
333 i . index_opt s c is equivalent to index_from_opt s 0 c .
334 Since 4.05
337 Raises Invalid_argument if i is not a valid position in s .
340 val rindex_from : bytes -> int -> char -> int
344 rindex_from s i c returns the index of the last occurrence of byte c in
347 s before position i+1 . rindex s c is equivalent to rindex_from s
348 (length s - 1) c .
349 Raises Invalid_argument if i+1 is not a valid position in s .
352 Raises Not_found if c does not occur in s before position i+1 .
355 val rindex_from_opt : bytes -> int -> char -> int option
359 rindex_from_opt s i c returns the index of the last occurrence of byte
362 c in s before position i+1 or None if c does not occur in s before po‐
363 sition i+1 . rindex_opt s c is equivalent to rindex_from s (length s -
364 1) c .
365 Since 4.05
368 Raises Invalid_argument if i+1 is not a valid position in s .
371 val contains : bytes -> char -> bool
375 contains s c tests if byte c appears in s .
378 val contains_from : bytes -> int -> char -> bool
382 contains_from s start c tests if byte c appears in s after position
385 start . contains s c is equivalent to contains_from
386 s 0 c .
387 Raises Invalid_argument if start is not a valid position in s .
390 val rcontains_from : bytes -> int -> char -> bool
394 rcontains_from s stop c tests if byte c appears in s before position
397 stop+1 .
398 Raises Invalid_argument if stop < 0 or stop+1 is not a valid position
401 in s .
402 val uppercase : bytes -> bytes
406 Deprecated. Functions operating on Latin-1 character set are depre‐
408 cated.
409 Return a copy of the argument, with all lowercase letters translated to
412 uppercase, including accented letters of the ISO Latin-1 (8859-1) char‐
413 acter set.
414 val lowercase : bytes -> bytes
418 Deprecated. Functions operating on Latin-1 character set are depre‐
420 cated.
421 Return a copy of the argument, with all uppercase letters translated to
424 lowercase, including accented letters of the ISO Latin-1 (8859-1) char‐
425 acter set.
426 val capitalize : bytes -> bytes
430 Deprecated. Functions operating on Latin-1 character set are depre‐
432 cated.
433 Return a copy of the argument, with the first character set to upper‐
436 case, using the ISO Latin-1 (8859-1) character set.
437 val uncapitalize : bytes -> bytes
441 Deprecated. Functions operating on Latin-1 character set are depre‐
443 cated.
444 Return a copy of the argument, with the first character set to lower‐
447 case, using the ISO Latin-1 (8859-1) character set.
448 val uppercase_ascii : bytes -> bytes
452 Return a copy of the argument, with all lowercase letters translated to
454 uppercase, using the US-ASCII character set.
455 Since 4.05.0
458 val lowercase_ascii : bytes -> bytes
462 Return a copy of the argument, with all uppercase letters translated to
464 lowercase, using the US-ASCII character set.
465 Since 4.05.0
468 val capitalize_ascii : bytes -> bytes
472 Return a copy of the argument, with the first character set to upper‐
474 case, using the US-ASCII character set.
475 Since 4.05.0
478 val uncapitalize_ascii : bytes -> bytes
482 Return a copy of the argument, with the first character set to lower‐
484 case, using the US-ASCII character set.
485 Since 4.05.0
488 type t = bytes
491 An alias for the type of byte sequences.
494 val compare : t -> t -> int
498 The comparison function for byte sequences, with the same specification
500 as compare . Along with the type t , this function compare allows the
501 module Bytes to be passed as argument to the functors Set.Make and
502 Map.Make .
503 val equal : t -> t -> bool
507 The equality function for byte sequences.
509 Since 4.05.0
512 Unsafe conversions (for advanced users)
517 This section describes unsafe, low-level conversion functions between
518 bytes and string . They do not copy the internal data; used improperly,
519 they can break the immutability invariant on strings provided by the
520 -safe-string option. They are available for expert library authors, but
521 for most purposes you should use the always-correct BytesLa‐
522 bels.to_string and BytesLabels.of_string instead.
523 val unsafe_to_string : bytes -> string
525 Unsafely convert a byte sequence into a string.
527 To reason about the use of unsafe_to_string , it is convenient to con‐
529 sider an "ownership" discipline. A piece of code that manipulates some
530 data "owns" it; there are several disjoint ownership modes, including:
531 -Unique ownership: the data may be accessed and mutated
533 -Shared ownership: the data has several owners, that may only access
535 it, not mutate it.
536 Unique ownership is linear: passing the data to another piece of code
538 means giving up ownership (we cannot write the data again). A unique
539 owner may decide to make the data shared (giving up mutation rights on
540 it), but shared data may not become uniquely-owned again.
541 unsafe_to_string s can only be used when the caller owns the byte se‐
544 quence s -- either uniquely or as shared immutable data. The caller
545 gives up ownership of s , and gains ownership of the returned string.
546 There are two valid use-cases that respect this ownership discipline:
548 1. Creating a string by initializing and mutating a byte sequence that
550 is never changed after initialization is performed.
551 let string_init len f : string =
554 let s = Bytes.create len in
555 for i = 0 to len - 1 do Bytes.set s i (f i) done;
556 Bytes.unsafe_to_string s
557 This function is safe because the byte sequence s will never be ac‐
560 cessed or mutated after unsafe_to_string is called. The string_init
561 code gives up ownership of s , and returns the ownership of the result‐
562 ing string to its caller.
563 Note that it would be unsafe if s was passed as an additional parameter
565 to the function f as it could escape this way and be mutated in the fu‐
566 ture -- string_init would give up ownership of s to pass it to f , and
567 could not call unsafe_to_string safely.
568 We have provided the String.init , String.map and String.mapi functions
570 to cover most cases of building new strings. You should prefer those
571 over to_string or unsafe_to_string whenever applicable.
572 2. Temporarily giving ownership of a byte sequence to a function that
574 expects a uniquely owned string and returns ownership back, so that we
575 can mutate the sequence again after the call ended.
576 let bytes_length (s : bytes) =
579 String.length (Bytes.unsafe_to_string s)
580 In this use-case, we do not promise that s will never be mutated after
583 the call to bytes_length s . The String.length function temporarily
584 borrows unique ownership of the byte sequence (and sees it as a string
585 ), but returns this ownership back to the caller, which may assume that
586 s is still a valid byte sequence after the call. Note that this is only
587 correct because we know that String.length does not capture its argu‐
588 ment -- it could escape by a side-channel such as a memoization combi‐
589 nator.
590 The caller may not mutate s while the string is borrowed (it has tempo‐
592 rarily given up ownership). This affects concurrent programs, but also
593 higher-order functions: if String.length returned a closure to be
594 called later, s should not be mutated until this closure is fully ap‐
595 plied and returns ownership.
596 val unsafe_of_string : string -> bytes
600 Unsafely convert a shared string to a byte sequence that should not be
602 mutated.
603 The same ownership discipline that makes unsafe_to_string correct ap‐
605 plies to unsafe_of_string : you may use it if you were the owner of the
606 string value, and you will own the return bytes in the same mode.
607 In practice, unique ownership of string values is extremely difficult
609 to reason about correctly. You should always assume strings are shared,
610 never uniquely owned.
611 For example, string literals are implicitly shared by the compiler, so
613 you never uniquely own them.
614 let incorrect = Bytes.unsafe_of_string "hello"
617 let s = Bytes.of_string "hello"
618 The first declaration is incorrect, because the string literal "hello"
621 could be shared by the compiler with other parts of the program, and
622 mutating incorrect is a bug. You must always use the second version,
623 which performs a copy and is thus correct.
624 Assuming unique ownership of strings that are not string literals, but
626 are (partly) built from string literals, is also incorrect. For exam‐
627 ple, mutating unsafe_of_string ("foo" ^ s) could mutate the shared
628 string "foo" -- assuming a rope-like representation of strings. More
629 generally, functions operating on strings will assume shared ownership,
630 they do not preserve unique ownership. It is thus incorrect to assume
631 unique ownership of the result of unsafe_of_string .
632 The only case we have reasonable confidence is safe is if the produced
634 bytes is shared -- used as an immutable byte sequence. This is possibly
635 useful for incremental migration of low-level programs that manipulate
636 immutable sequences of bytes (for example Marshal.from_bytes ) and pre‐
637 viously used the string type for this purpose.
638 Iterators
643 val to_seq : t -> char Seq.t
644 Iterate on the string, in increasing index order. Modifications of the
646 string during iteration will be reflected in the iterator.
647 Since 4.07
650 val to_seqi : t -> (int * char) Seq.t
654 Iterate on the string, in increasing order, yielding indices along
656 chars
657 Since 4.07
660 val of_seq : char Seq.t -> t
664 Create a string from the generator
666 Since 4.07
669 Binary encoding/decoding of integers
674 The functions in this section binary encode and decode integers to and
675 from byte sequences.
676 All following functions raise Invalid_argument if the space needed at
678 index i to decode or encode the integer is not available.
679 Little-endian (resp. big-endian) encoding means that least (resp. most)
681 significant bytes are stored first. Big-endian is also known as net‐
682 work byte order. Native-endian encoding is either little-endian or
683 big-endian depending on Sys.big_endian .
684 32-bit and 64-bit integers are represented by the int32 and int64
686 types, which can be interpreted either as signed or unsigned numbers.
687 8-bit and 16-bit integers are represented by the int type, which has
689 more bits than the binary encoding. These extra bits are handled as
690 follows:
691 -Functions that decode signed (resp. unsigned) 8-bit or 16-bit integers
693 represented by int values sign-extend (resp. zero-extend) their result.
694 -Functions that encode 8-bit or 16-bit integers represented by int val‐
696 ues truncate their input to their least significant bytes.
697 val get_uint8 : bytes -> int -> int
700 get_uint8 b i is b 's unsigned 8-bit integer starting at byte index i .
703 Since 4.08
706 val get_int8 : bytes -> int -> int
710 get_int8 b i is b 's signed 8-bit integer starting at byte index i .
713 Since 4.08
716 val get_uint16_ne : bytes -> int -> int
720 get_uint16_ne b i is b 's native-endian unsigned 16-bit integer start‐
723 ing at byte index i .
724 Since 4.08
727 val get_uint16_be : bytes -> int -> int
731 get_uint16_be b i is b 's big-endian unsigned 16-bit integer starting
734 at byte index i .
735 Since 4.08
738 val get_uint16_le : bytes -> int -> int
742 get_uint16_le b i is b 's little-endian unsigned 16-bit integer start‐
745 ing at byte index i .
746 Since 4.08
749 val get_int16_ne : bytes -> int -> int
753 get_int16_ne b i is b 's native-endian signed 16-bit integer starting
756 at byte index i .
757 Since 4.08
760 val get_int16_be : bytes -> int -> int
764 get_int16_be b i is b 's big-endian signed 16-bit integer starting at
767 byte index i .
768 Since 4.08
771 val get_int16_le : bytes -> int -> int
775 get_int16_le b i is b 's little-endian signed 16-bit integer starting
778 at byte index i .
779 Since 4.08
782 val get_int32_ne : bytes -> int -> int32
786 get_int32_ne b i is b 's native-endian 32-bit integer starting at byte
789 index i .
790 Since 4.08
793 val get_int32_be : bytes -> int -> int32
797 get_int32_be b i is b 's big-endian 32-bit integer starting at byte in‐
800 dex i .
801 Since 4.08
804 val get_int32_le : bytes -> int -> int32
808 get_int32_le b i is b 's little-endian 32-bit integer starting at byte
811 index i .
812 Since 4.08
815 val get_int64_ne : bytes -> int -> int64
819 get_int64_ne b i is b 's native-endian 64-bit integer starting at byte
822 index i .
823 Since 4.08
826 val get_int64_be : bytes -> int -> int64
830 get_int64_be b i is b 's big-endian 64-bit integer starting at byte in‐
833 dex i .
834 Since 4.08
837 val get_int64_le : bytes -> int -> int64
841 get_int64_le b i is b 's little-endian 64-bit integer starting at byte
844 index i .
845 Since 4.08
848 val set_uint8 : bytes -> int -> int -> unit
852 set_uint8 b i v sets b 's unsigned 8-bit integer starting at byte index
855 i to v .
856 Since 4.08
859 val set_int8 : bytes -> int -> int -> unit
863 set_int8 b i v sets b 's signed 8-bit integer starting at byte index i
866 to v .
867 Since 4.08
870 val set_uint16_ne : bytes -> int -> int -> unit
874 set_uint16_ne b i v sets b 's native-endian unsigned 16-bit integer
877 starting at byte index i to v .
878 Since 4.08
881 val set_uint16_be : bytes -> int -> int -> unit
885 set_uint16_be b i v sets b 's big-endian unsigned 16-bit integer start‐
888 ing at byte index i to v .
889 Since 4.08
892 val set_uint16_le : bytes -> int -> int -> unit
896 set_uint16_le b i v sets b 's little-endian unsigned 16-bit integer
899 starting at byte index i to v .
900 Since 4.08
903 val set_int16_ne : bytes -> int -> int -> unit
907 set_int16_ne b i v sets b 's native-endian signed 16-bit integer start‐
910 ing at byte index i to v .
911 Since 4.08
914 val set_int16_be : bytes -> int -> int -> unit
918 set_int16_be b i v sets b 's big-endian signed 16-bit integer starting
921 at byte index i to v .
922 Since 4.08
925 val set_int16_le : bytes -> int -> int -> unit
929 set_int16_le b i v sets b 's little-endian signed 16-bit integer start‐
932 ing at byte index i to v .
933 Since 4.08
936 val set_int32_ne : bytes -> int -> int32 -> unit
940 set_int32_ne b i v sets b 's native-endian 32-bit integer starting at
943 byte index i to v .
944 Since 4.08
947 val set_int32_be : bytes -> int -> int32 -> unit
951 set_int32_be b i v sets b 's big-endian 32-bit integer starting at byte
954 index i to v .
955 Since 4.08
958 val set_int32_le : bytes -> int -> int32 -> unit
962 set_int32_le b i v sets b 's little-endian 32-bit integer starting at
965 byte index i to v .
966 Since 4.08
969 val set_int64_ne : bytes -> int -> int64 -> unit
973 set_int64_ne b i v sets b 's native-endian 64-bit integer starting at
976 byte index i to v .
977 Since 4.08
980 val set_int64_be : bytes -> int -> int64 -> unit
984 set_int64_be b i v sets b 's big-endian 64-bit integer starting at byte
987 index i to v .
988 Since 4.08
991 val set_int64_le : bytes -> int -> int64 -> unit
995 set_int64_le b i v sets b 's little-endian 64-bit integer starting at
998 byte index i to v .
999 Since 4.08
1002OCamldoc 2021-07-22 Stdlib.BytesLabels(3)