---
name: "Stdlib.Buffer"
section: "3o"
platform: "linux"
package: "ocaml"
version: "5.5.0-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/Stdlib.Buffer"
---

# Stdlib.Buffer(3o)

no description

## NAME

Stdlib.Buffer - no description

## Module

Module   Stdlib.Buffer

## Documentation

Module **Buffer**\
  :  **(module Stdlib\_\_Buffer)**

### Capacity and reallocation strategy

Internally, a buffer uses a backing store (a byte sequence) whose size, called the capacity, is greater or equal to the number of characters stored in the buffer (its length).

The implementation uses a standard exponential reallocation strategy which guarantees amortized constant-time operation; in particular, the total size of all backing stores allocated over the lifetime of a buffer is at worst proportional to the total number of characters added.

**Buffer.clear** preserves the current backing store (so no memory is freed), while **Buffer.reset** frees the current backing store, releasing memory at the price of potentially having to reallocate later on.

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

*type t*

The abstract type of buffers.

*val create* :  **int -\> t**

**create n** 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.

*val contents* :  **t -\> string**

Return a copy of the current contents of the buffer. The buffer itself is unchanged.

*val to\_bytes* :  **t -\> bytes**

Return a copy of the current contents of the buffer. The buffer itself is unchanged.

**Since** 4.02

*val sub* :  **t -\> int -\> int -\> string**

**Buffer.sub b off len** returns a copy of  **len** bytes from the current contents of the buffer  **b** , starting at offset  **off** .

**Raises Invalid\_argument** if  **off** and  **len** do not designate a valid range of  **b** .

*val blit* :  **t -\> int -\> bytes -\> int -\> int -\> unit**

**Buffer.blit src srcoff dst dstoff len** 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

**Raises Invalid\_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** .

*val nth* :  **t -\> int -\> char**

Get the n-th character of the buffer.

**Raises Invalid\_argument** if index out of bounds

*val length* :  **t -\> int**

Return the number of characters currently contained in the buffer.

*val clear* :  **t -\> unit**

Empty the buffer.

*val reset* :  **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.create** **n** . For long-lived buffers that may have grown a lot,  **reset** allows faster reclamation of the space used by the buffer.

*val output\_buffer* :  **out\_channel -\> t -\> unit**

**output\_buffer oc b** writes the current contents of buffer  **b** on the output channel  **oc** .

*val truncate* :  **t -\> int -\> unit**

**truncate b len** truncates the length of  **b** to  **len** Note: the internal byte sequence is not shortened.

**Since** 4.05

**Raises Invalid\_argument** if  **len \< 0** or  **len \> length b** .

### 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** .

*val add\_char* :  **t -\> char -\> unit**

**add\_char b c** appends the character  **c** at the end of buffer  **b** .

*val add\_utf\_8\_uchar* :  **t -\> Uchar.t -\> unit**

**add\_utf\_8\_uchar b u** appends the  UTF-8 encoding of  **u** at the end of buffer  **b** .

**Since** 4.06

*val add\_utf\_16le\_uchar* :  **t -\> Uchar.t -\> unit**

**add\_utf\_16le\_uchar b u** appends the UTF-16LE encoding of  **u** at the end of buffer  **b** .

**Since** 4.06

*val add\_utf\_16be\_uchar* :  **t -\> Uchar.t -\> unit**

**add\_utf\_16be\_uchar b u** appends the UTF-16BE encoding of  **u** at the end of buffer  **b** .

**Since** 4.06

*val add\_string* :  **t -\> string -\> unit**

**add\_string b s** appends the string  **s** at the end of buffer  **b** .

*val add\_bytes* :  **t -\> bytes -\> unit**

**add\_bytes b s** appends the byte sequence  **s** at the end of buffer  **b** .

**Since** 4.02

*val add\_substring* :  **t -\> string -\> int -\> int -\> unit**

**add\_substring b s ofs len** takes  **len** characters from offset **ofs** in string  **s** and appends them at the end of buffer  **b** .

**Raises Invalid\_argument** if  **ofs** and  **len** do not designate a valid range of  **s** .

*val add\_subbytes* :  **t -\> bytes -\> int -\> int -\> unit**

**add\_subbytes b s ofs len** takes  **len** characters from offset **ofs** in byte sequence  **s** and appends them at the end of buffer  **b** .

**Since** 4.02

**Raises Invalid\_argument** if  **ofs** and  **len** do not designate a valid range of  **s** .

*val add\_substitute* :  **t -\> (string -\> string) -\> string -\> unit**

**add\_substitute b f s** 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  **$** .

*val add\_buffer* :  **t -\> t -\> unit**

**add\_buffer b1 b2** appends the current contents of buffer  **b2** at the end of buffer  **b1** .   **b2** is not modified.

*val add\_channel* :  **t -\> in\_channel -\> int -\> unit**

**add\_channel b ic n** reads at most  **n** characters from the input channel  **ic** and stores them at the end of buffer  **b** .

**Raises End\_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.

**Raises Invalid\_argument** if  **len \< 0** or  **len \> Sys.max\_string\_length** .

### Buffers and Sequences

*val to\_seq* :  **t -\> char Seq.t**

Iterate on the buffer, in increasing order.

The behavior is not specified if the buffer is modified during iteration.

**Since** 4.07

*val to\_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

*val add\_seq* :  **t -\> char Seq.t -\> unit**

Add chars to the buffer

**Since** 4.07

*val of\_seq* :  **char Seq.t -\> t**

Create a buffer from the generator

**Since** 4.07

### Binary encoding of integers

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.

*val add\_uint8* :  **t -\> int -\> unit**

**add\_uint8 b i** appends a binary unsigned 8-bit integer  **i** to **b** .

**Since** 4.08

*val add\_int8* :  **t -\> int -\> unit**

**add\_int8 b i** appends a binary signed 8-bit integer  **i** to **b** .

**Since** 4.08

*val add\_uint16\_ne* :  **t -\> int -\> unit**

**add\_uint16\_ne b i** appends a binary native-endian unsigned 16-bit integer  **i** to  **b** .

**Since** 4.08

*val add\_uint16\_be* :  **t -\> int -\> unit**

**add\_uint16\_be b i** appends a binary big-endian unsigned 16-bit integer  **i** to  **b** .

**Since** 4.08

*val add\_uint16\_le* :  **t -\> int -\> unit**

**add\_uint16\_le b i** appends a binary little-endian unsigned 16-bit integer  **i** to  **b** .

**Since** 4.08

*val add\_int16\_ne* :  **t -\> int -\> unit**

**add\_int16\_ne b i** appends a binary native-endian signed 16-bit integer  **i** to  **b** .

**Since** 4.08

*val add\_int16\_be* :  **t -\> int -\> unit**

**add\_int16\_be b i** appends a binary big-endian signed 16-bit integer  **i** to  **b** .

**Since** 4.08

*val add\_int16\_le* :  **t -\> int -\> unit**

**add\_int16\_le b i** appends a binary little-endian signed 16-bit integer  **i** to  **b** .

**Since** 4.08

*val add\_int32\_ne* :  **t -\> int32 -\> unit**

**add\_int32\_ne b i** appends a binary native-endian 32-bit integer **i** to  **b** .

**Since** 4.08

*val add\_int32\_be* :  **t -\> int32 -\> unit**

**add\_int32\_be b i** appends a binary big-endian 32-bit integer **i** to  **b** .

**Since** 4.08

*val add\_int32\_le* :  **t -\> int32 -\> unit**

**add\_int32\_le b i** appends a binary little-endian 32-bit integer **i** to  **b** .

**Since** 4.08

*val add\_int64\_ne* :  **t -\> int64 -\> unit**

**add\_int64\_ne b i** appends a binary native-endian 64-bit integer **i** to  **b** .

**Since** 4.08

*val add\_int64\_be* :  **t -\> int64 -\> unit**

**add\_int64\_be b i** appends a binary big-endian 64-bit integer **i** to  **b** .

**Since** 4.08

*val add\_int64\_le* :  **t -\> int64 -\> unit**

**add\_int64\_le b i** appends a binary little-endian 64-bit integer **i** to  **b** .

**Since** 4.08