DynBuffer Struct Reference

Detailed Description

A dynamic buffer.

You either Subclass and implement the DynBuffer_OnAllocError method or set OnAllocError to NULL.

#include <DynBuffer.h>

Inheritance diagram for DynBuffer:

Public Member Functions
	DynBuffer ()
	Leave storage uninitialized; call DynBuffer_constructor before use. More...
	DynBuffer (int startSize, int expandSize, AllocatorIntf *alloc=0, DynBuffer_OnAllocError onAllocError=0)
	Create a dynamic buffer. More...
	~DynBuffer ()
	destructor. More...
void	release ()
	Free the current storage, reset the cursor and capacity, and invalidate all borrowed buffer pointers. More...
char *	getBuf ()
	Returns a pointer to the internal buffer. More...
U32	getBufSize ()
int	getECode ()
	Returns the error code if memory allocation failed. More...
int	expand (int sizeNeeded)
	force buffer to expand. More...
char *	getCurPtr ()
	Return a pointer to the internal cursor position in the internal dynamic buffer. More...
void	incrementCursor (int nBytes)
	Increments the internal cursor position. More...
Public Member Functions inherited from BufPrint
	BufPrint (void *userData=0, BufPrint_Flush flush=0)
	BufPrint constructor. More...
	BufPrint (char *buf, int size, void *userData=0, BufPrint_Flush flush=0)
	Initialize a writer using caller-owned storage. More...
void *	getUserData ()
int	vprintf (const char *fmt, va_list argList)
	Format arguments into this writer. More...
int	printf (const char *fmt,...)
	Format values using the compact BAS formatter. More...
int	baputc (int c)
	Append one byte (C function: BufPrint_putc). More...
int	write (const void *data, int len)
	Append bytes, flushing or expanding through the callback as needed. More...
int	write (const char *buf)
	Append a NUL-terminated string (C macro: BufPrint_write2). More...
void	setBuf (char *buf, int size)
	Replace borrowed storage and reset the cursor, discarding pending data. More...
char *	getBuf ()
	Returns a pointer to the internal buffer. More...
U32	getBufSize ()
void	erase ()
	resets the cursor, thus erasing the data in the buffer More...
int	flush ()
	Deliver pending bytes to the callback with sizeRequired zero. More...
int	b64Encode (const void *data, S32 slen)
	Append standard Base64 with = padding, without a NUL terminator. More...
int	b64urlEncode (const void *source, S32 slen, bool padding)
	Append Base64url using - and _, without a NUL terminator. More...
int	jsonString (const char *str, size_t len)
	Append a complete quoted JSON string. More...

Static Public Member Functions
static const char *	ecode2str (int eCode)
	Convert a recognized allocation error code to a static message. More...

Constructor & Destructor Documentation

DynBuffer() [1/2]

DynBuffer::DynBuffer

(

)

Leave storage uninitialized; call DynBuffer_constructor before use.

DynBuffer() [2/2]

DynBuffer::DynBuffer	(	int	startSize,
		int	expandSize,
		AllocatorIntf *	alloc = 0,
		DynBuffer_OnAllocError	onAllocError = 0
	)

Create a dynamic buffer.

Parameters

startSize	Nonnegative initial payload capacity in bytes. Zero defers allocation until data requires space. Allocations reserve an additional NUL byte. Keep capacities and cursor arithmetic within int.
expandSize	Nonnegative growth increment in bytes. Zero prevents an existing buffer from growing; a larger individual write may request a larger increment. Growth requires a realloc callback.
alloc	Borrowed allocator, or NULL for AllocatorIntf_getDefault(). It must outlive the buffer and its storage.
onAllocError	Optional callback invoked synchronously on allocation errors; NULL disables notification. Inspect getECode after construction.

~DynBuffer()

DynBuffer::~DynBuffer

(

)

destructor.

release memory by calling method DynBuffer::release.

Member Function Documentation

ecode2str()

const char * DynBuffer::ecode2str ( int  eCode )

static

Convert a recognized allocation error code to a static message.

Parameters

[in]

eCode

One of -2, -3, -4 or -5. Other values, including -1 and zero, trigger an assertion in debug builds.

Returns

Borrowed static message; do not free it.

expand()

int DynBuffer::expand

(

int

sizeNeeded

)

force buffer to expand.

Parameters

sizeNeeded

Nonnegative number of additional bytes required after the current cursor, not a new total capacity. The cursor is unchanged.

Returns

0 when sufficient space is available, -1 when growth fails or is disabled. A nonzero value is returned if there is not enough memory to expand the buffer i.e. if the AllocatorIntf provided in the constructor cannot re-allocate the buffer.

getBuf()

char * DynBuffer::getBuf

(

)

Returns a pointer to the internal buffer.

This pointer is invalid after the DynBuffer reallocates the internal buffer. Unlike the BufPrint::getBuf method, the buffer returned by this method is zero terminated.

Returns

Borrowed NUL-terminated storage, or NULL if no allocation exists. The pointer is also invalidated by release or destruction.

getBufSize()

U32 DynBuffer::getBufSize

(

)

Returns

Current payload byte count (cursor), excluding the NUL; this is not the allocation capacity.

getCurPtr()

char * DynBuffer::getCurPtr

(

)

Return a pointer to the internal cursor position in the internal dynamic buffer.

Returns

Borrowed pointer at the cursor. Requires an allocated buffer; call expand with a positive size and check success first. The pointer is invalidated by reallocation or release.

See also

expand incrementCursor

getECode()

int DynBuffer::getECode

(

)

Returns the error code if memory allocation failed.

This

Returns

Zero or a recorded negative error code as listed below. A fixed-size capacity failure may return -1 from a write without setting this code, so always check the operation result as well. This method is typically used when the DynBuffer_OnAllocError is set to NULL in the constructor.

 0: No error.
-1: No allocator.
-2: Malloc failed.
-3: Need to realloc buffer, but no realloc provided.
-4: Realloc failed.
-5: Buffer too large.

incrementCursor()

void DynBuffer::incrementCursor

(

int

nBytes

)

Increments the internal cursor position.

It is possible to manually format data in the internal buffer. This method advances the internal cursor by N bytes.

Parameters

[in]

nBytes

Nonnegative bytes already written at getCurPtr(). Reserve enough space with expand first; this macro does not check bounds.

example

char data[]={"My data"};
if(myBuf->expand(sizeof(data)-1) == 0) // -1: no need to store null term.
{
   memcpy(myBuf->getCurPtr(), data, sizeof(data)-1);
   myBuf->incrementCursor(sizeof(data)-1);
}

release()

void DynBuffer::release

(

)

Free the current storage, reset the cursor and capacity, and invalidate all borrowed buffer pointers.

Does not destroy the allocator or reset a previously recorded allocation error. Repeated release is harmless.