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
22
23       Unsynchronized accesses
24
25       Unsynchronized  accesses  to  a  buffer  may  lead to an invalid buffer
26       state.  Thus, concurrent accesses to a buffer must be synchronized (for
27       instance with a Mutex.t ).
28
29       type t
30
31
32       The abstract type of buffers.
33
34
35
36       val create : int -> t
37
38
39       create  n  returns a fresh buffer, initially empty.  The n parameter is
40       the initial size of the internal byte sequence that  holds  the  buffer
41       contents.  That  byte  sequence  is automatically reallocated when more
42       than n characters are stored in the buffer, but shrinks back to n char‐
43       acters  when reset is called.  For best performance, n should be of the
44       same order of magnitude as the number of characters that  are  expected
45       to  be  stored  in the buffer (for instance, 80 for a buffer that holds
46       one output line).  Nothing bad will happen if the buffer  grows  beyond
47       that  limit,  however. In doubt, take n = 16 for instance.  If n is not
48       between 1 and Sys.max_string_length , it will be clipped to that inter‐
49       val.
50
51
52
53       val contents : t -> string
54
55       Return a copy of the current contents of the buffer.  The buffer itself
56       is unchanged.
57
58
59
60       val to_bytes : t -> bytes
61
62       Return a copy of the current contents of the buffer.  The buffer itself
63       is unchanged.
64
65
66       Since 4.02
67
68
69
70       val sub : t -> int -> int -> string
71
72
73       Buffer.sub  b off len returns a copy of len bytes from the current con‐
74       tents of the buffer b , starting at offset off .
75
76
77       Raises Invalid_argument if off and len do not designate a  valid  range
78       of b .
79
80
81
82       val blit : t -> int -> bytes -> int -> int -> unit
83
84
85       Buffer.blit  src  srcoff  dst dstoff len copies len characters from the
86       current contents of the buffer src , starting at offset srcoff to dst ,
87       starting at character dstoff .
88
89
90       Since 3.11.2
91
92
93       Raises  Invalid_argument  if  srcoff  and  len do not designate a valid
94       range of src , or if dstoff and len do not designate a valid  range  of
95       dst .
96
97
98
99       val nth : t -> int -> char
100
101       Get the n-th character of the buffer.
102
103
104       Raises Invalid_argument if index out of bounds
105
106
107
108       val length : t -> int
109
110       Return the number of characters currently contained in the buffer.
111
112
113
114       val clear : t -> unit
115
116       Empty the buffer.
117
118
119
120       val reset : t -> unit
121
122       Empty  the buffer and deallocate the internal byte sequence holding the
123       buffer contents, replacing it with the initial internal  byte  sequence
124       of  length  n  that  was allocated by Buffer.create n .  For long-lived
125       buffers that may have grown a lot, reset allows faster  reclamation  of
126       the space used by the buffer.
127
128
129
130       val output_buffer : out_channel -> t -> unit
131
132
133       output_buffer  oc b writes the current contents of buffer b on the out‐
134       put channel oc .
135
136
137
138       val truncate : t -> int -> unit
139
140
141       truncate b len truncates the length of b to len Note: the internal byte
142       sequence is not shortened.
143
144
145       Since 4.05.0
146
147
148       Raises Invalid_argument if len < 0 or len > length b .
149
150
151
152
153   Appending
154       Note:  all  add_* operations can raise Failure if the internal byte se‐
155       quence of the buffer would need to grow beyond Sys.max_string_length .
156
157       val add_char : t -> char -> unit
158
159
160       add_char b c appends the character c at the end of buffer b .
161
162
163
164       val add_utf_8_uchar : t -> Uchar.t -> unit
165
166
167       add_utf_8_uchar b u appends the UTF-8 encoding of u at the end of  buf‐
168       fer b .
169
170
171       Since 4.06.0
172
173
174
175       val add_utf_16le_uchar : t -> Uchar.t -> unit
176
177
178       add_utf_16le_uchar b u appends the UTF-16LE encoding of u at the end of
179       buffer b .
180
181
182       Since 4.06.0
183
184
185
186       val add_utf_16be_uchar : t -> Uchar.t -> unit
187
188
189       add_utf_16be_uchar b u appends the UTF-16BE encoding of u at the end of
190       buffer b .
191
192
193       Since 4.06.0
194
195
196
197       val add_string : t -> string -> unit
198
199
200       add_string b s appends the string s at the end of buffer b .
201
202
203
204       val add_bytes : t -> bytes -> unit
205
206
207       add_bytes b s appends the byte sequence s at the end of buffer b .
208
209
210       Since 4.02
211
212
213
214       val add_substring : t -> string -> int -> int -> unit
215
216
217       add_substring  b  s  ofs  len  takes  len characters from offset ofs in
218       string s and appends them at the end of buffer b .
219
220
221       Raises Invalid_argument if ofs and len do not designate a  valid  range
222       of s .
223
224
225
226       val add_subbytes : t -> bytes -> int -> int -> unit
227
228
229       add_subbytes  b  s ofs len takes len characters from offset ofs in byte
230       sequence s and appends them at the end of buffer b .
231
232
233       Since 4.02
234
235
236       Raises Invalid_argument if ofs and len do not designate a  valid  range
237       of s .
238
239
240
241       val add_substitute : t -> (string -> string) -> string -> unit
242
243
244       add_substitute  b f s appends the string pattern s at the end of buffer
245       b with substitution.  The substitution process looks for variables into
246       the  pattern  and  substitutes  each variable name by its value, as ob‐
247       tained by applying the mapping f  to  the  variable  name.  Inside  the
248       string  pattern,  a  variable  name immediately follows a non-escaped $
249       character and is one of the following:
250
251       -a non empty sequence of alphanumeric or _ characters,
252
253       -an arbitrary sequence of characters enclosed by  a  pair  of  matching
254       parentheses  or curly brackets.  An escaped $ character is a $ that im‐
255       mediately follows a backslash character; it then stands for a plain $ .
256
257
258
259       Raises Not_found if the closing character of a  parenthesized  variable
260       cannot be found.
261
262
263
264       val add_buffer : t -> t -> unit
265
266
267       add_buffer  b1  b2 appends the current contents of buffer b2 at the end
268       of buffer b1 .  b2 is not modified.
269
270
271
272       val add_channel : t -> in_channel -> int -> unit
273
274
275       add_channel b ic n reads at most n characters from the input channel ic
276       and stores them at the end of buffer b .
277
278
279       Raises  End_of_file if the channel contains fewer than n characters. In
280       this case, the characters are still added to the buffer, so as to avoid
281       loss of data.
282
283
284       Raises Invalid_argument if len < 0 or len > Sys.max_string_length .
285
286
287
288
289   Buffers and Sequences
290       val to_seq : t -> char Seq.t
291
292       Iterate on the buffer, in increasing order.
293
294       The  behavior  is not specified if the buffer is modified during itera‐
295       tion.
296
297
298       Since 4.07
299
300
301
302       val to_seqi : t -> (int * char) Seq.t
303
304       Iterate on the buffer, in  increasing  order,  yielding  indices  along
305       chars.
306
307       The  behavior  is not specified if the buffer is modified during itera‐
308       tion.
309
310
311       Since 4.07
312
313
314
315       val add_seq : t -> char Seq.t -> unit
316
317       Add chars to the buffer
318
319
320       Since 4.07
321
322
323
324       val of_seq : char Seq.t -> t
325
326       Create a buffer from the generator
327
328
329       Since 4.07
330
331
332
333
334   Binary encoding of integers
335       The functions in this section append binary encodings  of  integers  to
336       buffers.
337
338       Little-endian (resp. big-endian) encoding means that least (resp. most)
339       significant bytes are stored first.  Big-endian is also known  as  net‐
340       work  byte  order.   Native-endian  encoding is either little-endian or
341       big-endian depending on Sys.big_endian .
342
343       32-bit and 64-bit integers are  represented  by  the  int32  and  int64
344       types, which can be interpreted either as signed or unsigned numbers.
345
346       8-bit  and  16-bit  integers are represented by the int type, which has
347       more bits than the binary encoding.  Functions that encode these values
348       truncate their inputs to their least significant bytes.
349
350       val add_uint8 : t -> int -> unit
351
352
353       add_uint8 b i appends a binary unsigned 8-bit integer i to b .
354
355
356       Since 4.08
357
358
359
360       val add_int8 : t -> int -> unit
361
362
363       add_int8 b i appends a binary signed 8-bit integer i to b .
364
365
366       Since 4.08
367
368
369
370       val add_uint16_ne : t -> int -> unit
371
372
373       add_uint16_ne  b i appends a binary native-endian unsigned 16-bit inte‐
374       ger i to b .
375
376
377       Since 4.08
378
379
380
381       val add_uint16_be : t -> int -> unit
382
383
384       add_uint16_be b i appends a binary big-endian unsigned 16-bit integer i
385       to b .
386
387
388       Since 4.08
389
390
391
392       val add_uint16_le : t -> int -> unit
393
394
395       add_uint16_le  b i appends a binary little-endian unsigned 16-bit inte‐
396       ger i to b .
397
398
399       Since 4.08
400
401
402
403       val add_int16_ne : t -> int -> unit
404
405
406       add_int16_ne b i appends a binary native-endian signed 16-bit integer i
407       to b .
408
409
410       Since 4.08
411
412
413
414       val add_int16_be : t -> int -> unit
415
416
417       add_int16_be b i appends a binary big-endian signed 16-bit integer i to
418       b .
419
420
421       Since 4.08
422
423
424
425       val add_int16_le : t -> int -> unit
426
427
428       add_int16_le b i appends a binary little-endian signed 16-bit integer i
429       to b .
430
431
432       Since 4.08
433
434
435
436       val add_int32_ne : t -> int32 -> unit
437
438
439       add_int32_ne b i appends a binary native-endian 32-bit integer i to b .
440
441
442       Since 4.08
443
444
445
446       val add_int32_be : t -> int32 -> unit
447
448
449       add_int32_be b i appends a binary big-endian 32-bit integer i to b .
450
451
452       Since 4.08
453
454
455
456       val add_int32_le : t -> int32 -> unit
457
458
459       add_int32_le b i appends a binary little-endian 32-bit integer i to b .
460
461
462       Since 4.08
463
464
465
466       val add_int64_ne : t -> int64 -> unit
467
468
469       add_int64_ne b i appends a binary native-endian 64-bit integer i to b .
470
471
472       Since 4.08
473
474
475
476       val add_int64_be : t -> int64 -> unit
477
478
479       add_int64_be b i appends a binary big-endian 64-bit integer i to b .
480
481
482       Since 4.08
483
484
485
486       val add_int64_le : t -> int64 -> unit
487
488
489       add_int64_ne b i appends a binary little-endian 64-bit integer i to b .
490
491
492       Since 4.08
493
494
495
496
497
498OCamldoc                          2023-07-20                  Stdlib.Buffer(3)