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

NAME

6       Buffer - Extensible buffers.
7

Module

9       Module   Buffer
10

Documentation

12       Module Buffer
13        : sig end
14
15
16       Extensible buffers.
17
18       This  module implements buffers that automatically expand as necessary.
19       It provides accumulative concatenation of strings in quasi-linear  time
20       (instead of quadratic time when strings are concatenated pairwise). For
21       example:
22
23
24            let concat_strings ss =
25              let b = Buffer.create 16 in
26                List.iter (Buffer.add_string b) ss;
27                Buffer.contents b
28
29
30
31
32
33
34
35       type t
36
37
38       The abstract type of buffers.
39
40
41
42       val create : int -> t
43
44
45       create n returns a fresh buffer, initially empty.  The n  parameter  is
46       the  initial  size  of the internal byte sequence that holds the buffer
47       contents. That byte sequence is  automatically  reallocated  when  more
48       than n characters are stored in the buffer, but shrinks back to n char‐
49       acters when reset is called.  For best performance, n should be of  the
50       same  order  of magnitude as the number of characters that are expected
51       to be stored in the buffer (for instance, 80 for a  buffer  that  holds
52       one  output  line).  Nothing bad will happen if the buffer grows beyond
53       that limit, however. In doubt, take n = 16 for instance.  If n  is  not
54       between 1 and Sys.max_string_length , it will be clipped to that inter‐
55       val.
56
57
58
59       val contents : t -> string
60
61       Return a copy of the current contents of the buffer.  The buffer itself
62       is unchanged.
63
64
65
66       val to_bytes : t -> bytes
67
68       Return a copy of the current contents of the buffer.  The buffer itself
69       is unchanged.
70
71
72       Since 4.02
73
74
75
76       val sub : t -> int -> int -> string
77
78
79       Buffer.sub b off len returns a copy of len bytes from the current  con‐
80       tents of the buffer b , starting at offset off .
81
82
83       Raises  Invalid_argument  if  srcoff  and  len do not designate a valid
84       range of b .
85
86
87
88       val blit : t -> int -> bytes -> int -> int -> unit
89
90
91       Buffer.blit src srcoff dst dstoff len copies len  characters  from  the
92       current contents of the buffer src , starting at offset srcoff to dst ,
93       starting at character dstoff .
94
95
96       Since 3.11.2
97
98
99       Raises Invalid_argument if srcoff and len  do  not  designate  a  valid
100       range  of  src , or if dstoff and len do not designate a valid range of
101       dst .
102
103
104
105       val nth : t -> int -> char
106
107       Get the n-th character of the buffer.
108
109
110       Raises Invalid_argument if index out of bounds
111
112
113
114       val length : t -> int
115
116       Return the number of characters currently contained in the buffer.
117
118
119
120       val clear : t -> unit
121
122       Empty the buffer.
123
124
125
126       val reset : t -> unit
127
128       Empty the buffer and deallocate the internal byte sequence holding  the
129       buffer  contents,  replacing it with the initial internal byte sequence
130       of length n that was allocated by Buffer.create  n  .   For  long-lived
131       buffers  that  may have grown a lot, reset allows faster reclamation of
132       the space used by the buffer.
133
134
135
136       val add_char : t -> char -> unit
137
138
139       add_char b c appends the character c at the end of buffer b .
140
141
142
143       val add_utf_8_uchar : t -> Uchar.t -> unit
144
145
146       add_utf_8_uchar b u appends the UTF-8 encoding of u at the end of  buf‐
147       fer b .
148
149
150       Since 4.06.0
151
152
153
154       val add_utf_16le_uchar : t -> Uchar.t -> unit
155
156
157       add_utf_16le_uchar b u appends the UTF-16LE encoding of u at the end of
158       buffer b .
159
160
161       Since 4.06.0
162
163
164
165       val add_utf_16be_uchar : t -> Uchar.t -> unit
166
167
168       add_utf_16be_uchar b u appends the UTF-16BE encoding of u at the end of
169       buffer b .
170
171
172       Since 4.06.0
173
174
175
176       val add_string : t -> string -> unit
177
178
179       add_string b s appends the string s at the end of buffer b .
180
181
182
183       val add_bytes : t -> bytes -> unit
184
185
186       add_bytes b s appends the byte sequence s at the end of buffer b .
187
188
189       Since 4.02
190
191
192
193       val add_substring : t -> string -> int -> int -> unit
194
195
196       add_substring  b  s  ofs  len  takes  len characters from offset ofs in
197       string s and appends them at the end of buffer b .
198
199
200
201       val add_subbytes : t -> bytes -> int -> int -> unit
202
203
204       add_subbytes b s ofs len takes len characters from offset ofs  in  byte
205       sequence s and appends them at the end of buffer b .
206
207
208       Since 4.02
209
210
211
212       val add_substitute : t -> (string -> string) -> string -> unit
213
214
215       add_substitute  b f s appends the string pattern s at the end of buffer
216       b with substitution.  The substitution process looks for variables into
217       the  pattern  and  substitutes  each variable name by its value, as ob‐
218       tained by applying the mapping f  to  the  variable  name.  Inside  the
219       string  pattern,  a  variable  name immediately follows a non-escaped $
220       character and is one of the following:
221
222       -a non empty sequence of alphanumeric or _ characters,
223
224       -an arbitrary sequence of characters enclosed by  a  pair  of  matching
225       parentheses  or curly brackets.  An escaped $ character is a $ that im‐
226       mediately follows a backslash character; it then stands for a plain $ .
227
228
229
230       Raises Not_found if the closing character of a  parenthesized  variable
231       cannot be found.
232
233
234
235       val add_buffer : t -> t -> unit
236
237
238       add_buffer  b1  b2 appends the current contents of buffer b2 at the end
239       of buffer b1 .  b2 is not modified.
240
241
242
243       val add_channel : t -> in_channel -> int -> unit
244
245
246       add_channel b ic n reads at most n characters from the input channel ic
247       and stores them at the end of buffer b .
248
249
250       Raises  End_of_file if the channel contains fewer than n characters. In
251       this case, the characters are still added to the buffer, so as to avoid
252       loss of data.
253
254
255
256       val output_buffer : out_channel -> t -> unit
257
258
259       output_buffer  oc b writes the current contents of buffer b on the out‐
260       put channel oc .
261
262
263
264       val truncate : t -> int -> unit
265
266
267       truncate b len truncates the length of b to len Note: the internal byte
268       sequence is not shortened.
269
270
271       Since 4.05.0
272
273
274       Raises Invalid_argument if len < 0 or len > length b .
275
276
277
278
279   Iterators
280       val to_seq : t -> char Seq.t
281
282       Iterate on the buffer, in increasing order.  Modification of the buffer
283       during iteration is undefined behavior.
284
285
286       Since 4.07
287
288
289
290       val to_seqi : t -> (int * char) Seq.t
291
292       Iterate on the buffer, in  increasing  order,  yielding  indices  along
293       chars.  Modification of the buffer during iteration is undefined behav‐
294       ior.
295
296
297       Since 4.07
298
299
300
301       val add_seq : t -> char Seq.t -> unit
302
303       Add chars to the buffer
304
305
306       Since 4.07
307
308
309
310       val of_seq : char Seq.t -> t
311
312       Create a buffer from the generator
313
314
315       Since 4.07
316
317
318
319
320   Binary encoding of integers
321       The functions in this section append binary encodings  of  integers  to
322       buffers.
323
324       Little-endian (resp. big-endian) encoding means that least (resp. most)
325       significant bytes are stored first.  Big-endian is also known  as  net‐
326       work  byte  order.   Native-endian  encoding is either little-endian or
327       big-endian depending on Sys.big_endian .
328
329       32-bit and 64-bit integers are  represented  by  the  int32  and  int64
330       types, which can be interpreted either as signed or unsigned numbers.
331
332       8-bit  and  16-bit  integers are represented by the int type, which has
333       more bits than the binary encoding.  Functions that encode these values
334       truncate their inputs to their least significant bytes.
335
336       val add_uint8 : t -> int -> unit
337
338
339       add_uint8 b i appends a binary unsigned 8-bit integer i to b .
340
341
342       Since 4.08
343
344
345
346       val add_int8 : t -> int -> unit
347
348
349       add_int8 b i appends a binary signed 8-bit integer i to b .
350
351
352       Since 4.08
353
354
355
356       val add_uint16_ne : t -> int -> unit
357
358
359       add_uint16_ne  b i appends a binary native-endian unsigned 16-bit inte‐
360       ger i to b .
361
362
363       Since 4.08
364
365
366
367       val add_uint16_be : t -> int -> unit
368
369
370       add_uint16_be b i appends a binary big-endian unsigned 16-bit integer i
371       to b .
372
373
374       Since 4.08
375
376
377
378       val add_uint16_le : t -> int -> unit
379
380
381       add_uint16_le  b i appends a binary little-endian unsigned 16-bit inte‐
382       ger i to b .
383
384
385       Since 4.08
386
387
388
389       val add_int16_ne : t -> int -> unit
390
391
392       add_int16_ne b i appends a binary native-endian signed 16-bit integer i
393       to b .
394
395
396       Since 4.08
397
398
399
400       val add_int16_be : t -> int -> unit
401
402
403       add_int16_be b i appends a binary big-endian signed 16-bit integer i to
404       b .
405
406
407       Since 4.08
408
409
410
411       val add_int16_le : t -> int -> unit
412
413
414       add_int16_le b i appends a binary little-endian signed 16-bit integer i
415       to b .
416
417
418       Since 4.08
419
420
421
422       val add_int32_ne : t -> int32 -> unit
423
424
425       add_int32_ne b i appends a binary native-endian 32-bit integer i to b .
426
427
428       Since 4.08
429
430
431
432       val add_int32_be : t -> int32 -> unit
433
434
435       add_int32_be b i appends a binary big-endian 32-bit integer i to b .
436
437
438       Since 4.08
439
440
441
442       val add_int32_le : t -> int32 -> unit
443
444
445       add_int32_le b i appends a binary little-endian 32-bit integer i to b .
446
447
448       Since 4.08
449
450
451
452       val add_int64_ne : t -> int64 -> unit
453
454
455       add_int64_ne b i appends a binary native-endian 64-bit integer i to b .
456
457
458       Since 4.08
459
460
461
462       val add_int64_be : t -> int64 -> unit
463
464
465       add_int64_be b i appends a binary big-endian 64-bit integer i to b .
466
467
468       Since 4.08
469
470
471
472       val add_int64_le : t -> int64 -> unit
473
474
475       add_int64_ne b i appends a binary little-endian 64-bit integer i to b .
476
477
478       Since 4.08
479
480
481
482
483
484OCamldoc                          2021-07-22                         Buffer(3)