1Buffer(3) OCaml library Buffer(3)
2
6 Buffer - Extensible buffers.
7
9 Module Buffer
10
12 Module Buffer
13 : sig end
14 Extensible buffers.
17 This module implements buffers that automatically expand as necessary.
19 It provides accumulative concatenation of strings in linear time (in‐
20 stead of quadratic time when strings are concatenated pairwise). For
21 example:
22 let concat_strings ss =
25 let b = Buffer.create 16 in
26 List.iter (Buffer.add_string b) ss;
27 Buffer.contents b
28 Alert unsynchronized_access. Unsynchronized accesses to buffers are a
33 programming error.
34 Unsynchronized accesses
42 Unsynchronized accesses to a buffer may lead to an invalid buffer
44 state. Thus, concurrent accesses to a buffer must be synchronized (for
45 instance with a Mutex.t ).
46 type t
48 The abstract type of buffers.
51 val create : int -> t
55 create n returns a fresh buffer, initially empty. The n parameter is
58 the initial size of the internal byte sequence that holds the buffer
59 contents. That byte sequence is automatically reallocated when more
60 than n characters are stored in the buffer, but shrinks back to n char‐
61 acters when reset is called. For best performance, n should be of the
62 same order of magnitude as the number of characters that are expected
63 to be stored in the buffer (for instance, 80 for a buffer that holds
64 one output line). Nothing bad will happen if the buffer grows beyond
65 that limit, however. In doubt, take n = 16 for instance. If n is not
66 between 1 and Sys.max_string_length , it will be clipped to that inter‐
67 val.
68 val contents : t -> string
72 Return a copy of the current contents of the buffer. The buffer itself
74 is unchanged.
75 val to_bytes : t -> bytes
79 Return a copy of the current contents of the buffer. The buffer itself
81 is unchanged.
82 Since 4.02
85 val sub : t -> int -> int -> string
89 Buffer.sub b off len returns a copy of len bytes from the current con‐
92 tents of the buffer b , starting at offset off .
93 Raises Invalid_argument if off and len do not designate a valid range
96 of b .
97 val blit : t -> int -> bytes -> int -> int -> unit
101 Buffer.blit src srcoff dst dstoff len copies len characters from the
104 current contents of the buffer src , starting at offset srcoff to dst ,
105 starting at character dstoff .
106 Since 3.11.2
109 Raises Invalid_argument if srcoff and len do not designate a valid
112 range of src , or if dstoff and len do not designate a valid range of
113 dst .
114 val nth : t -> int -> char
118 Get the n-th character of the buffer.
120 Raises Invalid_argument if index out of bounds
123 val length : t -> int
127 Return the number of characters currently contained in the buffer.
129 val clear : t -> unit
133 Empty the buffer.
135 val reset : t -> unit
139 Empty the buffer and deallocate the internal byte sequence holding the
141 buffer contents, replacing it with the initial internal byte sequence
142 of length n that was allocated by Buffer.create n . For long-lived
143 buffers that may have grown a lot, reset allows faster reclamation of
144 the space used by the buffer.
145 val output_buffer : out_channel -> t -> unit
149 output_buffer oc b writes the current contents of buffer b on the out‐
152 put channel oc .
153 val truncate : t -> int -> unit
157 truncate b len truncates the length of b to len Note: the internal byte
160 sequence is not shortened.
161 Since 4.05.0
164 Raises Invalid_argument if len < 0 or len > length b .
167 Appending
172 Note: all add_* operations can raise Failure if the internal byte se‐
173 quence of the buffer would need to grow beyond Sys.max_string_length .
174 val add_char : t -> char -> unit
176 add_char b c appends the character c at the end of buffer b .
179 val add_utf_8_uchar : t -> Uchar.t -> unit
183 add_utf_8_uchar b u appends the UTF-8 encoding of u at the end of buf‐
186 fer b .
187 Since 4.06.0
190 val add_utf_16le_uchar : t -> Uchar.t -> unit
194 add_utf_16le_uchar b u appends the UTF-16LE encoding of u at the end of
197 buffer b .
198 Since 4.06.0
201 val add_utf_16be_uchar : t -> Uchar.t -> unit
205 add_utf_16be_uchar b u appends the UTF-16BE encoding of u at the end of
208 buffer b .
209 Since 4.06.0
212 val add_string : t -> string -> unit
216 add_string b s appends the string s at the end of buffer b .
219 val add_bytes : t -> bytes -> unit
223 add_bytes b s appends the byte sequence s at the end of buffer b .
226 Since 4.02
229 val add_substring : t -> string -> int -> int -> unit
233 add_substring b s ofs len takes len characters from offset ofs in
236 string s and appends them at the end of buffer b .
237 Raises Invalid_argument if ofs and len do not designate a valid range
240 of s .
241 val add_subbytes : t -> bytes -> int -> int -> unit
245 add_subbytes b s ofs len takes len characters from offset ofs in byte
248 sequence s and appends them at the end of buffer b .
249 Since 4.02
252 Raises Invalid_argument if ofs and len do not designate a valid range
255 of s .
256 val add_substitute : t -> (string -> string) -> string -> unit
260 add_substitute b f s appends the string pattern s at the end of buffer
263 b with substitution. The substitution process looks for variables into
264 the pattern and substitutes each variable name by its value, as ob‐
265 tained by applying the mapping f to the variable name. Inside the
266 string pattern, a variable name immediately follows a non-escaped $
267 character and is one of the following:
268 -a non empty sequence of alphanumeric or _ characters,
270 -an arbitrary sequence of characters enclosed by a pair of matching
272 parentheses or curly brackets. An escaped $ character is a $ that im‐
273 mediately follows a backslash character; it then stands for a plain $ .
274 Raises Not_found if the closing character of a parenthesized variable
278 cannot be found.
279 val add_buffer : t -> t -> unit
283 add_buffer b1 b2 appends the current contents of buffer b2 at the end
286 of buffer b1 . b2 is not modified.
287 val add_channel : t -> in_channel -> int -> unit
291 add_channel b ic n reads at most n characters from the input channel ic
294 and stores them at the end of buffer b .
295 Raises End_of_file if the channel contains fewer than n characters. In
298 this case, the characters are still added to the buffer, so as to avoid
299 loss of data.
300 Raises Invalid_argument if len < 0 or len > Sys.max_string_length .
303 Buffers and Sequences
308 val to_seq : t -> char Seq.t
309 Iterate on the buffer, in increasing order.
311 The behavior is not specified if the buffer is modified during itera‐
313 tion.
314 Since 4.07
317 val to_seqi : t -> (int * char) Seq.t
321 Iterate on the buffer, in increasing order, yielding indices along
323 chars.
324 The behavior is not specified if the buffer is modified during itera‐
326 tion.
327 Since 4.07
330 val add_seq : t -> char Seq.t -> unit
334 Add chars to the buffer
336 Since 4.07
339 val of_seq : char Seq.t -> t
343 Create a buffer from the generator
345 Since 4.07
348 Binary encoding of integers
353 The functions in this section append binary encodings of integers to
354 buffers.
355 Little-endian (resp. big-endian) encoding means that least (resp. most)
357 significant bytes are stored first. Big-endian is also known as net‐
358 work byte order. Native-endian encoding is either little-endian or
359 big-endian depending on Sys.big_endian .
360 32-bit and 64-bit integers are represented by the int32 and int64
362 types, which can be interpreted either as signed or unsigned numbers.
363 8-bit and 16-bit integers are represented by the int type, which has
365 more bits than the binary encoding. Functions that encode these values
366 truncate their inputs to their least significant bytes.
367 val add_uint8 : t -> int -> unit
369 add_uint8 b i appends a binary unsigned 8-bit integer i to b .
372 Since 4.08
375 val add_int8 : t -> int -> unit
379 add_int8 b i appends a binary signed 8-bit integer i to b .
382 Since 4.08
385 val add_uint16_ne : t -> int -> unit
389 add_uint16_ne b i appends a binary native-endian unsigned 16-bit inte‐
392 ger i to b .
393 Since 4.08
396 val add_uint16_be : t -> int -> unit
400 add_uint16_be b i appends a binary big-endian unsigned 16-bit integer i
403 to b .
404 Since 4.08
407 val add_uint16_le : t -> int -> unit
411 add_uint16_le b i appends a binary little-endian unsigned 16-bit inte‐
414 ger i to b .
415 Since 4.08
418 val add_int16_ne : t -> int -> unit
422 add_int16_ne b i appends a binary native-endian signed 16-bit integer i
425 to b .
426 Since 4.08
429 val add_int16_be : t -> int -> unit
433 add_int16_be b i appends a binary big-endian signed 16-bit integer i to
436 b .
437 Since 4.08
440 val add_int16_le : t -> int -> unit
444 add_int16_le b i appends a binary little-endian signed 16-bit integer i
447 to b .
448 Since 4.08
451 val add_int32_ne : t -> int32 -> unit
455 add_int32_ne b i appends a binary native-endian 32-bit integer i to b .
458 Since 4.08
461 val add_int32_be : t -> int32 -> unit
465 add_int32_be b i appends a binary big-endian 32-bit integer i to b .
468 Since 4.08
471 val add_int32_le : t -> int32 -> unit
475 add_int32_le b i appends a binary little-endian 32-bit integer i to b .
478 Since 4.08
481 val add_int64_ne : t -> int64 -> unit
485 add_int64_ne b i appends a binary native-endian 64-bit integer i to b .
488 Since 4.08
491 val add_int64_be : t -> int64 -> unit
495 add_int64_be b i appends a binary big-endian 64-bit integer i to b .
498 Since 4.08
501 val add_int64_le : t -> int64 -> unit
505 add_int64_ne b i appends a binary little-endian 64-bit integer i to b .
508 Since 4.08
511OCamldoc 2023-07-20 Buffer(3)