Lely core libraries 2.3.4
membuf.h File Reference

This header file is part of the utilities library; it contains the memory buffer declarations. More...

#include <lely/util/util.h>
#include <assert.h>
#include <stddef.h>
#include <string.h>
Include dependency graph for membuf.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct  membuf
 A memory buffer. More...
 

Macros

#define MEMBUF_INIT
 The static initializer for struct membuf.
 

Functions

void membuf_init (struct membuf *buf, void *ptr, size_t size)
 Initializes a memory buffer. More...
 
void membuf_fini (struct membuf *buf)
 Finalizes a memory buffer. More...
 
void * membuf_begin (const struct membuf *buf)
 Returns a pointer to the first byte in a memory buffer.
 
void membuf_clear (struct membuf *buf)
 Clears a memory buffer. More...
 
size_t membuf_size (const struct membuf *buf)
 Returns the total number of bytes written to a memory buffer.
 
size_t membuf_capacity (const struct membuf *buf)
 Returns the number of unused bytes remaining in a memory buffer.
 
size_t membuf_reserve (struct membuf *buf, size_t size)
 Resizes a memory buffer, if necessary, to make room for at least an additional size bytes. More...
 
ptrdiff_t membuf_seek (struct membuf *buf, ptrdiff_t offset)
 Adjusts the position indicator of a memory buffer by offset bytes. More...
 
void * membuf_alloc (struct membuf *buf, size_t *size)
 Creates region of *size bytes in a memory buffer, starting at the current position indicator given by membuf_size(), and sets the indicator to the end of the requested region. More...
 
size_t membuf_write (struct membuf *buf, const void *ptr, size_t size)
 Writes data to a memory buffer. More...
 
void membuf_flush (struct membuf *buf, size_t size)
 Flushes size bytes from the beginning of a memory buffer.
 

Detailed Description

This header file is part of the utilities library; it contains the memory buffer declarations.

Author
J. S. Seldenthuis jseld.nosp@m.enth.nosp@m.uis@l.nosp@m.ely..nosp@m.com

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Definition in file membuf.h.

Function Documentation

◆ membuf_init()

void membuf_init ( struct membuf buf,
void *  ptr,
size_t  size 
)
inline

Initializes a memory buffer.

Parameters
bufa pointer to a memory buffer.
ptra pointer to the memory region to be used by the buffer. If not NULL, the buffer takes ownership of the region at ptr and MAY reallocate or free the region during subsequent calls to membuf_reserve() and membuf_fini().
sizethe number of bytes available at ptr.
See also
membuf_fini()

Definition at line 151 of file membuf.h.

◆ membuf_fini()

void membuf_fini ( struct membuf buf)

Finalizes a memory buffer.

See also
membuf_init()

Definition at line 40 of file membuf.c.

◆ membuf_clear()

void membuf_clear ( struct membuf buf)
inline

Clears a memory buffer.

See also
membuf_flush()

Definition at line 169 of file membuf.h.

◆ membuf_reserve()

size_t membuf_reserve ( struct membuf buf,
size_t  size 
)

Resizes a memory buffer, if necessary, to make room for at least an additional size bytes.

This function may also shrink the buffer if it is larger than required. Although this functions preserves the data already written to the buffer, it invalidates the pointers obtained from previous calls to membuf_alloc().

Parameters
bufa pointer to a memory buffer.
sizethe required capacity of the buffer.
Returns
the new capacity of the buffer, or 0 on error. The new capacity can be larger than the requested capacity.

Definition at line 52 of file membuf.c.

◆ membuf_seek()

ptrdiff_t membuf_seek ( struct membuf buf,
ptrdiff_t  offset 
)
inline

Adjusts the position indicator of a memory buffer by offset bytes.

The offset will be truncated to a valid range: if negative, -offset must not exceed membuf_size(); if positive, offset must not exceed membuf_capacity().

Parameters
bufa pointer to a memory buffer.
offsetthe offset (in bytes) with respect to the current position indicator.
Returns
the actual applied offset.

Definition at line 193 of file membuf.h.

◆ membuf_alloc()

void * membuf_alloc ( struct membuf buf,
size_t *  size 
)
inline

Creates region of *size bytes in a memory buffer, starting at the current position indicator given by membuf_size(), and sets the indicator to the end of the requested region.

If the requested size is larger than the current capacity, *size will be updated with the actual size of the region. If the requested size turns out to be too large or too small, the region can be adjusted with membuf_seek().

Parameters
bufa pointer to a memory buffer.
sizethe address of the value containing the requested size. On exit, *size is updated with the actual size.
Returns
a pointer to a memory region of at least *size consecutive bytes (which may be 0). Note that this pointer is only valid until the next call to membuf_reserve().

Definition at line 211 of file membuf.h.

◆ membuf_write()

size_t membuf_write ( struct membuf buf,
const void *  ptr,
size_t  size 
)
inline

Writes data to a memory buffer.

Writing starts at the current position indicator given by membuf_size().

Parameters
bufa pointer to a memory buffer.
ptra pointer to the data to be copied.
sizethe number of bytes to be written.
Returns
the number of bytes written, which may be smaller than size in case of insufficient capacity.

Definition at line 222 of file membuf.h.