gi_buffer.h File Reference

Simple dynamically growable buffer object. More...

Go to the source code of this file.

Classes
struct	GiBuffer
Functions
EXTERN_C_BEGIN LIBGIFT_EXPORT void	gi_buffer_init (GiBuffer *buffer)
LIBGIFT_EXPORT void	gi_buffer_initex (GiBuffer *buffer, void *buf, size_t siz, size_t len, bool rsz)
LIBGIFT_EXPORT void	gi_buffer_finish (GiBuffer *buffer)
LIBGIFT_EXPORT bool	gi_buffer_grow (GiBuffer *buffer, size_t grown)
LIBGIFT_EXPORT bool	gi_buffer_shrink (GiBuffer *buffer, size_t shrunk)
LIBGIFT_EXPORT bool	gi_buffer_double (GiBuffer *buffer)
LIBGIFT_EXPORT bool	gi_buffer_resize (GiBuffer *buffer, size_t size)
LIBGIFT_EXPORT bool	gi_buffer_minsize (GiBuffer *buffer, size_t minsize)
LIBGIFT_EXPORT size_t	gi_buffer_handy (GiBuffer *buffer)
LIBGIFT_EXPORT bool	gi_buffer_append (GiBuffer *buffer, const void *buf, size_t siz)
LIBGIFT_EXPORT bool	gi_buffer_prepend (GiBuffer *buffer, const void *buf, size_t siz)
LIBGIFT_EXPORT bool	gi_buffer_truncate (GiBuffer *buffer, size_t len)
LIBGIFT_EXPORT void *	gi_buffer_tail (GiBuffer *buffer)
LIBGIFT_EXPORT void *	gi_buffer_head (GiBuffer *buffer)

---

Detailed Description

Simple dynamically growable buffer object.

---

Function Documentation

LIBGIFT_EXPORT bool gi_buffer_append (  GiBuffer *  buffer, const void *  buf, size_t  siz )

Append `siz' bytes from the user-supplied data buffer `buf' to the internal data buffer object. Returns: If all bytes are successfully added, true is returned; otherwise, there was not enough room to store the entire buffer and false is returned.

LIBGIFT_EXPORT bool gi_buffer_double (  GiBuffer *  buffer  )

Attempt to allocate at least twice as much total space as is currently allocated to the buffer. Returns: If the resize succeeds, true is returned; otherwise, false.

LIBGIFT_EXPORT void gi_buffer_finish (  GiBuffer *  buffer  )

Destroy any internally allocated data blocks. This function is optional depending on whether or not you actually want to clean up the internal memory buffer.

LIBGIFT_EXPORT bool gi_buffer_grow (  GiBuffer *  buffer, size_t  grown )

Guarantee that at least `grown' additional bytes will be available in the buffer. This does not actually guarantee that the buffer will be resized, simply that if the call succeeds, the difference between the total size and the current length will be at least `grown' bytes. Returns: If requested number of bytes is satisfied, true is returned. If realloc failed or the buffer is not resizeable, false is returned.

LIBGIFT_EXPORT size_t gi_buffer_handy (  GiBuffer *  buffer  )

Access the total number of trailing bytes in the buffer currently unused. Returns: Number of bytes between the current maximum allocated size and the length.

LIBGIFT_EXPORT void* gi_buffer_head (  GiBuffer *  buffer  )

Access the first byte found in the data buffer. This may return NULL if the data buffer has not been allocated, or if there is no data written.

EXTERN_C_BEGIN LIBGIFT_EXPORT void gi_buffer_init (  GiBuffer *  buffer  )

Initialize a buffer object. This may allocate data to the object which can be cleaned up by gi_buffer_finish.

LIBGIFT_EXPORT void gi_buffer_initex (  GiBuffer *  buffer, void *  buf, size_t  siz, size_t  len, bool  rsz )

Initialize the buffer object with a user-supplied data buffer. All writes through this interface will be applied to the user-supplied object. Parameters: buffer  buf  User-supplied data buffer. This data buffer must be able to store at least `siz' bytes. siz  Number of bytes that the user-supplied buffer can store. If `rsz' is true, the buffer may be expanded to support more than this initial size. len  Number of bytes currently written to the data buffer. The data written in the first `len' bytes of the buffer will be preserved as though it was written with this interface. rsz  Controls whether or not the buffer can be resized with realloc(). If false, it will be an error to write any amount of data beyond `siz' bytes. The data will not be truncated if it cannot be completely written.

LIBGIFT_EXPORT bool gi_buffer_minsize (  GiBuffer *  buffer, size_t  minsize )

Resize the data buffer to at least `size' total bytes. Returns: If the resize succeeds, true is returned; otherwise, false.

LIBGIFT_EXPORT bool gi_buffer_prepend (  GiBuffer *  buffer, const void *  buf, size_t  siz )

Similar to gi_buffer_append, except that the data will be prepended to the beginning of the data buffer. The entire length of the buffer is shifted back `siz' bytes.

LIBGIFT_EXPORT bool gi_buffer_resize (  GiBuffer *  buffer, size_t  size )

Resize the data buffer to exactly `size' total bytes. This may result in an implicit truncation of the buffer's length if there is not space available after the resize. Returns: If the resize succeeds, true is returned; otherwise, false.

LIBGIFT_EXPORT bool gi_buffer_shrink (  GiBuffer *  buffer, size_t  shrunk )

Constrict the buffer by at most `shrunk' bytes. Less than `shrunk' bytes may be reduced. The buffer's length will be adjusted similar to using gi_buffer_truncate with the param `buffer->len - shrunk'. Returns: If the resize succeeds, true is returned; otherwise, false.

LIBGIFT_EXPORT void* gi_buffer_tail (  GiBuffer *  buffer  )

Access the last byte found in the data buffer. This is the last byte with user-supplied data written to it, and will return NULL if the buffer is allocated, but has no data written.

LIBGIFT_EXPORT bool gi_buffer_truncate (  GiBuffer *  buffer, size_t  len )

Truncate the size and length of the data buffer. If `len' is larger than the current length, the buffer will be resized and all bytes between the old length and new will be filled with zeroes. If `len' is shorter than the current length, the buffer's length will be rolled back and the data buffer may have been reduced in size. Returns: The return value is passed down from one of gi_buffer_shrink or gi_buffer_grow.

---