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