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
22 replaces
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 Raise Invalid_argument if n is not a valid index in s .
50 val set : bytes -> int -> char -> unit
54 set s n c modifies s in place, replacing the byte at index n with c .
57 Raise Invalid_argument if n is not a valid index in s .
59 val create : int -> bytes
63 create n returns a new byte sequence of length n . The sequence is
66 uninitialized and contains arbitrary bytes.
67 Raise Invalid_argument if n < 0 or n > Sys.max_string_length .
69 val make : int -> char -> bytes
73 make n c returns a new byte sequence of length n , filled with the byte
76 c .
77 Raise Invalid_argument if n < 0 or n > Sys.max_string_length .
79 val init : int -> f:(int -> char) -> bytes
83 init n f returns a fresh byte sequence of length n , with character i
86 initialized to the result of f i .
87 Raise Invalid_argument if n < 0 or n > Sys.max_string_length .
89 val empty : bytes
93 A byte sequence of size 0.
95 val copy : bytes -> bytes
99 Return a new byte sequence that contains the same bytes as the argu‐
101 ment.
102 val of_string : string -> bytes
106 Return a new byte sequence that contains the same bytes as the given
108 string.
109 val to_string : bytes -> string
113 Return a new string that contains the same bytes as the given byte
115 sequence.
116 val sub : bytes -> pos:int -> len:int -> bytes
120 sub s start len returns a new byte sequence of length len , containing
123 the subsequence of s that starts at position start and has length len .
124 Raise Invalid_argument if start and len do not designate a valid range
126 of s .
127 val sub_string : bytes -> pos:int -> len:int -> string
131 Same as sub but return a string instead of a byte sequence.
133 val extend : bytes -> left:int -> right:int -> bytes
137 extend s left right returns a new byte sequence that contains the bytes
140 of s , with left uninitialized bytes prepended and right uninitialized
141 bytes appended to it. If left or right is negative, then bytes are
142 removed (instead of appended) from the corresponding side of s .
143 Raise Invalid_argument if the result length is negative or longer than
145 Sys.max_string_length bytes.
146 Since 4.05.0
149 val fill : bytes -> pos:int -> len:int -> char -> unit
153 fill s start len c modifies s in place, replacing len characters with c
156 , starting at start .
157 Raise Invalid_argument if start and len do not designate a valid range
159 of s .
160 val blit : src:bytes -> src_pos:int -> dst:bytes -> dst_pos:int ->
164 len:int -> unit
165 blit src srcoff dst dstoff len copies len bytes from sequence src ,
168 starting at index srcoff , to sequence dst , starting at index dstoff .
169 It works correctly even if src and dst are the same byte sequence, and
170 the source and destination intervals overlap.
171 Raise Invalid_argument if srcoff and len do not designate a valid range
173 of src , or if dstoff and len do not designate a valid range of dst .
174 val blit_string : src:string -> src_pos:int -> dst:bytes -> dst_pos:int
178 -> len:int -> unit
179 blit src srcoff dst dstoff len copies len bytes from string src ,
182 starting at index srcoff , to byte sequence dst , starting at index
183 dstoff .
184 Raise Invalid_argument if srcoff and len do not designate a valid range
186 of src , or if dstoff and len do not designate a valid range of dst .
187 Since 4.05.0
190 val concat : sep:bytes -> bytes list -> bytes
194 concat sep sl concatenates the list of byte sequences sl , inserting
197 the separator byte sequence sep between each, and returns the result as
198 a new byte sequence.
199 val cat : bytes -> bytes -> bytes
203 cat s1 s2 concatenates s1 and s2 and returns the result as new byte
206 sequence.
207 Raise Invalid_argument if the result is longer than
209 Sys.max_string_length bytes.
210 Since 4.05.0
213 val iter : f:(char -> unit) -> bytes -> unit
217 iter f s applies function f in turn to all the bytes of s . It is
220 equivalent to f (get s 0); f (get s 1); ...; f (get s
221 (length s - 1)); () .
222 val iteri : f:(int -> char -> unit) -> bytes -> unit
226 Same as Bytes.iter , but the function is applied to the index of the
228 byte as first argument and the byte itself as second argument.
229 val map : f:(char -> char) -> bytes -> bytes
233 map f s applies function f in turn to all the bytes of s and stores the
236 resulting bytes in a new sequence that is returned as the result.
237 val mapi : f:(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 trim : bytes -> bytes
250 Return a copy of the argument, without leading and trailing whitespace.
252 The bytes regarded as whitespace are the ASCII characters ' ' , '\012'
253 , '\n' , '\r' , and '\t' .
254 val escaped : bytes -> bytes
258 Return a copy of the argument, with special characters represented by
260 escape sequences, following the lexical conventions of OCaml.
261 val index : bytes -> char -> int
265 index s c returns the index of the first occurrence of byte c in s .
268 Raise Not_found if c does not occur in s .
270 val index_opt : bytes -> char -> int option
274 index_opt s c returns the index of the first occurrence of byte c in s
277 or None if c does not occur in s .
278 Since 4.05
281 val rindex : bytes -> char -> int
285 rindex s c returns the index of the last occurrence of byte c in s .
288 Raise Not_found if c does not occur in s .
290 val rindex_opt : bytes -> char -> int option
294 rindex_opt s c returns the index of the last occurrence of byte c in s
297 or None if c does not occur in s .
298 Since 4.05
301 val index_from : bytes -> int -> char -> int
305 index_from s i c returns the index of the first occurrence of byte c in
308 s after position i . Bytes.index s c is equivalent to Bytes.index_from
309 s 0 c .
310 Raise Invalid_argument if i is not a valid position in s . Raise
312 Not_found if c does not occur in s after position i .
313 val index_from_opt : bytes -> int -> char -> int option
317 index_from _opts i c returns the index of the first occurrence of byte
320 c in s after position i or None if c does not occur in s after position
321 i . Bytes.index_opt s c is equivalent to Bytes.index_from_opt s 0 c .
322 Raise Invalid_argument if i is not a valid position in s .
324 Since 4.05
327 val rindex_from : bytes -> int -> char -> int
331 rindex_from s i c returns the index of the last occurrence of byte c in
334 s before position i+1 . rindex s c is equivalent to rindex_from s
335 (Bytes.length s - 1) c .
336 Raise Invalid_argument if i+1 is not a valid position in s . Raise
338 Not_found if c does not occur in s before position i+1 .
339 val rindex_from_opt : bytes -> int -> char -> int option
343 rindex_from_opt s i c returns the index of the last occurrence of byte
346 c in s before position i+1 or None if c does not occur in s before
347 position i+1 . rindex_opt s c is equivalent to rindex_from s
348 (Bytes.length s - 1) c .
349 Raise Invalid_argument if i+1 is not a valid position in s .
351 Since 4.05
354 val contains : bytes -> char -> bool
358 contains s c tests if byte c appears in s .
361 val contains_from : bytes -> int -> char -> bool
365 contains_from s start c tests if byte c appears in s after position
368 start . contains s c is equivalent to contains_from
369 s 0 c .
370 Raise Invalid_argument if start is not a valid position in s .
372 val rcontains_from : bytes -> int -> char -> bool
376 rcontains_from s stop c tests if byte c appears in s before position
379 stop+1 .
380 Raise Invalid_argument if stop < 0 or stop+1 is not a valid position in
382 s .
383 val uppercase : bytes -> bytes
387 Deprecated. Functions operating on Latin-1 character set are depre‐
389 cated.
390 Return a copy of the argument, with all lowercase letters translated to
393 uppercase, including accented letters of the ISO Latin-1 (8859-1) char‐
394 acter set.
395 val lowercase : bytes -> bytes
399 Deprecated. Functions operating on Latin-1 character set are depre‐
401 cated.
402 Return a copy of the argument, with all uppercase letters translated to
405 lowercase, including accented letters of the ISO Latin-1 (8859-1) char‐
406 acter set.
407 val capitalize : bytes -> bytes
411 Deprecated. Functions operating on Latin-1 character set are depre‐
413 cated.
414 Return a copy of the argument, with the first character set to upper‐
417 case, using the ISO Latin-1 (8859-1) character set..
418 val uncapitalize : bytes -> bytes
422 Deprecated. Functions operating on Latin-1 character set are depre‐
424 cated.
425 Return a copy of the argument, with the first character set to lower‐
428 case, using the ISO Latin-1 (8859-1) character set..
429 val uppercase_ascii : bytes -> bytes
433 Return a copy of the argument, with all lowercase letters translated to
435 uppercase, using the US-ASCII character set.
436 Since 4.05.0
439 val lowercase_ascii : bytes -> bytes
443 Return a copy of the argument, with all uppercase letters translated to
445 lowercase, using the US-ASCII character set.
446 Since 4.05.0
449 val capitalize_ascii : bytes -> bytes
453 Return a copy of the argument, with the first character set to upper‐
455 case, using the US-ASCII character set.
456 Since 4.05.0
459 val uncapitalize_ascii : bytes -> bytes
463 Return a copy of the argument, with the first character set to lower‐
465 case, using the US-ASCII character set.
466 Since 4.05.0
469 type t = bytes
472 An alias for the type of byte sequences.
475 val compare : t -> t -> int
479 The comparison function for byte sequences, with the same specification
481 as compare . Along with the type t , this function compare allows the
482 module Bytes to be passed as argument to the functors Set.Make and
483 Map.Make .
484 val equal : t -> t -> bool
488 The equality function for byte sequences.
490 Since 4.05.0
493 Iterators
498 val to_seq : t -> char Seq.t
499 Iterate on the string, in increasing index order. Modifications of the
501 string during iteration will be reflected in the iterator.
502 Since 4.07
505 val to_seqi : t -> (int * char) Seq.t
509 Iterate on the string, in increasing order, yielding indices along
511 chars
512 Since 4.07
515 val of_seq : char Seq.t -> t
519 Create a string from the generator
521 Since 4.07
524 Binary encoding/decoding of integers
529 The functions in this section binary encode and decode integers to and
530 from byte sequences.
531 All following functions raise Invalid_argument if the space needed at
533 index i to decode or encode the integer is not available.
534 Little-endian (resp. big-endian) encoding means that least (resp. most)
536 significant bytes are stored first. Big-endian is also known as net‐
537 work byte order. Native-endian encoding is either little-endian or
538 big-endian depending on Sys.big_endian .
539 32-bit and 64-bit integers are represented by the int32 and int64
541 types, which can be interpreted either as signed or unsigned numbers.
542 8-bit and 16-bit integers are represented by the int type, which has
544 more bits than the binary encoding. These extra bits are handled as
545 follows:
546 -Functions that decode signed (resp. unsigned) 8-bit or 16-bit integers
548 represented by int values sign-extend (resp. zero-extend) their result.
549 -Functions that encode 8-bit or 16-bit integers represented by int val‐
551 ues truncate their input to their least significant bytes.
552 val get_uint8 : bytes -> int -> int
555 get_uint8 b i is b 's unsigned 8-bit integer starting at byte index i .
558 Since 4.08
561 val get_int8 : bytes -> int -> int
565 get_int8 b i is b 's signed 8-bit integer starting at byte index i .
568 Since 4.08
571 val get_uint16_ne : bytes -> int -> int
575 get_uint16_ne b i is b 's native-endian unsigned 16-bit integer start‐
578 ing at byte index i .
579 Since 4.08
582 val get_uint16_be : bytes -> int -> int
586 get_uint16_be b i is b 's big-endian unsigned 16-bit integer starting
589 at byte index i .
590 Since 4.08
593 val get_uint16_le : bytes -> int -> int
597 get_uint16_le b i is b 's little-endian unsigned 16-bit integer start‐
600 ing at byte index i .
601 Since 4.08
604 val get_int16_ne : bytes -> int -> int
608 get_int16_ne b i is b 's native-endian signed 16-bit integer starting
611 at byte index i .
612 Since 4.08
615 val get_int16_be : bytes -> int -> int
619 get_int16_be b i is b 's big-endian signed 16-bit integer starting at
622 byte index i .
623 Since 4.08
626 val get_int16_le : bytes -> int -> int
630 get_int16_le b i is b 's little-endian signed 16-bit integer starting
633 at byte index i .
634 Since 4.08
637 val get_int32_ne : bytes -> int -> int32
641 get_int32_ne b i is b 's native-endian 32-bit integer starting at byte
644 index i .
645 Since 4.08
648 val get_int32_be : bytes -> int -> int32
652 get_int32_be b i is b 's big-endian 32-bit integer starting at byte
655 index i .
656 Since 4.08
659 val get_int32_le : bytes -> int -> int32
663 get_int32_le b i is b 's little-endian 32-bit integer starting at byte
666 index i .
667 Since 4.08
670 val get_int64_ne : bytes -> int -> int64
674 get_int64_ne b i is b 's native-endian 64-bit integer starting at byte
677 index i .
678 Since 4.08
681 val get_int64_be : bytes -> int -> int64
685 get_int64_be b i is b 's big-endian 64-bit integer starting at byte
688 index i .
689 Since 4.08
692 val get_int64_le : bytes -> int -> int64
696 get_int64_le b i is b 's little-endian 64-bit integer starting at byte
699 index i .
700 Since 4.08
703 val set_uint8 : bytes -> int -> int -> unit
707 set_uint8 b i v sets b 's unsigned 8-bit integer starting at byte index
710 i to v .
711 Since 4.08
714 val set_int8 : bytes -> int -> int -> unit
718 set_int8 b i v sets b 's signed 8-bit integer starting at byte index i
721 to v .
722 Since 4.08
725 val set_uint16_ne : bytes -> int -> int -> unit
729 set_uint16_ne b i v sets b 's native-endian unsigned 16-bit integer
732 starting at byte index i to v .
733 Since 4.08
736 val set_uint16_be : bytes -> int -> int -> unit
740 set_uint16_be b i v sets b 's big-endian unsigned 16-bit integer start‐
743 ing at byte index i to v .
744 Since 4.08
747 val set_uint16_le : bytes -> int -> int -> unit
751 set_uint16_le b i v sets b 's little-endian unsigned 16-bit integer
754 starting at byte index i to v .
755 Since 4.08
758 val set_int16_ne : bytes -> int -> int -> unit
762 set_int16_ne b i v sets b 's native-endian signed 16-bit integer start‐
765 ing at byte index i to v .
766 Since 4.08
769 val set_int16_be : bytes -> int -> int -> unit
773 set_int16_be b i v sets b 's big-endian signed 16-bit integer starting
776 at byte index i to v .
777 Since 4.08
780 val set_int16_le : bytes -> int -> int -> unit
784 set_int16_le b i v sets b 's little-endian signed 16-bit integer start‐
787 ing at byte index i to v .
788 Since 4.08
791 val set_int32_ne : bytes -> int -> int32 -> unit
795 set_int32_ne b i v sets b 's native-endian 32-bit integer starting at
798 byte index i to v .
799 Since 4.08
802 val set_int32_be : bytes -> int -> int32 -> unit
806 set_int32_be b i v sets b 's big-endian 32-bit integer starting at byte
809 index i to v .
810 Since 4.08
813 val set_int32_le : bytes -> int -> int32 -> unit
817 set_int32_le b i v sets b 's little-endian 32-bit integer starting at
820 byte index i to v .
821 Since 4.08
824 val set_int64_ne : bytes -> int -> int64 -> unit
828 set_int64_ne b i v sets b 's native-endian 64-bit integer starting at
831 byte index i to v .
832 Since 4.08
835 val set_int64_be : bytes -> int -> int64 -> unit
839 set_int64_be b i v sets b 's big-endian 64-bit integer starting at byte
842 index i to v .
843 Since 4.08
846 val set_int64_le : bytes -> int -> int64 -> unit
850 set_int64_le b i v sets b 's little-endian 64-bit integer starting at
853 byte index i to v .
854 Since 4.08
857OCamldoc 2020-02-27 BytesLabels(3)