=== Memory Buffers

Mbufs are mutable/growing memory buffers, like C++ strings.
Mbuf can append data to the end of a buffer, or insert data into arbitrary
position in the middle of a buffer. The buffer grows automatically when
needed. 

==== struct mbuf

[source,c]
----
struct mbuf {
  char *buf;   /* Buffer pointer */
  size_t len;  /* Data length. Data is located between offset 0 and len. */
  size_t size; /* Buffer size allocated by realloc(1). Must be >= len */
};
----
Memory buffer descriptor 

==== mbuf_init()

[source,c]
----
void mbuf_init(struct mbuf *, size_t initial_capacity);
----
Initialize an Mbuf.
`initial_capacity` specifies the initial capacity of the mbuf. 

==== mbuf_free()

[source,c]
----
void mbuf_free(struct mbuf *);
----
Free the space allocated for the mbuffer and resets the mbuf structure. 

==== mbuf_append()

[source,c]
----
size_t mbuf_append(struct mbuf *, const void *data, size_t data_size);
----
Appends data to the Mbuf.

Return the number of bytes appended, or 0 if out of memory. 

==== mbuf_insert()

[source,c]
----
size_t mbuf_insert(struct mbuf *, size_t, const void *, size_t);
----
Insert data at a specified offset in the Mbuf.

Existing data will be shifted forwards and the buffer will
be grown if necessary.
Return the number of bytes inserted. 

==== mbuf_remove()

[source,c]
----
void mbuf_remove(struct mbuf *, size_t data_size);
----
Remove `data_size` bytes from the beginning of the buffer. 

==== mbuf_resize()

[source,c]
----
void mbuf_resize(struct mbuf *, size_t new_size);
----
Resize an Mbuf.

If `new_size` is smaller than buffer's `len`, the
resize is not performed. 

==== mbuf_trim()

[source,c]
----
void mbuf_trim(struct mbuf *);
----
Shrink an Mbuf by resizing its `size` to `len`.