1Buffer(3)                        OCaml library                       Buffer(3)
2
3
4

NAME

6       Buffer - Extensible buffers.
7

Module

9       Module   Buffer
10

Documentation

12       Module Buffer
13        : sig end
14
15
16       Extensible buffers.
17
18       This  module implements buffers that automatically expand as necessary.
19       It provides accumulative concatenation of strings in quasi-linear  time
20       (instead of quadratic time when strings are concatenated pairwise).
21
22
23
24
25
26       type t
27
28
29       The abstract type of buffers.
30
31
32
33       val create : int -> t
34
35
36       create  n  returns a fresh buffer, initially empty.  The n parameter is
37       the initial size of the internal byte sequence that  holds  the  buffer
38       contents.  That  byte  sequence  is automatically reallocated when more
39       than n characters are stored in the buffer, but shrinks back to n char‐
40       acters  when reset is called.  For best performance, n should be of the
41       same order of magnitude as the number of characters that  are  expected
42       to  be  stored  in the buffer (for instance, 80 for a buffer that holds
43       one output line).  Nothing bad will happen if the buffer  grows  beyond
44       that  limit,  however. In doubt, take n = 16 for instance.  If n is not
45       between 1 and Sys.max_string_length , it will be clipped to that inter‐
46       val.
47
48
49
50       val contents : t -> string
51
52       Return a copy of the current contents of the buffer.  The buffer itself
53       is unchanged.
54
55
56
57       val to_bytes : t -> bytes
58
59       Return a copy of the current contents of the buffer.  The buffer itself
60       is unchanged.
61
62
63       Since 4.02
64
65
66
67       val sub : t -> int -> int -> string
68
69
70       Buffer.sub  b off len returns a copy of len bytes from the current con‐
71       tents of the buffer b , starting at offset off .
72
73       Raise Invalid_argument if srcoff and len do not designate a valid range
74       of b .
75
76
77
78       val blit : t -> int -> bytes -> int -> int -> unit
79
80
81       Buffer.blit  src  srcoff  dst dstoff len copies len characters from the
82       current contents of the buffer src , starting at offset srcoff to dst ,
83       starting at character dstoff .
84
85       Raise Invalid_argument if srcoff and len do not designate a valid range
86       of src , or if dstoff and len do not designate a valid range of dst .
87
88
89       Since 3.11.2
90
91
92
93       val nth : t -> int -> char
94
95       Get the n-th character of the buffer. Raise Invalid_argument  if  index
96       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       .  Raise Not_found if the closing character of a parenthesized variable
214       cannot be found.
215
216
217
218
219       val add_buffer : t -> t -> unit
220
221
222       add_buffer  b1  b2 appends the current contents of buffer b2 at the end
223       of buffer b1 .  b2 is not modified.
224
225
226
227       val add_channel : t -> Pervasives.in_channel -> int -> unit
228
229
230       add_channel b ic n reads at most n characters from the input channel ic
231       and  stores  them  at  the  end of buffer b .  Raise End_of_file if the
232       channel contains fewer than n characters. In this case, the  characters
233       are still added to the buffer, so as to avoid loss of data.
234
235
236
237       val output_buffer : Pervasives.out_channel -> t -> unit
238
239
240       output_buffer  oc b writes the current contents of buffer b on the out‐
241       put channel oc .
242
243
244
245       val truncate : t -> int -> unit
246
247
248       truncate b len truncates the length of b to len Note: the internal byte
249       sequence  is not shortened.  Raise Invalid_argument if len < 0 or len >
250       length b .
251
252
253       Since 4.05.0
254
255
256
257
258       === Iterators ===
259
260
261       val to_seq : t -> char Seq.t
262
263       Iterate on the buffer, in increasing order.  Modification of the buffer
264       during iteration is undefined behavior.
265
266
267       Since 4.07
268
269
270
271       val to_seqi : t -> (int * char) Seq.t
272
273       Iterate  on  the  buffer,  in  increasing order, yielding indices along
274       chars.  Modification of the buffer during iteration is undefined behav‐
275       ior.
276
277
278       Since 4.07
279
280
281
282       val add_seq : t -> char Seq.t -> unit
283
284       Add chars to the buffer
285
286
287       Since 4.07
288
289
290
291       val of_seq : char Seq.t -> t
292
293       Create a buffer from the generator
294
295
296       Since 4.07
297
298
299
300
301
302OCamldoc                          2019-02-02                         Buffer(3)