DasBuf Struct Reference

Buffer class to handle accumulating byte streams. More...

#include <das2/buffer.h>

Public Member Functions
DAS_API DasBuf *	new_DasBuf (size_t uLen)
	Create a new Read-Write buffer on the heap Allocates a new char buffer of the indicated size, call del_DasBuffer() when finished. More...
DAS_API DasErrCode	DasBuf_initReadWrite (DasBuf *pThis, char *sBuf, size_t uLen)
	Initialize a read-write buffer that points to an external byte array. More...
DAS_API void	DasBuf_reinit (DasBuf *pThis)
	Re-initialize a buffer including read and write points This version can be a little quicker than init_DasBuffer() because it only zero's out the bytes that were written, not the entire buffer.
DAS_API void	del_DasBuf (DasBuf *pThis)
	Free a buffer object along with it's backing store. More...
DAS_API DasErrCode	DasBuf_puts (DasBuf *pThis, const char *sStr)
	Add a string to the buffer. More...
DAS_API DasErrCode	DasBuf_printf (DasBuf *pThis, const char *sFmt,...)
	Write formatted strings to the buffer. More...
DAS_API DasErrCode	DasBuf_write (DasBuf *pThis, const void *pData, size_t uLen)
	Add generic data to the buffer. More...
DAS_API size_t	DasBuf_written (const DasBuf *pThis)
	Get the size of the data in the buffer. More...
DAS_API size_t	DasBuf_unread (const DasBuf *pThis)
	Get the number of bytes remaining from the read begin point to the read end point. More...
DAS_API size_t	DasBuf_strip (DasBuf *pThis)
	Adjust read points so that the data starts and ends on non-space values. More...
DAS_API size_t	DasBuf_read (DasBuf *pThis, char *pOut, size_t uOut)
	Read bytes from a buffer Copies bytes out of a buffer and increments the read point. More...
DAS_API const ubyte *	DasBuf_direct (const DasBuf *pThis, size_t *pLength)
	Get a constant point to un-read bytes in the buffer and the number un-read. More...
DAS_API size_t	DasBuf_peek (const DasBuf *pThis, char *pOut, size_t uOut)
	Peak at bytes from a buffer Copies bytes out of a buffer but does not increment the read point. More...
DAS_API int	DasBuf_last (const DasBuf *pThis)
	Peak the last byte in the buffer. More...

Detailed Description

Buffer class to handle accumulating byte streams.

DasBuf objects maintain a data buffer with a current write point, a current read point and an end read point. As data are written to the buffer the write point is incremented as well as the end-of-read point. This structure is handy when multiple functions need to contribute encoded data to a single memory buffer, or when multiple functions need to read from a buffer without memory re-allocations or placing null values to stop parsing.

Member Function Documentation

new_DasBuf()

DAS_API DasBuf * new_DasBuf

(

size_t

uLen

)

Create a new Read-Write buffer on the heap Allocates a new char buffer of the indicated size, call del_DasBuffer() when finished.

Parameters

uLen	The length of the raw buffer to allocate

Returns

a new DasBuf allocated on the heap.

DasBuf_initReadWrite()

DAS_API DasErrCode DasBuf_initReadWrite	(	DasBuf *	pThis,
		char *	sBuf,
		size_t	uLen
	)

Initialize a read-write buffer that points to an external byte array.

The write point is reset to the beginning and function zero's all data. The read point is also set to the beginning.

Parameters

pThis	the buffer initialize
sBuf	an pre-allocated character buffer to receive new data
uLen	the length of the pre-allocated buffer

del_DasBuf()

DAS_API void del_DasBuf

(

DasBuf *

pThis

)

Free a buffer object along with it's backing store.

Don't use this if the DasBuf_initReadOnly or DasBuf_initReadWrite were given pointers to buffers allocated on the stack. If so, your program will crash.

Parameters

pThis

The buffer to free. It's good practice to set this pointer to NULL after this function is called

DasBuf_puts()

DAS_API DasErrCode DasBuf_puts	(	DasBuf *	pThis,
		const char *	sStr
	)

Add a string to the buffer.

Parameters

pThis	the buffer to receive the bytes
sStr	the null-terminated string to write

Returns

0 if the operation succeeded, a positive error code otherwise.

DasBuf_printf()

DAS_API DasErrCode DasBuf_printf	(	DasBuf *	pThis,
		const char *	sFmt,
			...
	)

Write formatted strings to the buffer.

Parameters

pThis	the buffer to receive the bytes
sFmt	an sprintf style format string

Returns

0 if the operation succeeded, a positive error code otherwise.

DasBuf_write()

DAS_API DasErrCode DasBuf_write	(	DasBuf *	pThis,
		const void *	pData,
		size_t	uLen
	)

Add generic data to the buffer.

Parameters

pThis	the buffer to receive the bytes
pData	a pointer to the bytes to write
uLen	the number of bytes to write

Returns

0 if the operation succeeded, a positive error code otherwise.

DasBuf_written()

DAS_API size_t DasBuf_written

(

const DasBuf *

pThis

)

Get the size of the data in the buffer.

Returns

the number of bytes written to the buffer

DasBuf_unread()

DAS_API size_t DasBuf_unread

(

const DasBuf *

pThis

)

Get the number of bytes remaining from the read begin point to the read end point.

Normally this returns the difference between the read point and the write point but some operations such as DasBuf_strip() reduce the read end point below the write point.

Returns

Read length remaining.

DasBuf_strip()

DAS_API size_t DasBuf_strip

(

DasBuf *

pThis

)

Adjust read points so that the data starts and ends on non-space values.

This is handy if the buffer contains string data.

Warning

If any new bytes are added after the buffer has been stripped then the right read point will be reset to the end of valid data.

Returns

The number of bytes left to read after moving the read boundaries. The return value is the same as what you would get by calling DasBuf_remaining() immediately after this function.

DasBuf_read()

DAS_API size_t DasBuf_read	(	DasBuf *	pThis,
		char *	pOut,
		size_t	uOut
	)

Read bytes from a buffer Copies bytes out of a buffer and increments the read point.

As soon as the read point hits the end of valid data no more bytes are copied.

Returns

The number of bytes copied out of the buffer.

DasBuf_direct()

DAS_API const ubyte * DasBuf_direct	(	const DasBuf *	pThis,
		size_t *	pLength
	)

Get a constant point to un-read bytes in the buffer and the number un-read.

Note

Unlike most read function calls this does not advance the read point You must do it manually using DasBuf_readOffset() and DasBuf_setReadOffset()

Parameters

pThis	the buffer
pLength	A pointer to a size_t to receive the number of unread bytes

Returns

A contant unsigned byte pointer at the read location or NULL if there are no more bytes to read

DasBuf_peek()

DAS_API size_t DasBuf_peek	(	const DasBuf *	pThis,
		char *	pOut,
		size_t	uOut
	)

Peak at bytes from a buffer Copies bytes out of a buffer but does not increment the read point.

Returns

The number of bytes copied out of the buffer.

DasBuf_last()

DAS_API int DasBuf_last

(

const DasBuf *

pThis

)

Peak the last byte in the buffer.

Returns

the last byte in the buffer as an int, or -1 if there are no bytes in the buffer.

---

The documentation for this struct was generated from the following file:

• das2/buffer.h