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 Since 4.02.0
20 This module is intended to be used through {!StdLabels} which re‐
22 places
23 {!Array}, {!Bytes}, {!List} and {!String} with their labeled coun‐
24 terparts.
25 For example:
27 {[
28 open StdLabels
29 let first = Bytes.sub ~pos:0 ~len:1
31 ]}
32 val length : bytes -> int
39 Return the length (number of bytes) of the argument.
41 val get : bytes -> int -> char
45 get s n returns the byte at index n in argument s .
48 Raises Invalid_argument if n is not a valid index in s .
51 val set : bytes -> int -> char -> unit
55 set s n c modifies s in place, replacing the byte at index n with c .
58 Raises Invalid_argument if n is not a valid index in s .
61 val create : int -> bytes
65 create n returns a new byte sequence of length n . The sequence is
68 uninitialized and contains arbitrary bytes.
69 Raises Invalid_argument if n < 0 or n > Sys.max_string_length .
72 val make : int -> char -> bytes
76 make n c returns a new byte sequence of length n , filled with the byte
79 c .
80 Raises Invalid_argument if n < 0 or n > Sys.max_string_length .
83 val init : int -> f:(int -> char) -> bytes
87 init n f returns a fresh byte sequence of length n , with character i
90 initialized to the result of f i .
91 Raises Invalid_argument if n < 0 or n > Sys.max_string_length .
94 val empty : bytes
98 A byte sequence of size 0.
100 val copy : bytes -> bytes
104 Return a new byte sequence that contains the same bytes as the argu‐
106 ment.
107 val of_string : string -> bytes
111 Return a new byte sequence that contains the same bytes as the given
113 string.
114 val to_string : bytes -> string
118 Return a new string that contains the same bytes as the given byte se‐
120 quence.
121 val sub : bytes -> pos:int -> len:int -> bytes
125 sub s start len returns a new byte sequence of length len , containing
128 the subsequence of s that starts at position start and has length len .
129 Raises Invalid_argument if start and len do not designate a valid range
132 of s .
133 val sub_string : bytes -> pos:int -> len:int -> string
137 Same as sub but return a string instead of a byte sequence.
139 val extend : bytes -> left:int -> right:int -> bytes
143 extend s left right returns a new byte sequence that contains the bytes
146 of s , with left uninitialized bytes prepended and right uninitialized
147 bytes appended to it. If left or right is negative, then bytes are re‐
148 moved (instead of appended) from the corresponding side of s .
149 Since 4.05.0
152 Raises Invalid_argument if the result length is negative or longer than
155 Sys.max_string_length bytes.
156 val fill : bytes -> pos:int -> len:int -> char -> unit
160 fill s start len c modifies s in place, replacing len characters with c
163 , starting at start .
164 Raises Invalid_argument if start and len do not designate a valid range
167 of s .
168 val blit : src:bytes -> src_pos:int -> dst:bytes -> dst_pos:int ->
172 len:int -> unit
173 blit src srcoff dst dstoff len copies len bytes from sequence src ,
176 starting at index srcoff , to sequence dst , starting at index dstoff .
177 It works correctly even if src and dst are the same byte sequence, and
178 the source and destination intervals overlap.
179 Raises Invalid_argument if srcoff and len do not designate a valid
182 range of src , or if dstoff and len do not designate a valid range of
183 dst .
184 val blit_string : src:string -> src_pos:int -> dst:bytes -> dst_pos:int
188 -> len:int -> unit
189 blit src srcoff dst dstoff len copies len bytes from string src ,
192 starting at index srcoff , to byte sequence dst , starting at index
193 dstoff .
194 Since 4.05.0
197 Raises Invalid_argument if srcoff and len do not designate a valid
200 range of src , or if dstoff and len do not designate a valid range of
201 dst .
202 val concat : sep:bytes -> bytes list -> bytes
206 concat sep sl concatenates the list of byte sequences sl , inserting
209 the separator byte sequence sep between each, and returns the result as
210 a new byte sequence.
211 val cat : bytes -> bytes -> bytes
215 cat s1 s2 concatenates s1 and s2 and returns the result as new byte se‐
218 quence.
219 Since 4.05.0
222 Raises Invalid_argument if the result is longer than
225 Sys.max_string_length bytes.
226 val iter : f:(char -> unit) -> bytes -> unit
230 iter f s applies function f in turn to all the bytes of s . It is
233 equivalent to f (get s 0); f (get s 1); ...; f (get s
234 (length s - 1)); () .
235 val iteri : f:(int -> char -> unit) -> bytes -> unit
239 Same as Bytes.iter , but the function is applied to the index of the
241 byte as first argument and the byte itself as second argument.
242 val map : f:(char -> char) -> bytes -> bytes
246 map f s applies function f in turn to all the bytes of s and stores the
249 resulting bytes in a new sequence that is returned as the result.
250 val mapi : f:(int -> char -> char) -> bytes -> bytes
254 mapi f s calls f with each character of s and its index (in increasing
257 index order) and stores the resulting bytes in a new sequence that is
258 returned as the result.
259 val trim : bytes -> bytes
263 Return a copy of the argument, without leading and trailing whitespace.
265 The bytes regarded as whitespace are the ASCII characters ' ' , '\012'
266 , '\n' , '\r' , and '\t' .
267 val escaped : bytes -> bytes
271 Return a copy of the argument, with special characters represented by
273 escape sequences, following the lexical conventions of OCaml.
274 val index : bytes -> char -> int
278 index s c returns the index of the first occurrence of byte c in s .
281 Raises Not_found if c does not occur in s .
284 val index_opt : bytes -> char -> int option
288 index_opt s c returns the index of the first occurrence of byte c in s
291 or None if c does not occur in s .
292 Since 4.05
295 val rindex : bytes -> char -> int
299 rindex s c returns the index of the last occurrence of byte c in s .
302 Raises Not_found if c does not occur in s .
305 val rindex_opt : bytes -> char -> int option
309 rindex_opt s c returns the index of the last occurrence of byte c in s
312 or None if c does not occur in s .
313 Since 4.05
316 val index_from : bytes -> int -> char -> int
320 index_from s i c returns the index of the first occurrence of byte c in
323 s after position i . Bytes.index s c is equivalent to Bytes.index_from
324 s 0 c .
325 Raises Invalid_argument if i is not a valid position in s .
328 Raises Not_found if c does not occur in s after position i .
331 val index_from_opt : bytes -> int -> char -> int option
335 index_from _opts i c returns the index of the first occurrence of byte
338 c in s after position i or None if c does not occur in s after position
339 i . Bytes.index_opt s c is equivalent to Bytes.index_from_opt s 0 c .
340 Since 4.05
343 Raises Invalid_argument if i is not a valid position in s .
346 val rindex_from : bytes -> int -> char -> int
350 rindex_from s i c returns the index of the last occurrence of byte c in
353 s before position i+1 . rindex s c is equivalent to rindex_from s
354 (Bytes.length s - 1) c .
355 Raises Invalid_argument if i+1 is not a valid position in s .
358 Raises Not_found if c does not occur in s before position i+1 .
361 val rindex_from_opt : bytes -> int -> char -> int option
365 rindex_from_opt s i c returns the index of the last occurrence of byte
368 c in s before position i+1 or None if c does not occur in s before po‐
369 sition i+1 . rindex_opt s c is equivalent to rindex_from s
370 (Bytes.length s - 1) c .
371 Since 4.05
374 Raises Invalid_argument if i+1 is not a valid position in s .
377 val contains : bytes -> char -> bool
381 contains s c tests if byte c appears in s .
384 val contains_from : bytes -> int -> char -> bool
388 contains_from s start c tests if byte c appears in s after position
391 start . contains s c is equivalent to contains_from
392 s 0 c .
393 Raises Invalid_argument if start is not a valid position in s .
396 val rcontains_from : bytes -> int -> char -> bool
400 rcontains_from s stop c tests if byte c appears in s before position
403 stop+1 .
404 Raises Invalid_argument if stop < 0 or stop+1 is not a valid position
407 in s .
408 val uppercase : bytes -> bytes
412 Deprecated. Functions operating on Latin-1 character set are depre‐
414 cated.
415 Return a copy of the argument, with all lowercase letters translated to
418 uppercase, including accented letters of the ISO Latin-1 (8859-1) char‐
419 acter set.
420 val lowercase : bytes -> bytes
424 Deprecated. Functions operating on Latin-1 character set are depre‐
426 cated.
427 Return a copy of the argument, with all uppercase letters translated to
430 lowercase, including accented letters of the ISO Latin-1 (8859-1) char‐
431 acter set.
432 val capitalize : bytes -> bytes
436 Deprecated. Functions operating on Latin-1 character set are depre‐
438 cated.
439 Return a copy of the argument, with the first character set to upper‐
442 case, using the ISO Latin-1 (8859-1) character set..
443 val uncapitalize : bytes -> bytes
447 Deprecated. Functions operating on Latin-1 character set are depre‐
449 cated.
450 Return a copy of the argument, with the first character set to lower‐
453 case, using the ISO Latin-1 (8859-1) character set..
454 val uppercase_ascii : bytes -> bytes
458 Return a copy of the argument, with all lowercase letters translated to
460 uppercase, using the US-ASCII character set.
461 Since 4.05.0
464 val lowercase_ascii : bytes -> bytes
468 Return a copy of the argument, with all uppercase letters translated to
470 lowercase, using the US-ASCII character set.
471 Since 4.05.0
474 val capitalize_ascii : bytes -> bytes
478 Return a copy of the argument, with the first character set to upper‐
480 case, using the US-ASCII character set.
481 Since 4.05.0
484 val uncapitalize_ascii : bytes -> bytes
488 Return a copy of the argument, with the first character set to lower‐
490 case, using the US-ASCII character set.
491 Since 4.05.0
494 type t = bytes
497 An alias for the type of byte sequences.
500 val compare : t -> t -> int
504 The comparison function for byte sequences, with the same specification
506 as compare . Along with the type t , this function compare allows the
507 module Bytes to be passed as argument to the functors Set.Make and
508 Map.Make .
509 val equal : t -> t -> bool
513 The equality function for byte sequences.
515 Since 4.05.0
518 Iterators
523 val to_seq : t -> char Seq.t
524 Iterate on the string, in increasing index order. Modifications of the
526 string during iteration will be reflected in the iterator.
527 Since 4.07
530 val to_seqi : t -> (int * char) Seq.t
534 Iterate on the string, in increasing order, yielding indices along
536 chars
537 Since 4.07
540 val of_seq : char Seq.t -> t
544 Create a string from the generator
546 Since 4.07
549 Binary encoding/decoding of integers
554 The functions in this section binary encode and decode integers to and
555 from byte sequences.
556 All following functions raise Invalid_argument if the space needed at
558 index i to decode or encode the integer is not available.
559 Little-endian (resp. big-endian) encoding means that least (resp. most)
561 significant bytes are stored first. Big-endian is also known as net‐
562 work byte order. Native-endian encoding is either little-endian or
563 big-endian depending on Sys.big_endian .
564 32-bit and 64-bit integers are represented by the int32 and int64
566 types, which can be interpreted either as signed or unsigned numbers.
567 8-bit and 16-bit integers are represented by the int type, which has
569 more bits than the binary encoding. These extra bits are handled as
570 follows:
571 -Functions that decode signed (resp. unsigned) 8-bit or 16-bit integers
573 represented by int values sign-extend (resp. zero-extend) their result.
574 -Functions that encode 8-bit or 16-bit integers represented by int val‐
576 ues truncate their input to their least significant bytes.
577 val get_uint8 : bytes -> int -> int
580 get_uint8 b i is b 's unsigned 8-bit integer starting at byte index i .
583 Since 4.08
586 val get_int8 : bytes -> int -> int
590 get_int8 b i is b 's signed 8-bit integer starting at byte index i .
593 Since 4.08
596 val get_uint16_ne : bytes -> int -> int
600 get_uint16_ne b i is b 's native-endian unsigned 16-bit integer start‐
603 ing at byte index i .
604 Since 4.08
607 val get_uint16_be : bytes -> int -> int
611 get_uint16_be b i is b 's big-endian unsigned 16-bit integer starting
614 at byte index i .
615 Since 4.08
618 val get_uint16_le : bytes -> int -> int
622 get_uint16_le b i is b 's little-endian unsigned 16-bit integer start‐
625 ing at byte index i .
626 Since 4.08
629 val get_int16_ne : bytes -> int -> int
633 get_int16_ne b i is b 's native-endian signed 16-bit integer starting
636 at byte index i .
637 Since 4.08
640 val get_int16_be : bytes -> int -> int
644 get_int16_be b i is b 's big-endian signed 16-bit integer starting at
647 byte index i .
648 Since 4.08
651 val get_int16_le : bytes -> int -> int
655 get_int16_le b i is b 's little-endian signed 16-bit integer starting
658 at byte index i .
659 Since 4.08
662 val get_int32_ne : bytes -> int -> int32
666 get_int32_ne b i is b 's native-endian 32-bit integer starting at byte
669 index i .
670 Since 4.08
673 val get_int32_be : bytes -> int -> int32
677 get_int32_be b i is b 's big-endian 32-bit integer starting at byte in‐
680 dex i .
681 Since 4.08
684 val get_int32_le : bytes -> int -> int32
688 get_int32_le b i is b 's little-endian 32-bit integer starting at byte
691 index i .
692 Since 4.08
695 val get_int64_ne : bytes -> int -> int64
699 get_int64_ne b i is b 's native-endian 64-bit integer starting at byte
702 index i .
703 Since 4.08
706 val get_int64_be : bytes -> int -> int64
710 get_int64_be b i is b 's big-endian 64-bit integer starting at byte in‐
713 dex i .
714 Since 4.08
717 val get_int64_le : bytes -> int -> int64
721 get_int64_le b i is b 's little-endian 64-bit integer starting at byte
724 index i .
725 Since 4.08
728 val set_uint8 : bytes -> int -> int -> unit
732 set_uint8 b i v sets b 's unsigned 8-bit integer starting at byte index
735 i to v .
736 Since 4.08
739 val set_int8 : bytes -> int -> int -> unit
743 set_int8 b i v sets b 's signed 8-bit integer starting at byte index i
746 to v .
747 Since 4.08
750 val set_uint16_ne : bytes -> int -> int -> unit
754 set_uint16_ne b i v sets b 's native-endian unsigned 16-bit integer
757 starting at byte index i to v .
758 Since 4.08
761 val set_uint16_be : bytes -> int -> int -> unit
765 set_uint16_be b i v sets b 's big-endian unsigned 16-bit integer start‐
768 ing at byte index i to v .
769 Since 4.08
772 val set_uint16_le : bytes -> int -> int -> unit
776 set_uint16_le b i v sets b 's little-endian unsigned 16-bit integer
779 starting at byte index i to v .
780 Since 4.08
783 val set_int16_ne : bytes -> int -> int -> unit
787 set_int16_ne b i v sets b 's native-endian signed 16-bit integer start‐
790 ing at byte index i to v .
791 Since 4.08
794 val set_int16_be : bytes -> int -> int -> unit
798 set_int16_be b i v sets b 's big-endian signed 16-bit integer starting
801 at byte index i to v .
802 Since 4.08
805 val set_int16_le : bytes -> int -> int -> unit
809 set_int16_le b i v sets b 's little-endian signed 16-bit integer start‐
812 ing at byte index i to v .
813 Since 4.08
816 val set_int32_ne : bytes -> int -> int32 -> unit
820 set_int32_ne b i v sets b 's native-endian 32-bit integer starting at
823 byte index i to v .
824 Since 4.08
827 val set_int32_be : bytes -> int -> int32 -> unit
831 set_int32_be b i v sets b 's big-endian 32-bit integer starting at byte
834 index i to v .
835 Since 4.08
838 val set_int32_le : bytes -> int -> int32 -> unit
842 set_int32_le b i v sets b 's little-endian 32-bit integer starting at
845 byte index i to v .
846 Since 4.08
849 val set_int64_ne : bytes -> int -> int64 -> unit
853 set_int64_ne b i v sets b 's native-endian 64-bit integer starting at
856 byte index i to v .
857 Since 4.08
860 val set_int64_be : bytes -> int -> int64 -> unit
864 set_int64_be b i v sets b 's big-endian 64-bit integer starting at byte
867 index i to v .
868 Since 4.08
871 val set_int64_le : bytes -> int -> int64 -> unit
875 set_int64_le b i v sets b 's little-endian 64-bit integer starting at
878 byte index i to v .
879 Since 4.08
882OCamldoc 2021-01-26 BytesLabels(3)