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
209       obtained  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
217       immediately follows a backslash character; it then stands for a plain $
218       .
219
220
221
222       Raises Not_found if the closing character of a  parenthesized  variable
223       cannot be found.
224
225
226
227       val add_buffer : t -> t -> unit
228
229
230       add_buffer  b1  b2 appends the current contents of buffer b2 at the end
231       of buffer b1 .  b2 is not modified.
232
233
234
235       val add_channel : t -> in_channel -> int -> unit
236
237
238       add_channel b ic n reads at most n characters from the input channel ic
239       and stores them at the end of buffer b .
240
241
242       Raises  End_of_file if the channel contains fewer than n characters. In
243       this case, the characters are still added to the buffer, so as to avoid
244       loss of data.
245
246
247
248       val output_buffer : out_channel -> t -> unit
249
250
251       output_buffer  oc b writes the current contents of buffer b on the out‐
252       put channel oc .
253
254
255
256       val truncate : t -> int -> unit
257
258
259       truncate b len truncates the length of b to len Note: the internal byte
260       sequence is not shortened.
261
262
263       Since 4.05.0
264
265
266       Raises Invalid_argument if len < 0 or len > length b .
267
268
269
270
271   Iterators
272       val to_seq : t -> char Seq.t
273
274       Iterate on the buffer, in increasing order.  Modification of the buffer
275       during iteration is undefined behavior.
276
277
278       Since 4.07
279
280
281
282       val to_seqi : t -> (int * char) Seq.t
283
284       Iterate on the buffer, in  increasing  order,  yielding  indices  along
285       chars.  Modification of the buffer during iteration is undefined behav‐
286       ior.
287
288
289       Since 4.07
290
291
292
293       val add_seq : t -> char Seq.t -> unit
294
295       Add chars to the buffer
296
297
298       Since 4.07
299
300
301
302       val of_seq : char Seq.t -> t
303
304       Create a buffer from the generator
305
306
307       Since 4.07
308
309
310
311
312   Binary encoding of integers
313       The functions in this section append binary encodings  of  integers  to
314       buffers.
315
316       Little-endian (resp. big-endian) encoding means that least (resp. most)
317       significant bytes are stored first.  Big-endian is also known  as  net‐
318       work  byte  order.   Native-endian  encoding is either little-endian or
319       big-endian depending on Sys.big_endian .
320
321       32-bit and 64-bit integers are  represented  by  the  int32  and  int64
322       types, which can be interpreted either as signed or unsigned numbers.
323
324       8-bit  and  16-bit  integers are represented by the int type, which has
325       more bits than the binary encoding.  Functions that encode these values
326       truncate their inputs to their least significant bytes.
327
328       val add_uint8 : t -> int -> unit
329
330
331       add_uint8 b i appends a binary unsigned 8-bit integer i to b .
332
333
334       Since 4.08
335
336
337
338       val add_int8 : t -> int -> unit
339
340
341       add_int8 b i appends a binary signed 8-bit integer i to b .
342
343
344       Since 4.08
345
346
347
348       val add_uint16_ne : t -> int -> unit
349
350
351       add_uint16_ne  b i appends a binary native-endian unsigned 16-bit inte‐
352       ger i to b .
353
354
355       Since 4.08
356
357
358
359       val add_uint16_be : t -> int -> unit
360
361
362       add_uint16_be b i appends a binary big-endian unsigned 16-bit integer i
363       to b .
364
365
366       Since 4.08
367
368
369
370       val add_uint16_le : t -> int -> unit
371
372
373       add_uint16_le  b i appends a binary little-endian unsigned 16-bit inte‐
374       ger i to b .
375
376
377       Since 4.08
378
379
380
381       val add_int16_ne : t -> int -> unit
382
383
384       add_int16_ne b i appends a binary native-endian signed 16-bit integer i
385       to b .
386
387
388       Since 4.08
389
390
391
392       val add_int16_be : t -> int -> unit
393
394
395       add_int16_be b i appends a binary big-endian signed 16-bit integer i to
396       b .
397
398
399       Since 4.08
400
401
402
403       val add_int16_le : t -> int -> unit
404
405
406       add_int16_le b i appends a binary little-endian signed 16-bit integer i
407       to b .
408
409
410       Since 4.08
411
412
413
414       val add_int32_ne : t -> int32 -> unit
415
416
417       add_int32_ne b i appends a binary native-endian 32-bit integer i to b .
418
419
420       Since 4.08
421
422
423
424       val add_int32_be : t -> int32 -> unit
425
426
427       add_int32_be b i appends a binary big-endian 32-bit integer i to b .
428
429
430       Since 4.08
431
432
433
434       val add_int32_le : t -> int32 -> unit
435
436
437       add_int32_le b i appends a binary little-endian 32-bit integer i to b .
438
439
440       Since 4.08
441
442
443
444       val add_int64_ne : t -> int64 -> unit
445
446
447       add_int64_ne b i appends a binary native-endian 64-bit integer i to b .
448
449
450       Since 4.08
451
452
453
454       val add_int64_be : t -> int64 -> unit
455
456
457       add_int64_be b i appends a binary big-endian 64-bit integer i to b .
458
459
460       Since 4.08
461
462
463
464       val add_int64_le : t -> int64 -> unit
465
466
467       add_int64_ne b i appends a binary little-endian 64-bit integer i to b .
468
469
470       Since 4.08
471
472
473
474
475
476OCamldoc                          2020-09-01                         Buffer(3)