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