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 linear  time  (in‐
20       stead  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.
299
300       The behavior is not specified if the buffer is modified  during  itera‐
301       tion.
302
303
304       Since 4.07
305
306
307
308       val to_seqi : t -> (int * char) Seq.t
309
310       Iterate  on  the  buffer,  in  increasing order, yielding indices along
311       chars.
312
313       The behavior is not specified if the buffer is modified  during  itera‐
314       tion.
315
316
317       Since 4.07
318
319
320
321       val add_seq : t -> char Seq.t -> unit
322
323       Add chars to the buffer
324
325
326       Since 4.07
327
328
329
330       val of_seq : char Seq.t -> t
331
332       Create a buffer from the generator
333
334
335       Since 4.07
336
337
338
339
340   Binary encoding of integers
341       The  functions  in  this section append binary encodings of integers to
342       buffers.
343
344       Little-endian (resp. big-endian) encoding means that least (resp. most)
345       significant  bytes  are stored first.  Big-endian is also known as net‐
346       work byte order.  Native-endian encoding  is  either  little-endian  or
347       big-endian depending on Sys.big_endian .
348
349       32-bit  and  64-bit  integers  are  represented  by the int32 and int64
350       types, which can be interpreted either as signed or unsigned numbers.
351
352       8-bit and 16-bit integers are represented by the int  type,  which  has
353       more bits than the binary encoding.  Functions that encode these values
354       truncate their inputs to their least significant bytes.
355
356       val add_uint8 : t -> int -> unit
357
358
359       add_uint8 b i appends a binary unsigned 8-bit integer i to b .
360
361
362       Since 4.08
363
364
365
366       val add_int8 : t -> int -> unit
367
368
369       add_int8 b i appends a binary signed 8-bit integer i to b .
370
371
372       Since 4.08
373
374
375
376       val add_uint16_ne : t -> int -> unit
377
378
379       add_uint16_ne b i appends a binary native-endian unsigned 16-bit  inte‐
380       ger i to b .
381
382
383       Since 4.08
384
385
386
387       val add_uint16_be : t -> int -> unit
388
389
390       add_uint16_be b i appends a binary big-endian unsigned 16-bit integer i
391       to b .
392
393
394       Since 4.08
395
396
397
398       val add_uint16_le : t -> int -> unit
399
400
401       add_uint16_le b i appends a binary little-endian unsigned 16-bit  inte‐
402       ger i to b .
403
404
405       Since 4.08
406
407
408
409       val add_int16_ne : t -> int -> unit
410
411
412       add_int16_ne b i appends a binary native-endian signed 16-bit integer i
413       to b .
414
415
416       Since 4.08
417
418
419
420       val add_int16_be : t -> int -> unit
421
422
423       add_int16_be b i appends a binary big-endian signed 16-bit integer i to
424       b .
425
426
427       Since 4.08
428
429
430
431       val add_int16_le : t -> int -> unit
432
433
434       add_int16_le b i appends a binary little-endian signed 16-bit integer i
435       to b .
436
437
438       Since 4.08
439
440
441
442       val add_int32_ne : t -> int32 -> unit
443
444
445       add_int32_ne b i appends a binary native-endian 32-bit integer i to b .
446
447
448       Since 4.08
449
450
451
452       val add_int32_be : t -> int32 -> unit
453
454
455       add_int32_be b i appends a binary big-endian 32-bit integer i to b .
456
457
458       Since 4.08
459
460
461
462       val add_int32_le : t -> int32 -> unit
463
464
465       add_int32_le b i appends a binary little-endian 32-bit integer i to b .
466
467
468       Since 4.08
469
470
471
472       val add_int64_ne : t -> int64 -> unit
473
474
475       add_int64_ne b i appends a binary native-endian 64-bit integer i to b .
476
477
478       Since 4.08
479
480
481
482       val add_int64_be : t -> int64 -> unit
483
484
485       add_int64_be b i appends a binary big-endian 64-bit integer i to b .
486
487
488       Since 4.08
489
490
491
492       val add_int64_le : t -> int64 -> unit
493
494
495       add_int64_ne b i appends a binary little-endian 64-bit integer i to b .
496
497
498       Since 4.08
499
500
501
502
503
504OCamldoc                          2023-01-23                         Buffer(3)