type (='a:level, #'b:level) t
The abstract type of buffers.
val create : 'a int -> ('a, 'b) t
create n
returns a fresh buffer, initially empty.
The n
parameter is the initial size of the internal string
that holds the buffer contents. That string is automatically
reallocated when more than n
characters are stored in the buffer,
but shrinks back to n
characters when reset
is called.
For best performance, n
should be of the same order of magnitude
as the number of characters that are expected to be stored in
the buffer (for instance, 80 for a buffer that holds one output
line). Nothing bad will happen if the buffer grows beyond that
limit, however. In doubt, take n = 16
for instance.
If n
is not between 1 and Sys.max_string_length
, it will
be clipped to that interval.
val contents : ('a, 'b) t -> 'b string
with 'a < 'b
Return a copy of the current contents of the buffer.
The buffer itself is unchanged.
val length : ('a, 'b) t -> 'b int
with 'a < 'b
Return the number of characters currently contained in the buffer.
val clear : ('a, 'a) t -{'a ||}-> unit
Empty the buffer.
val reset : ('a, 'a) t -{'a ||}-> unit
Empty the buffer and deallocate the internal string holding the
buffer contents, replacing it with the initial internal string
of length n
that was allocated by Buffer.create
n
.
For long-lived buffers that may have grown a lot, reset
allows
faster reclamation of the space used by the buffer.
val add_char : ('a, 'a) t -> 'a char -{'a ||}-> unit
add_char b c
appends the character c
at the end of the buffer b
.
val add_substring : ('a, 'a) t ->
'a string -> 'a int -> 'a int -{'a ||}-> unit
add_substring b s ofs len
takes len
characters from offset
ofs
in string s
and appends them at the end of the buffer b
.
val add_string : ('a, 'a) t -> 'a string -{'a ||}-> unit
add_string b s
appends the string s
at the end of the buffer b
.
val add_buffer : ('a, 'a) t -> ('b, 'a) t -{'a ||}-> unit
with 'b < 'a
add_buffer b1 b2
appends the current contents of buffer b2
at the end of buffer b1
. b2
is not modified.
This module implements string buffers that automatically expand as necessary. It provides accumulative concatenation of strings in quasi-linear time (instead of quadratic time when strings are concatenated pairwise).