1Stdlib.Buffer(3) OCaml library Stdlib.Buffer(3)
2
3
4
6 Stdlib.Buffer - no description
7
9 Module Stdlib.Buffer
10
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)