1Stdlib.Buffer(3)                 OCaml library                Stdlib.Buffer(3)
2
3
4

NAME

6       Stdlib.Buffer - no description
7

Module

9       Module   Stdlib.Buffer
10

Documentation

12       Module Buffer
13        : (module Stdlib__buffer)
14
15
16
17
18
19
20
21       type t
22
23
24       The abstract type of buffers.
25
26
27
28       val create : int -> t
29
30
31       create  n  returns a fresh buffer, initially empty.  The n parameter is
32       the initial size of the internal byte sequence that  holds  the  buffer
33       contents.  That  byte  sequence  is automatically reallocated when more
34       than n characters are stored in the buffer, but shrinks back to n char‐
35       acters  when reset is called.  For best performance, n should be of the
36       same order of magnitude as the number of characters that  are  expected
37       to  be  stored  in the buffer (for instance, 80 for a buffer that holds
38       one output line).  Nothing bad will happen if the buffer  grows  beyond
39       that  limit,  however. In doubt, take n = 16 for instance.  If n is not
40       between 1 and Sys.max_string_length , it will be clipped to that inter‐
41       val.
42
43
44
45       val contents : t -> string
46
47       Return a copy of the current contents of the buffer.  The buffer itself
48       is unchanged.
49
50
51
52       val to_bytes : t -> bytes
53
54       Return a copy of the current contents of the buffer.  The buffer itself
55       is unchanged.
56
57
58       Since 4.02
59
60
61
62       val sub : t -> int -> int -> string
63
64
65       Buffer.sub  b off len returns a copy of len bytes from the current con‐
66       tents of the buffer b , starting at offset off .
67
68
69       Raises Invalid_argument if srcoff and len  do  not  designate  a  valid
70       range of b .
71
72
73
74       val blit : t -> int -> bytes -> int -> int -> unit
75
76
77       Buffer.blit  src  srcoff  dst dstoff len copies len characters from the
78       current contents of the buffer src , starting at offset srcoff to dst ,
79       starting at character dstoff .
80
81
82       Since 3.11.2
83
84
85       Raises  Invalid_argument  if  srcoff  and  len do not designate a valid
86       range of src , or if dstoff and len do not designate a valid  range  of
87       dst .
88
89
90
91       val nth : t -> int -> char
92
93       Get the n-th character of the buffer.
94
95
96       Raises Invalid_argument if index 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       .
214
215
216
217       Raises Not_found if the closing character of a  parenthesized  variable
218       cannot be found.
219
220
221
222       val add_buffer : t -> t -> unit
223
224
225       add_buffer  b1  b2 appends the current contents of buffer b2 at the end
226       of buffer b1 .  b2 is not modified.
227
228
229
230       val add_channel : t -> in_channel -> int -> unit
231
232
233       add_channel b ic n reads at most n characters from the input channel ic
234       and stores them at the end of buffer b .
235
236
237       Raises  End_of_file if the channel contains fewer than n characters. In
238       this case, the characters are still added to the buffer, so as to avoid
239       loss of data.
240
241
242
243       val output_buffer : out_channel -> t -> unit
244
245
246       output_buffer  oc b writes the current contents of buffer b on the out‐
247       put channel oc .
248
249
250
251       val truncate : t -> int -> unit
252
253
254       truncate b len truncates the length of b to len Note: the internal byte
255       sequence is not shortened.
256
257
258       Since 4.05.0
259
260
261       Raises Invalid_argument if len < 0 or len > length b .
262
263
264
265
266   Iterators
267       val to_seq : t -> char Seq.t
268
269       Iterate on the buffer, in increasing order.  Modification of the buffer
270       during iteration is undefined behavior.
271
272
273       Since 4.07
274
275
276
277       val to_seqi : t -> (int * char) Seq.t
278
279       Iterate on the buffer, in  increasing  order,  yielding  indices  along
280       chars.  Modification of the buffer during iteration is undefined behav‐
281       ior.
282
283
284       Since 4.07
285
286
287
288       val add_seq : t -> char Seq.t -> unit
289
290       Add chars to the buffer
291
292
293       Since 4.07
294
295
296
297       val of_seq : char Seq.t -> t
298
299       Create a buffer from the generator
300
301
302       Since 4.07
303
304
305
306
307   Binary encoding of integers
308       The functions in this section append binary encodings  of  integers  to
309       buffers.
310
311       Little-endian (resp. big-endian) encoding means that least (resp. most)
312       significant bytes are stored first.  Big-endian is also known  as  net‐
313       work  byte  order.   Native-endian  encoding is either little-endian or
314       big-endian depending on Sys.big_endian .
315
316       32-bit and 64-bit integers are  represented  by  the  int32  and  int64
317       types, which can be interpreted either as signed or unsigned numbers.
318
319       8-bit  and  16-bit  integers are represented by the int type, which has
320       more bits than the binary encoding.  Functions that encode these values
321       truncate their inputs to their least significant bytes.
322
323       val add_uint8 : t -> int -> unit
324
325
326       add_uint8 b i appends a binary unsigned 8-bit integer i to b .
327
328
329       Since 4.08
330
331
332
333       val add_int8 : t -> int -> unit
334
335
336       add_int8 b i appends a binary signed 8-bit integer i to b .
337
338
339       Since 4.08
340
341
342
343       val add_uint16_ne : t -> int -> unit
344
345
346       add_uint16_ne  b i appends a binary native-endian unsigned 16-bit inte‐
347       ger i to b .
348
349
350       Since 4.08
351
352
353
354       val add_uint16_be : t -> int -> unit
355
356
357       add_uint16_be b i appends a binary big-endian unsigned 16-bit integer i
358       to b .
359
360
361       Since 4.08
362
363
364
365       val add_uint16_le : t -> int -> unit
366
367
368       add_uint16_le  b i appends a binary little-endian unsigned 16-bit inte‐
369       ger i to b .
370
371
372       Since 4.08
373
374
375
376       val add_int16_ne : t -> int -> unit
377
378
379       add_int16_ne b i appends a binary native-endian signed 16-bit integer i
380       to b .
381
382
383       Since 4.08
384
385
386
387       val add_int16_be : t -> int -> unit
388
389
390       add_int16_be b i appends a binary big-endian signed 16-bit integer i to
391       b .
392
393
394       Since 4.08
395
396
397
398       val add_int16_le : t -> int -> unit
399
400
401       add_int16_le b i appends a binary little-endian signed 16-bit integer i
402       to b .
403
404
405       Since 4.08
406
407
408
409       val add_int32_ne : t -> int32 -> unit
410
411
412       add_int32_ne b i appends a binary native-endian 32-bit integer i to b .
413
414
415       Since 4.08
416
417
418
419       val add_int32_be : t -> int32 -> unit
420
421
422       add_int32_be b i appends a binary big-endian 32-bit integer i to b .
423
424
425       Since 4.08
426
427
428
429       val add_int32_le : t -> int32 -> unit
430
431
432       add_int32_le b i appends a binary little-endian 32-bit integer i to b .
433
434
435       Since 4.08
436
437
438
439       val add_int64_ne : t -> int64 -> unit
440
441
442       add_int64_ne b i appends a binary native-endian 64-bit integer i to b .
443
444
445       Since 4.08
446
447
448
449       val add_int64_be : t -> int64 -> unit
450
451
452       add_int64_be b i appends a binary big-endian 64-bit integer i to b .
453
454
455       Since 4.08
456
457
458
459       val add_int64_le : t -> int64 -> unit
460
461
462       add_int64_ne b i appends a binary little-endian 64-bit integer i to b .
463
464
465       Since 4.08
466
467
468
469
470
471OCamldoc                          2020-09-01                  Stdlib.Buffer(3)