1BytesLabels(3)                   OCaml library                  BytesLabels(3)
2
3
4

NAME

6       BytesLabels - Byte sequence operations.
7

Module

9       Module   BytesLabels
10

Documentation

12       Module BytesLabels
13        : sig end
14
15
16       Byte sequence operations.
17
18
19       Since 4.02.0
20
21           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
26           For example:
27           {[
28              open StdLabels
29
30              let first = Bytes.sub ~pos:0 ~len:1
31           ]}
32
33
34
35
36
37
38       val length : bytes -> int
39
40       Return the length (number of bytes) of the argument.
41
42
43
44       val get : bytes -> int -> char
45
46
47       get s n returns the byte at index n in argument s .
48
49
50       Raises Invalid_argument if n is not a valid index in s .
51
52
53
54       val set : bytes -> int -> char -> unit
55
56
57       set s n c modifies s in place, replacing the byte at index n with c .
58
59
60       Raises Invalid_argument if n is not a valid index in s .
61
62
63
64       val create : int -> bytes
65
66
67       create  n  returns  a  new  byte sequence of length n . The sequence is
68       uninitialized and contains arbitrary bytes.
69
70
71       Raises Invalid_argument if n < 0 or n > Sys.max_string_length .
72
73
74
75       val make : int -> char -> bytes
76
77
78       make n c returns a new byte sequence of length n , filled with the byte
79       c .
80
81
82       Raises Invalid_argument if n < 0 or n > Sys.max_string_length .
83
84
85
86       val init : int -> f:(int -> char) -> bytes
87
88
89       init  n  f returns a fresh byte sequence of length n , with character i
90       initialized to the result of f i .
91
92
93       Raises Invalid_argument if n < 0 or n > Sys.max_string_length .
94
95
96
97       val empty : bytes
98
99       A byte sequence of size 0.
100
101
102
103       val copy : bytes -> bytes
104
105       Return a new byte sequence that contains the same bytes  as  the  argu‐
106       ment.
107
108
109
110       val of_string : string -> bytes
111
112       Return  a  new  byte sequence that contains the same bytes as the given
113       string.
114
115
116
117       val to_string : bytes -> string
118
119       Return a new string that contains the same bytes as the given byte  se‐
120       quence.
121
122
123
124       val sub : bytes -> pos:int -> len:int -> bytes
125
126
127       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
130
131       Raises Invalid_argument if start and len do not designate a valid range
132       of s .
133
134
135
136       val sub_string : bytes -> pos:int -> len:int -> string
137
138       Same as sub but return a string instead of a byte sequence.
139
140
141
142       val extend : bytes -> left:int -> right:int -> bytes
143
144
145       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
150
151       Since 4.05.0
152
153
154       Raises Invalid_argument if the result length is negative or longer than
155       Sys.max_string_length bytes.
156
157
158
159       val fill : bytes -> pos:int -> len:int -> char -> unit
160
161
162       fill s start len c modifies s in place, replacing len characters with c
163       , starting at start .
164
165
166       Raises Invalid_argument if start and len do not designate a valid range
167       of s .
168
169
170
171       val  blit  :  src:bytes  ->  src_pos:int -> dst:bytes -> dst_pos:int ->
172       len:int -> unit
173
174
175       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
180
181       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
185
186
187       val blit_string : src:string -> src_pos:int -> dst:bytes -> dst_pos:int
188       -> len:int -> unit
189
190
191       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
195
196       Since 4.05.0
197
198
199       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
203
204
205       val concat : sep:bytes -> bytes list -> bytes
206
207
208       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
212
213
214       val cat : bytes -> bytes -> bytes
215
216
217       cat s1 s2 concatenates s1 and s2 and returns the result as new byte se‐
218       quence.
219
220
221       Since 4.05.0
222
223
224       Raises    Invalid_argument    if    the    result    is   longer   than
225       Sys.max_string_length bytes.
226
227
228
229       val iter : f:(char -> unit) -> bytes -> unit
230
231
232       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
236
237
238       val iteri : f:(int -> char -> unit) -> bytes -> unit
239
240       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
243
244
245       val map : f:(char -> char) -> bytes -> bytes
246
247
248       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
251
252
253       val mapi : f:(int -> char -> char) -> bytes -> bytes
254
255
256       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
260
261
262       val trim : bytes -> bytes
263
264       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
268
269
270       val escaped : bytes -> bytes
271
272       Return  a  copy of the argument, with special characters represented by
273       escape sequences, following the lexical conventions of OCaml.
274
275
276
277       val index : bytes -> char -> int
278
279
280       index s c returns the index of the first occurrence of byte c in s .
281
282
283       Raises Not_found if c does not occur in s .
284
285
286
287       val index_opt : bytes -> char -> int option
288
289
290       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
293
294       Since 4.05
295
296
297
298       val rindex : bytes -> char -> int
299
300
301       rindex s c returns the index of the last occurrence of byte c in s .
302
303
304       Raises Not_found if c does not occur in s .
305
306
307
308       val rindex_opt : bytes -> char -> int option
309
310
311       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
314
315       Since 4.05
316
317
318
319       val index_from : bytes -> int -> char -> int
320
321
322       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
326
327       Raises Invalid_argument if i is not a valid position in s .
328
329
330       Raises Not_found if c does not occur in s after position i .
331
332
333
334       val index_from_opt : bytes -> int -> char -> int option
335
336
337       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
341
342       Since 4.05
343
344
345       Raises Invalid_argument if i is not a valid position in s .
346
347
348
349       val rindex_from : bytes -> int -> char -> int
350
351
352       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
356
357       Raises Invalid_argument if i+1 is not a valid position in s .
358
359
360       Raises Not_found if c does not occur in s before position i+1 .
361
362
363
364       val rindex_from_opt : bytes -> int -> char -> int option
365
366
367       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
372
373       Since 4.05
374
375
376       Raises Invalid_argument if i+1 is not a valid position in s .
377
378
379
380       val contains : bytes -> char -> bool
381
382
383       contains s c tests if byte c appears in s .
384
385
386
387       val contains_from : bytes -> int -> char -> bool
388
389
390       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
394
395       Raises Invalid_argument if start is not a valid position in s .
396
397
398
399       val rcontains_from : bytes -> int -> char -> bool
400
401
402       rcontains_from s stop c tests if byte c appears in  s  before  position
403       stop+1 .
404
405
406       Raises  Invalid_argument  if stop < 0 or stop+1 is not a valid position
407       in s .
408
409
410
411       val uppercase : bytes -> bytes
412
413       Deprecated.  Functions operating on Latin-1 character  set  are  depre‐
414       cated.
415
416
417       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
421
422
423       val lowercase : bytes -> bytes
424
425       Deprecated.   Functions  operating  on Latin-1 character set are depre‐
426       cated.
427
428
429       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
433
434
435       val capitalize : bytes -> bytes
436
437       Deprecated.  Functions operating on Latin-1 character  set  are  depre‐
438       cated.
439
440
441       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
444
445
446       val uncapitalize : bytes -> bytes
447
448       Deprecated.  Functions operating on Latin-1 character  set  are  depre‐
449       cated.
450
451
452       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
455
456
457       val uppercase_ascii : bytes -> bytes
458
459       Return a copy of the argument, with all lowercase letters translated to
460       uppercase, using the US-ASCII character set.
461
462
463       Since 4.05.0
464
465
466
467       val lowercase_ascii : bytes -> bytes
468
469       Return a copy of the argument, with all uppercase letters translated to
470       lowercase, using the US-ASCII character set.
471
472
473       Since 4.05.0
474
475
476
477       val capitalize_ascii : bytes -> bytes
478
479       Return a copy of the argument, with the first character set  to  upper‐
480       case, using the US-ASCII character set.
481
482
483       Since 4.05.0
484
485
486
487       val uncapitalize_ascii : bytes -> bytes
488
489       Return  a  copy of the argument, with the first character set to lower‐
490       case, using the US-ASCII character set.
491
492
493       Since 4.05.0
494
495
496       type t = bytes
497
498
499       An alias for the type of byte sequences.
500
501
502
503       val compare : t -> t -> int
504
505       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
510
511
512       val equal : t -> t -> bool
513
514       The equality function for byte sequences.
515
516
517       Since 4.05.0
518
519
520
521
522   Iterators
523       val to_seq : t -> char Seq.t
524
525       Iterate  on the string, in increasing index order. Modifications of the
526       string during iteration will be reflected in the iterator.
527
528
529       Since 4.07
530
531
532
533       val to_seqi : t -> (int * char) Seq.t
534
535       Iterate on the string, in  increasing  order,  yielding  indices  along
536       chars
537
538
539       Since 4.07
540
541
542
543       val of_seq : char Seq.t -> t
544
545       Create a string from the generator
546
547
548       Since 4.07
549
550
551
552
553   Binary encoding/decoding of integers
554       The  functions in this section binary encode and decode integers to and
555       from byte sequences.
556
557       All following functions raise Invalid_argument if the space  needed  at
558       index i to decode or encode the integer is not available.
559
560       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
565       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
568       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
572       -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
575       -Functions that encode 8-bit or 16-bit integers represented by int val‐
576       ues truncate their input to their least significant bytes.
577
578
579       val get_uint8 : bytes -> int -> int
580
581
582       get_uint8 b i is b 's unsigned 8-bit integer starting at byte index i .
583
584
585       Since 4.08
586
587
588
589       val get_int8 : bytes -> int -> int
590
591
592       get_int8 b i is b 's signed 8-bit integer starting at byte index i .
593
594
595       Since 4.08
596
597
598
599       val get_uint16_ne : bytes -> int -> int
600
601
602       get_uint16_ne  b i is b 's native-endian unsigned 16-bit integer start‐
603       ing at byte index i .
604
605
606       Since 4.08
607
608
609
610       val get_uint16_be : bytes -> int -> int
611
612
613       get_uint16_be b i is b 's big-endian unsigned 16-bit  integer  starting
614       at byte index i .
615
616
617       Since 4.08
618
619
620
621       val get_uint16_le : bytes -> int -> int
622
623
624       get_uint16_le  b i is b 's little-endian unsigned 16-bit integer start‐
625       ing at byte index i .
626
627
628       Since 4.08
629
630
631
632       val get_int16_ne : bytes -> int -> int
633
634
635       get_int16_ne b i is b 's native-endian signed 16-bit  integer  starting
636       at byte index i .
637
638
639       Since 4.08
640
641
642
643       val get_int16_be : bytes -> int -> int
644
645
646       get_int16_be  b  i is b 's big-endian signed 16-bit integer starting at
647       byte index i .
648
649
650       Since 4.08
651
652
653
654       val get_int16_le : bytes -> int -> int
655
656
657       get_int16_le b i is b 's little-endian signed 16-bit  integer  starting
658       at byte index i .
659
660
661       Since 4.08
662
663
664
665       val get_int32_ne : bytes -> int -> int32
666
667
668       get_int32_ne  b i is b 's native-endian 32-bit integer starting at byte
669       index i .
670
671
672       Since 4.08
673
674
675
676       val get_int32_be : bytes -> int -> int32
677
678
679       get_int32_be b i is b 's big-endian 32-bit integer starting at byte in‐
680       dex i .
681
682
683       Since 4.08
684
685
686
687       val get_int32_le : bytes -> int -> int32
688
689
690       get_int32_le  b i is b 's little-endian 32-bit integer starting at byte
691       index i .
692
693
694       Since 4.08
695
696
697
698       val get_int64_ne : bytes -> int -> int64
699
700
701       get_int64_ne b i is b 's native-endian 64-bit integer starting at  byte
702       index i .
703
704
705       Since 4.08
706
707
708
709       val get_int64_be : bytes -> int -> int64
710
711
712       get_int64_be b i is b 's big-endian 64-bit integer starting at byte in‐
713       dex i .
714
715
716       Since 4.08
717
718
719
720       val get_int64_le : bytes -> int -> int64
721
722
723       get_int64_le b i is b 's little-endian 64-bit integer starting at  byte
724       index i .
725
726
727       Since 4.08
728
729
730
731       val set_uint8 : bytes -> int -> int -> unit
732
733
734       set_uint8 b i v sets b 's unsigned 8-bit integer starting at byte index
735       i to v .
736
737
738       Since 4.08
739
740
741
742       val set_int8 : bytes -> int -> int -> unit
743
744
745       set_int8 b i v sets b 's signed 8-bit integer starting at byte index  i
746       to v .
747
748
749       Since 4.08
750
751
752
753       val set_uint16_ne : bytes -> int -> int -> unit
754
755
756       set_uint16_ne  b  i  v  sets b 's native-endian unsigned 16-bit integer
757       starting at byte index i to v .
758
759
760       Since 4.08
761
762
763
764       val set_uint16_be : bytes -> int -> int -> unit
765
766
767       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
770
771       Since 4.08
772
773
774
775       val set_uint16_le : bytes -> int -> int -> unit
776
777
778       set_uint16_le  b  i  v  sets b 's little-endian unsigned 16-bit integer
779       starting at byte index i to v .
780
781
782       Since 4.08
783
784
785
786       val set_int16_ne : bytes -> int -> int -> unit
787
788
789       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
792
793       Since 4.08
794
795
796
797       val set_int16_be : bytes -> int -> int -> unit
798
799
800       set_int16_be  b i v sets b 's big-endian signed 16-bit integer starting
801       at byte index i to v .
802
803
804       Since 4.08
805
806
807
808       val set_int16_le : bytes -> int -> int -> unit
809
810
811       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
814
815       Since 4.08
816
817
818
819       val set_int32_ne : bytes -> int -> int32 -> unit
820
821
822       set_int32_ne  b  i v sets b 's native-endian 32-bit integer starting at
823       byte index i to v .
824
825
826       Since 4.08
827
828
829
830       val set_int32_be : bytes -> int -> int32 -> unit
831
832
833       set_int32_be b i v sets b 's big-endian 32-bit integer starting at byte
834       index i to v .
835
836
837       Since 4.08
838
839
840
841       val set_int32_le : bytes -> int -> int32 -> unit
842
843
844       set_int32_le  b  i v sets b 's little-endian 32-bit integer starting at
845       byte index i to v .
846
847
848       Since 4.08
849
850
851
852       val set_int64_ne : bytes -> int -> int64 -> unit
853
854
855       set_int64_ne b i v sets b 's native-endian 64-bit integer  starting  at
856       byte index i to v .
857
858
859       Since 4.08
860
861
862
863       val set_int64_be : bytes -> int -> int64 -> unit
864
865
866       set_int64_be b i v sets b 's big-endian 64-bit integer starting at byte
867       index i to v .
868
869
870       Since 4.08
871
872
873
874       val set_int64_le : bytes -> int -> int64 -> unit
875
876
877       set_int64_le b i v sets b 's little-endian 64-bit integer  starting  at
878       byte index i to v .
879
880
881       Since 4.08
882
883
884
885
886
887OCamldoc                          2021-01-26                    BytesLabels(3)
Impressum