Stdlib.Buffer(3) OCaml library Stdlib.Buffer(3)

# [NAME](#NAME)

Stdlib.Buffer - no description

# [Module](#Module)

Module Stdlib.Buffer

# [Documentation](#Documentation)

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

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

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

## [Appending](#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.0

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

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

*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 variables into the pattern and substitutes each variable name by its value, as obtained by applying the mapping **f** to the variable name. Inside the string pattern, a variable name immediately follows a non-escaped **$** character and 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; it then stands for a plain **$** .

**Raises Not\_found** if the closing character of a parenthesized variable cannot be found.

*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](#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](#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\_ne b i** appends a binary little-endian 64-bit integer **i** to **b** .

**Since** 4.08

2026-10-27 OCamldoc

---

Document: Stdlib.Buffer(3o) from ocaml-4 4.14.4-r4 (Chainguard OS)
Source: https://github.com/ocaml/ocaml