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