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 off and len do not designate a  valid  range
70       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 output_buffer : out_channel -> t -> unit
123
124
125       output_buffer  oc b writes the current contents of buffer b on the out‐
126       put channel oc .
127
128
129
130       val truncate : t -> int -> unit
131
132
133       truncate b len truncates the length of b to len Note: the internal byte
134       sequence is not shortened.
135
136
137       Since 4.05.0
138
139
140       Raises Invalid_argument if len < 0 or len > length b .
141
142
143
144
145   Appending
146       Note:  all  add_* operations can raise Failure if the internal byte se‐
147       quence of the buffer would need to grow beyond Sys.max_string_length .
148
149       val add_char : t -> char -> unit
150
151
152       add_char b c appends the character c at the end of buffer b .
153
154
155
156       val add_utf_8_uchar : t -> Uchar.t -> unit
157
158
159       add_utf_8_uchar b u appends the UTF-8 encoding of u at the end of  buf‐
160       fer b .
161
162
163       Since 4.06.0
164
165
166
167       val add_utf_16le_uchar : t -> Uchar.t -> unit
168
169
170       add_utf_16le_uchar b u appends the UTF-16LE encoding of u at the end of
171       buffer b .
172
173
174       Since 4.06.0
175
176
177
178       val add_utf_16be_uchar : t -> Uchar.t -> unit
179
180
181       add_utf_16be_uchar b u appends the UTF-16BE encoding of u at the end of
182       buffer b .
183
184
185       Since 4.06.0
186
187
188
189       val add_string : t -> string -> unit
190
191
192       add_string b s appends the string s at the end of buffer b .
193
194
195
196       val add_bytes : t -> bytes -> unit
197
198
199       add_bytes b s appends the byte sequence s at the end of buffer b .
200
201
202       Since 4.02
203
204
205
206       val add_substring : t -> string -> int -> int -> unit
207
208
209       add_substring  b  s  ofs  len  takes  len characters from offset ofs in
210       string s and appends them at the end of buffer b .
211
212
213       Raises Invalid_argument if ofs and len do not designate a  valid  range
214       of s .
215
216
217
218       val add_subbytes : t -> bytes -> int -> int -> unit
219
220
221       add_subbytes  b  s ofs len takes len characters from offset ofs in byte
222       sequence s and appends them at the end of buffer b .
223
224
225       Since 4.02
226
227
228       Raises Invalid_argument if ofs and len do not designate a  valid  range
229       of s .
230
231
232
233       val add_substitute : t -> (string -> string) -> string -> unit
234
235
236       add_substitute  b f s appends the string pattern s at the end of buffer
237       b with substitution.  The substitution process looks for variables into
238       the  pattern  and  substitutes  each variable name by its value, as ob‐
239       tained by applying the mapping f  to  the  variable  name.  Inside  the
240       string  pattern,  a  variable  name immediately follows a non-escaped $
241       character and is one of the following:
242
243       -a non empty sequence of alphanumeric or _ characters,
244
245       -an arbitrary sequence of characters enclosed by  a  pair  of  matching
246       parentheses  or curly brackets.  An escaped $ character is a $ that im‐
247       mediately follows a backslash character; it then stands for a plain $ .
248
249
250
251       Raises Not_found if the closing character of a  parenthesized  variable
252       cannot be found.
253
254
255
256       val add_buffer : t -> t -> unit
257
258
259       add_buffer  b1  b2 appends the current contents of buffer b2 at the end
260       of buffer b1 .  b2 is not modified.
261
262
263
264       val add_channel : t -> in_channel -> int -> unit
265
266
267       add_channel b ic n reads at most n characters from the input channel ic
268       and stores them at the end of buffer b .
269
270
271       Raises  End_of_file if the channel contains fewer than n characters. In
272       this case, the characters are still added to the buffer, so as to avoid
273       loss of data.
274
275
276       Raises Invalid_argument if len < 0 or len > Sys.max_string_length .
277
278
279
280
281   Buffers and Sequences
282       val to_seq : t -> char Seq.t
283
284       Iterate on the buffer, in increasing order.
285
286       The  behavior  is not specified if the buffer is modified during itera‐
287       tion.
288
289
290       Since 4.07
291
292
293
294       val to_seqi : t -> (int * char) Seq.t
295
296       Iterate on the buffer, in  increasing  order,  yielding  indices  along
297       chars.
298
299       The  behavior  is not specified if the buffer is modified during itera‐
300       tion.
301
302
303       Since 4.07
304
305
306
307       val add_seq : t -> char Seq.t -> unit
308
309       Add chars to the buffer
310
311
312       Since 4.07
313
314
315
316       val of_seq : char Seq.t -> t
317
318       Create a buffer from the generator
319
320
321       Since 4.07
322
323
324
325
326   Binary encoding of integers
327       The functions in this section append binary encodings  of  integers  to
328       buffers.
329
330       Little-endian (resp. big-endian) encoding means that least (resp. most)
331       significant bytes are stored first.  Big-endian is also known  as  net‐
332       work  byte  order.   Native-endian  encoding is either little-endian or
333       big-endian depending on Sys.big_endian .
334
335       32-bit and 64-bit integers are  represented  by  the  int32  and  int64
336       types, which can be interpreted either as signed or unsigned numbers.
337
338       8-bit  and  16-bit  integers are represented by the int type, which has
339       more bits than the binary encoding.  Functions that encode these values
340       truncate their inputs to their least significant bytes.
341
342       val add_uint8 : t -> int -> unit
343
344
345       add_uint8 b i appends a binary unsigned 8-bit integer i to b .
346
347
348       Since 4.08
349
350
351
352       val add_int8 : t -> int -> unit
353
354
355       add_int8 b i appends a binary signed 8-bit integer i to b .
356
357
358       Since 4.08
359
360
361
362       val add_uint16_ne : t -> int -> unit
363
364
365       add_uint16_ne  b i appends a binary native-endian unsigned 16-bit inte‐
366       ger i to b .
367
368
369       Since 4.08
370
371
372
373       val add_uint16_be : t -> int -> unit
374
375
376       add_uint16_be b i appends a binary big-endian unsigned 16-bit integer i
377       to b .
378
379
380       Since 4.08
381
382
383
384       val add_uint16_le : t -> int -> unit
385
386
387       add_uint16_le  b i appends a binary little-endian unsigned 16-bit inte‐
388       ger i to b .
389
390
391       Since 4.08
392
393
394
395       val add_int16_ne : t -> int -> unit
396
397
398       add_int16_ne b i appends a binary native-endian signed 16-bit integer i
399       to b .
400
401
402       Since 4.08
403
404
405
406       val add_int16_be : t -> int -> unit
407
408
409       add_int16_be b i appends a binary big-endian signed 16-bit integer i to
410       b .
411
412
413       Since 4.08
414
415
416
417       val add_int16_le : t -> int -> unit
418
419
420       add_int16_le b i appends a binary little-endian signed 16-bit integer i
421       to b .
422
423
424       Since 4.08
425
426
427
428       val add_int32_ne : t -> int32 -> unit
429
430
431       add_int32_ne b i appends a binary native-endian 32-bit integer i to b .
432
433
434       Since 4.08
435
436
437
438       val add_int32_be : t -> int32 -> unit
439
440
441       add_int32_be b i appends a binary big-endian 32-bit integer i to b .
442
443
444       Since 4.08
445
446
447
448       val add_int32_le : t -> int32 -> unit
449
450
451       add_int32_le b i appends a binary little-endian 32-bit integer i to b .
452
453
454       Since 4.08
455
456
457
458       val add_int64_ne : t -> int64 -> unit
459
460
461       add_int64_ne b i appends a binary native-endian 64-bit integer i to b .
462
463
464       Since 4.08
465
466
467
468       val add_int64_be : t -> int64 -> unit
469
470
471       add_int64_be b i appends a binary big-endian 64-bit integer i to b .
472
473
474       Since 4.08
475
476
477
478       val add_int64_le : t -> int64 -> unit
479
480
481       add_int64_ne b i appends a binary little-endian 64-bit integer i to b .
482
483
484       Since 4.08
485
486
487
488
489
490OCamldoc                          2022-07-22                  Stdlib.Buffer(3)
Impressum