1Stdlib.Bytes(3) OCaml library Stdlib.Bytes(3)
2
3
4
6 Stdlib.Bytes - no description
7
9 Module Stdlib.Bytes
10
12 Module Bytes
13 : (module Stdlib__bytes)
14
15
16
17
18
19
20
21
22 val length : bytes -> int
23
24 Return the length (number of bytes) of the argument.
25
26
27
28 val get : bytes -> int -> char
29
30
31 get s n returns the byte at index n in argument s .
32
33 Raise Invalid_argument if n is not a valid index in s .
34
35
36
37 val set : bytes -> int -> char -> unit
38
39
40 set s n c modifies s in place, replacing the byte at index n with c .
41
42 Raise Invalid_argument if n is not a valid index in s .
43
44
45
46 val create : int -> bytes
47
48
49 create n returns a new byte sequence of length n . The sequence is
50 uninitialized and contains arbitrary bytes.
51
52 Raise Invalid_argument if n < 0 or n > Sys.max_string_length .
53
54
55
56 val make : int -> char -> bytes
57
58
59 make n c returns a new byte sequence of length n , filled with the byte
60 c .
61
62 Raise Invalid_argument if n < 0 or n > Sys.max_string_length .
63
64
65
66 val init : int -> (int -> char) -> bytes
67
68
69 Bytes.init n f returns a fresh byte sequence of length n , with charac‐
70 ter i initialized to the result of f i (in increasing index order).
71
72 Raise Invalid_argument if n < 0 or n > Sys.max_string_length .
73
74
75
76 val empty : bytes
77
78 A byte sequence of size 0.
79
80
81
82 val copy : bytes -> bytes
83
84 Return a new byte sequence that contains the same bytes as the argu‐
85 ment.
86
87
88
89 val of_string : string -> bytes
90
91 Return a new byte sequence that contains the same bytes as the given
92 string.
93
94
95
96 val to_string : bytes -> string
97
98 Return a new string that contains the same bytes as the given byte
99 sequence.
100
101
102
103 val sub : bytes -> int -> int -> bytes
104
105
106 sub s start len returns a new byte sequence of length len , containing
107 the subsequence of s that starts at position start and has length len .
108
109 Raise Invalid_argument if start and len do not designate a valid range
110 of s .
111
112
113
114 val sub_string : bytes -> int -> int -> string
115
116 Same as sub but return a string instead of a byte sequence.
117
118
119
120 val extend : bytes -> int -> int -> bytes
121
122
123 extend s left right returns a new byte sequence that contains the bytes
124 of s , with left uninitialized bytes prepended and right uninitialized
125 bytes appended to it. If left or right is negative, then bytes are
126 removed (instead of appended) from the corresponding side of s .
127
128 Raise Invalid_argument if the result length is negative or longer than
129 Sys.max_string_length bytes.
130
131
132
133 val fill : bytes -> int -> int -> char -> unit
134
135
136 fill s start len c modifies s in place, replacing len characters with c
137 , starting at start .
138
139 Raise Invalid_argument if start and len do not designate a valid range
140 of s .
141
142
143
144 val blit : bytes -> int -> bytes -> int -> int -> unit
145
146
147 blit src srcoff dst dstoff len copies len bytes from sequence src ,
148 starting at index srcoff , to sequence dst , starting at index dstoff .
149 It works correctly even if src and dst are the same byte sequence, and
150 the source and destination intervals overlap.
151
152 Raise Invalid_argument if srcoff and len do not designate a valid range
153 of src , or if dstoff and len do not designate a valid range of dst .
154
155
156
157 val blit_string : string -> int -> bytes -> int -> int -> unit
158
159
160 blit_string src srcoff dst dstoff len copies len bytes from string src
161 , starting at index srcoff , to byte sequence dst , starting at index
162 dstoff .
163
164 Raise Invalid_argument if srcoff and len do not designate a valid range
165 of src , or if dstoff and len do not designate a valid range of dst .
166
167
168
169 val concat : bytes -> bytes list -> bytes
170
171
172 concat sep sl concatenates the list of byte sequences sl , inserting
173 the separator byte sequence sep between each, and returns the result as
174 a new byte sequence.
175
176 Raise Invalid_argument if the result is longer than
177 Sys.max_string_length bytes.
178
179
180
181 val cat : bytes -> bytes -> bytes
182
183
184 cat s1 s2 concatenates s1 and s2 and returns the result as new byte
185 sequence.
186
187 Raise Invalid_argument if the result is longer than
188 Sys.max_string_length bytes.
189
190
191
192 val iter : (char -> unit) -> bytes -> unit
193
194
195 iter f s applies function f in turn to all the bytes of s . It is
196 equivalent to f (get s 0); f (get s 1); ...; f (get s
197 (length s - 1)); () .
198
199
200
201 val iteri : (int -> char -> unit) -> bytes -> unit
202
203 Same as Bytes.iter , but the function is applied to the index of the
204 byte as first argument and the byte itself as second argument.
205
206
207
208 val map : (char -> char) -> bytes -> bytes
209
210
211 map f s applies function f in turn to all the bytes of s (in increasing
212 index order) and stores the resulting bytes in a new sequence that is
213 returned as the result.
214
215
216
217 val mapi : (int -> char -> char) -> bytes -> bytes
218
219
220 mapi f s calls f with each character of s and its index (in increasing
221 index order) and stores the resulting bytes in a new sequence that is
222 returned as the result.
223
224
225
226 val trim : bytes -> bytes
227
228 Return a copy of the argument, without leading and trailing whitespace.
229 The bytes regarded as whitespace are the ASCII characters ' ' , '\012'
230 , '\n' , '\r' , and '\t' .
231
232
233
234 val escaped : bytes -> bytes
235
236 Return a copy of the argument, with special characters represented by
237 escape sequences, following the lexical conventions of OCaml. All
238 characters outside the ASCII printable range (32..126) are escaped, as
239 well as backslash and double-quote.
240
241 Raise Invalid_argument if the result is longer than
242 Sys.max_string_length bytes.
243
244
245
246 val index : bytes -> char -> int
247
248
249 index s c returns the index of the first occurrence of byte c in s .
250
251 Raise Not_found if c does not occur in s .
252
253
254
255 val index_opt : bytes -> char -> int option
256
257
258 index_opt s c returns the index of the first occurrence of byte c in s
259 or None if c does not occur in s .
260
261
262 Since 4.05
263
264
265
266 val rindex : bytes -> char -> int
267
268
269 rindex s c returns the index of the last occurrence of byte c in s .
270
271 Raise Not_found if c does not occur in s .
272
273
274
275 val rindex_opt : bytes -> char -> int option
276
277
278 rindex_opt s c returns the index of the last occurrence of byte c in s
279 or None if c does not occur in s .
280
281
282 Since 4.05
283
284
285
286 val index_from : bytes -> int -> char -> int
287
288
289 index_from s i c returns the index of the first occurrence of byte c in
290 s after position i . Bytes.index s c is equivalent to Bytes.index_from
291 s 0 c .
292
293 Raise Invalid_argument if i is not a valid position in s . Raise
294 Not_found if c does not occur in s after position i .
295
296
297
298 val index_from_opt : bytes -> int -> char -> int option
299
300
301 index_from_opt s i c returns the index of the first occurrence of byte
302 c in s after position i or None if c does not occur in s after position
303 i . Bytes.index_opt s c is equivalent to Bytes.index_from_opt s 0 c .
304
305 Raise Invalid_argument if i is not a valid position in s .
306
307
308 Since 4.05
309
310
311
312 val rindex_from : bytes -> int -> char -> int
313
314
315 rindex_from s i c returns the index of the last occurrence of byte c in
316 s before position i+1 . rindex s c is equivalent to rindex_from s
317 (Bytes.length s - 1) c .
318
319 Raise Invalid_argument if i+1 is not a valid position in s . Raise
320 Not_found if c does not occur in s before position i+1 .
321
322
323
324 val rindex_from_opt : bytes -> int -> char -> int option
325
326
327 rindex_from_opt s i c returns the index of the last occurrence of byte
328 c in s before position i+1 or None if c does not occur in s before
329 position i+1 . rindex_opt s c is equivalent to rindex_from s
330 (Bytes.length s - 1) c .
331
332 Raise Invalid_argument if i+1 is not a valid position in s .
333
334
335 Since 4.05
336
337
338
339 val contains : bytes -> char -> bool
340
341
342 contains s c tests if byte c appears in s .
343
344
345
346 val contains_from : bytes -> int -> char -> bool
347
348
349 contains_from s start c tests if byte c appears in s after position
350 start . contains s c is equivalent to contains_from
351 s 0 c .
352
353 Raise Invalid_argument if start is not a valid position in s .
354
355
356
357 val rcontains_from : bytes -> int -> char -> bool
358
359
360 rcontains_from s stop c tests if byte c appears in s before position
361 stop+1 .
362
363 Raise Invalid_argument if stop < 0 or stop+1 is not a valid position in
364 s .
365
366
367
368 val uppercase : bytes -> bytes
369
370 Deprecated. Functions operating on Latin-1 character set are depre‐
371 cated.
372
373
374 Return a copy of the argument, with all lowercase letters translated to
375 uppercase, including accented letters of the ISO Latin-1 (8859-1) char‐
376 acter set.
377
378
379
380 val lowercase : bytes -> bytes
381
382 Deprecated. Functions operating on Latin-1 character set are depre‐
383 cated.
384
385
386 Return a copy of the argument, with all uppercase letters translated to
387 lowercase, including accented letters of the ISO Latin-1 (8859-1) char‐
388 acter set.
389
390
391
392 val capitalize : bytes -> bytes
393
394 Deprecated. Functions operating on Latin-1 character set are depre‐
395 cated.
396
397
398 Return a copy of the argument, with the first character set to upper‐
399 case, using the ISO Latin-1 (8859-1) character set..
400
401
402
403 val uncapitalize : bytes -> bytes
404
405 Deprecated. Functions operating on Latin-1 character set are depre‐
406 cated.
407
408
409 Return a copy of the argument, with the first character set to lower‐
410 case, using the ISO Latin-1 (8859-1) character set..
411
412
413
414 val uppercase_ascii : bytes -> bytes
415
416 Return a copy of the argument, with all lowercase letters translated to
417 uppercase, using the US-ASCII character set.
418
419
420 Since 4.03.0
421
422
423
424 val lowercase_ascii : bytes -> bytes
425
426 Return a copy of the argument, with all uppercase letters translated to
427 lowercase, using the US-ASCII character set.
428
429
430 Since 4.03.0
431
432
433
434 val capitalize_ascii : bytes -> bytes
435
436 Return a copy of the argument, with the first character set to upper‐
437 case, using the US-ASCII character set.
438
439
440 Since 4.03.0
441
442
443
444 val uncapitalize_ascii : bytes -> bytes
445
446 Return a copy of the argument, with the first character set to lower‐
447 case, using the US-ASCII character set.
448
449
450 Since 4.03.0
451
452
453 type t = bytes
454
455
456 An alias for the type of byte sequences.
457
458
459
460 val compare : t -> t -> int
461
462 The comparison function for byte sequences, with the same specification
463 as compare . Along with the type t , this function compare allows the
464 module Bytes to be passed as argument to the functors Set.Make and
465 Map.Make .
466
467
468
469 val equal : t -> t -> bool
470
471 The equality function for byte sequences.
472
473
474 Since 4.03.0
475
476
477
478
479 Unsafe conversions (for advanced users)
480 This section describes unsafe, low-level conversion functions between
481 bytes and string . They do not copy the internal data; used improperly,
482 they can break the immutability invariant on strings provided by the
483 -safe-string option. They are available for expert library authors, but
484 for most purposes you should use the always-correct Bytes.to_string and
485 Bytes.of_string instead.
486
487 val unsafe_to_string : bytes -> string
488
489 Unsafely convert a byte sequence into a string.
490
491 To reason about the use of unsafe_to_string , it is convenient to con‐
492 sider an "ownership" discipline. A piece of code that manipulates some
493 data "owns" it; there are several disjoint ownership modes, including:
494
495 -Unique ownership: the data may be accessed and mutated
496
497 -Shared ownership: the data has several owners, that may only access
498 it, not mutate it.
499
500 Unique ownership is linear: passing the data to another piece of code
501 means giving up ownership (we cannot write the data again). A unique
502 owner may decide to make the data shared (giving up mutation rights on
503 it), but shared data may not become uniquely-owned again.
504
505
506 unsafe_to_string s can only be used when the caller owns the byte
507 sequence s -- either uniquely or as shared immutable data. The caller
508 gives up ownership of s , and gains ownership of the returned string.
509
510 There are two valid use-cases that respect this ownership discipline:
511
512 1. Creating a string by initializing and mutating a byte sequence that
513 is never changed after initialization is performed.
514
515
516 let string_init len f : string =
517 let s = Bytes.create len in
518 for i = 0 to len - 1 do Bytes.set s i (f i) done;
519 Bytes.unsafe_to_string s
520
521
522 This function is safe because the byte sequence s will never be
523 accessed or mutated after unsafe_to_string is called. The string_init
524 code gives up ownership of s , and returns the ownership of the result‐
525 ing string to its caller.
526
527 Note that it would be unsafe if s was passed as an additional parameter
528 to the function f as it could escape this way and be mutated in the
529 future -- string_init would give up ownership of s to pass it to f ,
530 and could not call unsafe_to_string safely.
531
532 We have provided the String.init , String.map and String.mapi functions
533 to cover most cases of building new strings. You should prefer those
534 over to_string or unsafe_to_string whenever applicable.
535
536 2. Temporarily giving ownership of a byte sequence to a function that
537 expects a uniquely owned string and returns ownership back, so that we
538 can mutate the sequence again after the call ended.
539
540
541 let bytes_length (s : bytes) =
542 String.length (Bytes.unsafe_to_string s)
543
544
545 In this use-case, we do not promise that s will never be mutated after
546 the call to bytes_length s . The String.length function temporarily
547 borrows unique ownership of the byte sequence (and sees it as a string
548 ), but returns this ownership back to the caller, which may assume that
549 s is still a valid byte sequence after the call. Note that this is only
550 correct because we know that String.length does not capture its argu‐
551 ment -- it could escape by a side-channel such as a memoization combi‐
552 nator.
553
554 The caller may not mutate s while the string is borrowed (it has tempo‐
555 rarily given up ownership). This affects concurrent programs, but also
556 higher-order functions: if String.length returned a closure to be
557 called later, s should not be mutated until this closure is fully
558 applied and returns ownership.
559
560
561
562 val unsafe_of_string : string -> bytes
563
564 Unsafely convert a shared string to a byte sequence that should not be
565 mutated.
566
567 The same ownership discipline that makes unsafe_to_string correct
568 applies to unsafe_of_string : you may use it if you were the owner of
569 the string value, and you will own the return bytes in the same mode.
570
571 In practice, unique ownership of string values is extremely difficult
572 to reason about correctly. You should always assume strings are shared,
573 never uniquely owned.
574
575 For example, string literals are implicitly shared by the compiler, so
576 you never uniquely own them.
577
578
579 let incorrect = Bytes.unsafe_of_string "hello"
580 let s = Bytes.of_string "hello"
581
582
583 The first declaration is incorrect, because the string literal "hello"
584 could be shared by the compiler with other parts of the program, and
585 mutating incorrect is a bug. You must always use the second version,
586 which performs a copy and is thus correct.
587
588 Assuming unique ownership of strings that are not string literals, but
589 are (partly) built from string literals, is also incorrect. For exam‐
590 ple, mutating unsafe_of_string ("foo" ^ s) could mutate the shared
591 string "foo" -- assuming a rope-like representation of strings. More
592 generally, functions operating on strings will assume shared ownership,
593 they do not preserve unique ownership. It is thus incorrect to assume
594 unique ownership of the result of unsafe_of_string .
595
596 The only case we have reasonable confidence is safe is if the produced
597 bytes is shared -- used as an immutable byte sequence. This is possibly
598 useful for incremental migration of low-level programs that manipulate
599 immutable sequences of bytes (for example Marshal.from_bytes ) and pre‐
600 viously used the string type for this purpose.
601
602
603
604
605 Iterators
606 val to_seq : t -> char Seq.t
607
608 Iterate on the string, in increasing index order. Modifications of the
609 string during iteration will be reflected in the iterator.
610
611
612 Since 4.07
613
614
615
616 val to_seqi : t -> (int * char) Seq.t
617
618 Iterate on the string, in increasing order, yielding indices along
619 chars
620
621
622 Since 4.07
623
624
625
626 val of_seq : char Seq.t -> t
627
628 Create a string from the generator
629
630
631 Since 4.07
632
633
634
635
636 Binary encoding/decoding of integers
637 The functions in this section binary encode and decode integers to and
638 from byte sequences.
639
640 All following functions raise Invalid_argument if the space needed at
641 index i to decode or encode the integer is not available.
642
643 Little-endian (resp. big-endian) encoding means that least (resp. most)
644 significant bytes are stored first. Big-endian is also known as net‐
645 work byte order. Native-endian encoding is either little-endian or
646 big-endian depending on Sys.big_endian .
647
648 32-bit and 64-bit integers are represented by the int32 and int64
649 types, which can be interpreted either as signed or unsigned numbers.
650
651 8-bit and 16-bit integers are represented by the int type, which has
652 more bits than the binary encoding. These extra bits are handled as
653 follows:
654
655 -Functions that decode signed (resp. unsigned) 8-bit or 16-bit integers
656 represented by int values sign-extend (resp. zero-extend) their result.
657
658 -Functions that encode 8-bit or 16-bit integers represented by int val‐
659 ues truncate their input to their least significant bytes.
660
661
662 val get_uint8 : bytes -> int -> int
663
664
665 get_uint8 b i is b 's unsigned 8-bit integer starting at byte index i .
666
667
668 Since 4.08
669
670
671
672 val get_int8 : bytes -> int -> int
673
674
675 get_int8 b i is b 's signed 8-bit integer starting at byte index i .
676
677
678 Since 4.08
679
680
681
682 val get_uint16_ne : bytes -> int -> int
683
684
685 get_uint16_ne b i is b 's native-endian unsigned 16-bit integer start‐
686 ing at byte index i .
687
688
689 Since 4.08
690
691
692
693 val get_uint16_be : bytes -> int -> int
694
695
696 get_uint16_be b i is b 's big-endian unsigned 16-bit integer starting
697 at byte index i .
698
699
700 Since 4.08
701
702
703
704 val get_uint16_le : bytes -> int -> int
705
706
707 get_uint16_le b i is b 's little-endian unsigned 16-bit integer start‐
708 ing at byte index i .
709
710
711 Since 4.08
712
713
714
715 val get_int16_ne : bytes -> int -> int
716
717
718 get_int16_ne b i is b 's native-endian signed 16-bit integer starting
719 at byte index i .
720
721
722 Since 4.08
723
724
725
726 val get_int16_be : bytes -> int -> int
727
728
729 get_int16_be b i is b 's big-endian signed 16-bit integer starting at
730 byte index i .
731
732
733 Since 4.08
734
735
736
737 val get_int16_le : bytes -> int -> int
738
739
740 get_int16_le b i is b 's little-endian signed 16-bit integer starting
741 at byte index i .
742
743
744 Since 4.08
745
746
747
748 val get_int32_ne : bytes -> int -> int32
749
750
751 get_int32_ne b i is b 's native-endian 32-bit integer starting at byte
752 index i .
753
754
755 Since 4.08
756
757
758
759 val get_int32_be : bytes -> int -> int32
760
761
762 get_int32_be b i is b 's big-endian 32-bit integer starting at byte
763 index i .
764
765
766 Since 4.08
767
768
769
770 val get_int32_le : bytes -> int -> int32
771
772
773 get_int32_le b i is b 's little-endian 32-bit integer starting at byte
774 index i .
775
776
777 Since 4.08
778
779
780
781 val get_int64_ne : bytes -> int -> int64
782
783
784 get_int64_ne b i is b 's native-endian 64-bit integer starting at byte
785 index i .
786
787
788 Since 4.08
789
790
791
792 val get_int64_be : bytes -> int -> int64
793
794
795 get_int64_be b i is b 's big-endian 64-bit integer starting at byte
796 index i .
797
798
799 Since 4.08
800
801
802
803 val get_int64_le : bytes -> int -> int64
804
805
806 get_int64_le b i is b 's little-endian 64-bit integer starting at byte
807 index i .
808
809
810 Since 4.08
811
812
813
814 val set_uint8 : bytes -> int -> int -> unit
815
816
817 set_uint8 b i v sets b 's unsigned 8-bit integer starting at byte index
818 i to v .
819
820
821 Since 4.08
822
823
824
825 val set_int8 : bytes -> int -> int -> unit
826
827
828 set_int8 b i v sets b 's signed 8-bit integer starting at byte index i
829 to v .
830
831
832 Since 4.08
833
834
835
836 val set_uint16_ne : bytes -> int -> int -> unit
837
838
839 set_uint16_ne b i v sets b 's native-endian unsigned 16-bit integer
840 starting at byte index i to v .
841
842
843 Since 4.08
844
845
846
847 val set_uint16_be : bytes -> int -> int -> unit
848
849
850 set_uint16_be b i v sets b 's big-endian unsigned 16-bit integer start‐
851 ing at byte index i to v .
852
853
854 Since 4.08
855
856
857
858 val set_uint16_le : bytes -> int -> int -> unit
859
860
861 set_uint16_le b i v sets b 's little-endian unsigned 16-bit integer
862 starting at byte index i to v .
863
864
865 Since 4.08
866
867
868
869 val set_int16_ne : bytes -> int -> int -> unit
870
871
872 set_int16_ne b i v sets b 's native-endian signed 16-bit integer start‐
873 ing at byte index i to v .
874
875
876 Since 4.08
877
878
879
880 val set_int16_be : bytes -> int -> int -> unit
881
882
883 set_int16_be b i v sets b 's big-endian signed 16-bit integer starting
884 at byte index i to v .
885
886
887 Since 4.08
888
889
890
891 val set_int16_le : bytes -> int -> int -> unit
892
893
894 set_int16_le b i v sets b 's little-endian signed 16-bit integer start‐
895 ing at byte index i to v .
896
897
898 Since 4.08
899
900
901
902 val set_int32_ne : bytes -> int -> int32 -> unit
903
904
905 set_int32_ne b i v sets b 's native-endian 32-bit integer starting at
906 byte index i to v .
907
908
909 Since 4.08
910
911
912
913 val set_int32_be : bytes -> int -> int32 -> unit
914
915
916 set_int32_be b i v sets b 's big-endian 32-bit integer starting at byte
917 index i to v .
918
919
920 Since 4.08
921
922
923
924 val set_int32_le : bytes -> int -> int32 -> unit
925
926
927 set_int32_le b i v sets b 's little-endian 32-bit integer starting at
928 byte index i to v .
929
930
931 Since 4.08
932
933
934
935 val set_int64_ne : bytes -> int -> int64 -> unit
936
937
938 set_int64_ne b i v sets b 's native-endian 64-bit integer starting at
939 byte index i to v .
940
941
942 Since 4.08
943
944
945
946 val set_int64_be : bytes -> int -> int64 -> unit
947
948
949 set_int64_be b i v sets b 's big-endian 64-bit integer starting at byte
950 index i to v .
951
952
953 Since 4.08
954
955
956
957 val set_int64_le : bytes -> int -> int64 -> unit
958
959
960 set_int64_le b i v sets b 's little-endian 64-bit integer starting at
961 byte index i to v .
962
963
964 Since 4.08
965
966
967
968
969
970OCamldoc 2020-02-27 Stdlib.Bytes(3)