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 off and len do not designate a valid range
84       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 output_buffer : out_channel -> t -> unit
137
138
139       output_buffer oc b writes the current contents of buffer b on the  out‐
140       put channel oc .
141
142
143
144       val truncate : t -> int -> unit
145
146
147       truncate b len truncates the length of b to len Note: the internal byte
148       sequence is not shortened.
149
150
151       Since 4.05.0
152
153
154       Raises Invalid_argument if len < 0 or len > length b .
155
156
157
158
159   Appending
160       Note: all add_* operations can raise Failure if the internal  byte  se‐
161       quence of the buffer would need to grow beyond Sys.max_string_length .
162
163       val add_char : t -> char -> unit
164
165
166       add_char b c appends the character c at the end of buffer b .
167
168
169
170       val add_utf_8_uchar : t -> Uchar.t -> unit
171
172
173       add_utf_8_uchar  b u appends the UTF-8 encoding of u at the end of buf‐
174       fer b .
175
176
177       Since 4.06.0
178
179
180
181       val add_utf_16le_uchar : t -> Uchar.t -> unit
182
183
184       add_utf_16le_uchar b u appends the UTF-16LE encoding of u at the end of
185       buffer b .
186
187
188       Since 4.06.0
189
190
191
192       val add_utf_16be_uchar : t -> Uchar.t -> unit
193
194
195       add_utf_16be_uchar b u appends the UTF-16BE encoding of u at the end of
196       buffer b .
197
198
199       Since 4.06.0
200
201
202
203       val add_string : t -> string -> unit
204
205
206       add_string b s appends the string s at the end of buffer b .
207
208
209
210       val add_bytes : t -> bytes -> unit
211
212
213       add_bytes b s appends the byte sequence s at the end of buffer b .
214
215
216       Since 4.02
217
218
219
220       val add_substring : t -> string -> int -> int -> unit
221
222
223       add_substring b s ofs len takes  len  characters  from  offset  ofs  in
224       string s and appends them at the end of buffer b .
225
226
227       Raises  Invalid_argument  if ofs and len do not designate a valid range
228       of s .
229
230
231
232       val add_subbytes : t -> bytes -> int -> int -> unit
233
234
235       add_subbytes b s ofs len takes len characters from offset ofs  in  byte
236       sequence s and appends them at the end of buffer b .
237
238
239       Since 4.02
240
241
242       Raises  Invalid_argument  if ofs and len do not designate a valid range
243       of s .
244
245
246
247       val add_substitute : t -> (string -> string) -> string -> unit
248
249
250       add_substitute b f s appends the string pattern s at the end of  buffer
251       b with substitution.  The substitution process looks for variables into
252       the pattern and substitutes each variable name by  its  value,  as  ob‐
253       tained  by  applying  the  mapping  f  to the variable name. Inside the
254       string pattern, a variable name immediately  follows  a  non-escaped  $
255       character and is one of the following:
256
257       -a non empty sequence of alphanumeric or _ characters,
258
259       -an  arbitrary  sequence  of  characters enclosed by a pair of matching
260       parentheses or curly brackets.  An escaped $ character is a $ that  im‐
261       mediately follows a backslash character; it then stands for a plain $ .
262
263
264
265       Raises  Not_found  if the closing character of a parenthesized variable
266       cannot be found.
267
268
269
270       val add_buffer : t -> t -> unit
271
272
273       add_buffer b1 b2 appends the current contents of buffer b2 at  the  end
274       of buffer b1 .  b2 is not modified.
275
276
277
278       val add_channel : t -> in_channel -> int -> unit
279
280
281       add_channel b ic n reads at most n characters from the input channel ic
282       and stores them at the end of buffer b .
283
284
285       Raises End_of_file if the channel contains fewer than n characters.  In
286       this case, the characters are still added to the buffer, so as to avoid
287       loss of data.
288
289
290       Raises Invalid_argument if len < 0 or len > Sys.max_string_length .
291
292
293
294
295   Buffers and Sequences
296       val to_seq : t -> char Seq.t
297
298       Iterate on the buffer, in increasing order.  Modification of the buffer
299       during iteration is undefined behavior.
300
301
302       Since 4.07
303
304
305
306       val to_seqi : t -> (int * char) Seq.t
307
308       Iterate  on  the  buffer,  in  increasing order, yielding indices along
309       chars.  Modification of the buffer during iteration is undefined behav‐
310       ior.
311
312
313       Since 4.07
314
315
316
317       val add_seq : t -> char Seq.t -> unit
318
319       Add chars to the buffer
320
321
322       Since 4.07
323
324
325
326       val of_seq : char Seq.t -> t
327
328       Create a buffer from the generator
329
330
331       Since 4.07
332
333
334
335
336   Binary encoding of integers
337       The  functions  in  this section append binary encodings of integers to
338       buffers.
339
340       Little-endian (resp. big-endian) encoding means that least (resp. most)
341       significant  bytes  are stored first.  Big-endian is also known as net‐
342       work byte order.  Native-endian encoding  is  either  little-endian  or
343       big-endian depending on Sys.big_endian .
344
345       32-bit  and  64-bit  integers  are  represented  by the int32 and int64
346       types, which can be interpreted either as signed or unsigned numbers.
347
348       8-bit and 16-bit integers are represented by the int  type,  which  has
349       more bits than the binary encoding.  Functions that encode these values
350       truncate their inputs to their least significant bytes.
351
352       val add_uint8 : t -> int -> unit
353
354
355       add_uint8 b i appends a binary unsigned 8-bit integer i to b .
356
357
358       Since 4.08
359
360
361
362       val add_int8 : t -> int -> unit
363
364
365       add_int8 b i appends a binary signed 8-bit integer i to b .
366
367
368       Since 4.08
369
370
371
372       val add_uint16_ne : t -> int -> unit
373
374
375       add_uint16_ne b i appends a binary native-endian unsigned 16-bit  inte‐
376       ger i to b .
377
378
379       Since 4.08
380
381
382
383       val add_uint16_be : t -> int -> unit
384
385
386       add_uint16_be b i appends a binary big-endian unsigned 16-bit integer i
387       to b .
388
389
390       Since 4.08
391
392
393
394       val add_uint16_le : t -> int -> unit
395
396
397       add_uint16_le b i appends a binary little-endian unsigned 16-bit  inte‐
398       ger i to b .
399
400
401       Since 4.08
402
403
404
405       val add_int16_ne : t -> int -> unit
406
407
408       add_int16_ne b i appends a binary native-endian signed 16-bit integer i
409       to b .
410
411
412       Since 4.08
413
414
415
416       val add_int16_be : t -> int -> unit
417
418
419       add_int16_be b i appends a binary big-endian signed 16-bit integer i to
420       b .
421
422
423       Since 4.08
424
425
426
427       val add_int16_le : t -> int -> unit
428
429
430       add_int16_le b i appends a binary little-endian signed 16-bit integer i
431       to b .
432
433
434       Since 4.08
435
436
437
438       val add_int32_ne : t -> int32 -> unit
439
440
441       add_int32_ne b i appends a binary native-endian 32-bit integer i to b .
442
443
444       Since 4.08
445
446
447
448       val add_int32_be : t -> int32 -> unit
449
450
451       add_int32_be b i appends a binary big-endian 32-bit integer i to b .
452
453
454       Since 4.08
455
456
457
458       val add_int32_le : t -> int32 -> unit
459
460
461       add_int32_le b i appends a binary little-endian 32-bit integer i to b .
462
463
464       Since 4.08
465
466
467
468       val add_int64_ne : t -> int64 -> unit
469
470
471       add_int64_ne b i appends a binary native-endian 64-bit integer i to b .
472
473
474       Since 4.08
475
476
477
478       val add_int64_be : t -> int64 -> unit
479
480
481       add_int64_be b i appends a binary big-endian 64-bit integer i to b .
482
483
484       Since 4.08
485
486
487
488       val add_int64_le : t -> int64 -> unit
489
490
491       add_int64_ne b i appends a binary little-endian 64-bit integer i to b .
492
493
494       Since 4.08
495
496
497
498
499
500OCamldoc                          2022-02-04                         Buffer(3)