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
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)