Module Buffer
: (moduleStdlib__Buffer)
Unsynchronized accesses
Unsynchronized accesses to a buffer may lead to an invalid buffer state. Thus, concurrent accesses to a
buffer must be synchronized (for instance with a Mutex.t ).
typet
The abstract type of buffers.
valcreate : int->tcreaten returns a fresh buffer, initially empty. The n parameter is the initial size of the internal
byte sequence that holds the buffer contents. That byte sequence 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.
valcontents : t->string
Return a copy of the current contents of the buffer. The buffer itself is unchanged.
valto_bytes : t->bytes
Return a copy of the current contents of the buffer. The buffer itself is unchanged.
Since 4.02
valsub : t->int->int->stringBuffer.subbofflen returns a copy of len bytes from the current contents of the buffer b , starting at
offset off .
RaisesInvalid_argument if off and len do not designate a valid range of b .
valblit : t->int->bytes->int->int->unitBuffer.blitsrcsrcoffdstdstofflen copies len characters from the current contents of the buffer src ,
starting at offset srcoff to dst , starting at character dstoff .
Since 3.11.2
RaisesInvalid_argument if srcoff and len do not designate a valid range of src , or if dstoff and len do
not designate a valid range of dst .
valnth : t->int->char
Get the n-th character of the buffer.
RaisesInvalid_argument if index out of bounds
vallength : t->int
Return the number of characters currently contained in the buffer.
valclear : t->unit
Empty the buffer.
valreset : t->unit
Empty the buffer and deallocate the internal byte sequence holding the buffer contents, replacing it with
the initial internal byte sequence of length n that was allocated by Buffer.createn . For long-lived
buffers that may have grown a lot, reset allows faster reclamation of the space used by the buffer.
valoutput_buffer : out_channel->t->unitoutput_bufferocb writes the current contents of buffer b on the output channel oc .
valtruncate : t->int->unittruncateblen truncates the length of b to len Note: the internal byte sequence is not shortened.
Since 4.05
RaisesInvalid_argument if len<0 or len>lengthb .
Appending
Note: all add_* operations can raise Failure if the internal byte sequence of the buffer would need to
grow beyond Sys.max_string_length .
valadd_char : t->char->unitadd_charbc appends the character c at the end of buffer b .
valadd_utf_8_uchar : t->Uchar.t->unitadd_utf_8_ucharbu appends the UTF-8 encoding of u at the end of buffer b .
Since 4.06
valadd_utf_16le_uchar : t->Uchar.t->unitadd_utf_16le_ucharbu appends the UTF-16LE encoding of u at the end of buffer b .
Since 4.06
valadd_utf_16be_uchar : t->Uchar.t->unitadd_utf_16be_ucharbu appends the UTF-16BE encoding of u at the end of buffer b .
Since 4.06
valadd_string : t->string->unitadd_stringbs appends the string s at the end of buffer b .
valadd_bytes : t->bytes->unitadd_bytesbs appends the byte sequence s at the end of buffer b .
Since 4.02
valadd_substring : t->string->int->int->unitadd_substringbsofslen takes len characters from offset ofs in string s and appends them at the end of
buffer b .
RaisesInvalid_argument if ofs and len do not designate a valid range of s .
valadd_subbytes : t->bytes->int->int->unitadd_subbytesbsofslen takes len characters from offset ofs in byte sequence s and appends them at the
end of buffer b .
Since 4.02
RaisesInvalid_argument if ofs and len do not designate a valid range of s .
valadd_substitute : t->(string->string)->string->unitadd_substitutebfs appends the string pattern s at the end of buffer b with substitution. The
substitution process looks for variable references in the pattern and substitutes each variable reference
with its value, as obtained by applying the mapping f to the variable name. Inside the string pattern, a
variable reference is a non-escaped $ immediately followed by a variable name, which is one of the
following:
-a non empty sequence of alphanumeric or _ characters,
-an arbitrary sequence of characters enclosed by a pair of matching parentheses or curly brackets. An
escaped $ character is a $ that immediately follows a backslash character; the two characters together
stand for a plain $ .
valadd_buffer : t->t->unitadd_bufferb1b2 appends the current contents of buffer b2 at the end of buffer b1 . b2 is not modified.
valadd_channel : t->in_channel->int->unitadd_channelbicn reads at most n characters from the input channel ic and stores them at the end of
buffer b .
RaisesEnd_of_file if the channel contains fewer than n characters. In this case, the characters are
still added to the buffer, so as to avoid loss of data.
RaisesInvalid_argument if len<0 or len>Sys.max_string_length .
BuffersandSequencesvalto_seq : t->charSeq.t
Iterate on the buffer, in increasing order.
The behavior is not specified if the buffer is modified during iteration.
Since 4.07
valto_seqi : t->(int*char)Seq.t
Iterate on the buffer, in increasing order, yielding indices along chars.
The behavior is not specified if the buffer is modified during iteration.
Since 4.07
valadd_seq : t->charSeq.t->unit
Add chars to the buffer
Since 4.07
valof_seq : charSeq.t->t
Create a buffer from the generator
Since 4.07
Binaryencodingofintegers
The functions in this section append binary encodings of integers to buffers.
Little-endian (resp. big-endian) encoding means that least (resp. most) significant bytes are stored
first. Big-endian is also known as network byte order. Native-endian encoding is either little-endian
or big-endian depending on Sys.big_endian .
32-bit and 64-bit integers are represented by the int32 and int64 types, which can be interpreted either
as signed or unsigned numbers.
8-bit and 16-bit integers are represented by the int type, which has more bits than the binary encoding.
Functions that encode these values truncate their inputs to their least significant bytes.
valadd_uint8 : t->int->unitadd_uint8bi appends a binary unsigned 8-bit integer i to b .
Since 4.08
valadd_int8 : t->int->unitadd_int8bi appends a binary signed 8-bit integer i to b .
Since 4.08
valadd_uint16_ne : t->int->unitadd_uint16_nebi appends a binary native-endian unsigned 16-bit integer i to b .
Since 4.08
valadd_uint16_be : t->int->unitadd_uint16_bebi appends a binary big-endian unsigned 16-bit integer i to b .
Since 4.08
valadd_uint16_le : t->int->unitadd_uint16_lebi appends a binary little-endian unsigned 16-bit integer i to b .
Since 4.08
valadd_int16_ne : t->int->unitadd_int16_nebi appends a binary native-endian signed 16-bit integer i to b .
Since 4.08
valadd_int16_be : t->int->unitadd_int16_bebi appends a binary big-endian signed 16-bit integer i to b .
Since 4.08
valadd_int16_le : t->int->unitadd_int16_lebi appends a binary little-endian signed 16-bit integer i to b .
Since 4.08
valadd_int32_ne : t->int32->unitadd_int32_nebi appends a binary native-endian 32-bit integer i to b .
Since 4.08
valadd_int32_be : t->int32->unitadd_int32_bebi appends a binary big-endian 32-bit integer i to b .
Since 4.08
valadd_int32_le : t->int32->unitadd_int32_lebi appends a binary little-endian 32-bit integer i to b .
Since 4.08
valadd_int64_ne : t->int64->unitadd_int64_nebi appends a binary native-endian 64-bit integer i to b .
Since 4.08
valadd_int64_be : t->int64->unitadd_int64_bebi appends a binary big-endian 64-bit integer i to b .
Since 4.08
valadd_int64_le : t->int64->unitadd_int64_nebi appends a binary little-endian 64-bit integer i to b .
Since 4.08
OCamldoc 2025-06-12 Stdlib.Buffer(3o)
Install Now
PNG Icons
