#include <UsefulBuf.h>

Detailed Description

UsefulOutBuf is a structure and functions (an object) for serializing data into a buffer to encode for a network protocol or write data to a file.

The main idea is that all the pointer manipulation is performed by UsefulOutBuf functions so the caller doesn't have to do any pointer manipulation. The pointer manipulation is centralized. This code has been reviewed and written carefully so it spares the caller of much of this work and results in safer code with less effort.

The UsefulOutBuf methods that add data to the output buffer always check the length and will never write off the end of the output buffer. If an attempt to add data that will not fit is made, an internal error flag will be set and further attempts to add data will not do anything.

There is no way to ever write off the end of that buffer when calling the UsefulOutBuf_AddXxx() and UsefulOutBuf_InsertXxx() functions.

The functions to add data do not report success of failure. The caller only needs to check for an error in the final call, either UsefulOutBuf_OutUBuf() or UsefulOutBuf_CopyOut() to get the result. This makes the calling code cleaner.

There is a utility function to get the error status anytime along the way for a special circumstance. There are functions to see how much room is left and see if some data will fit too, but their use is generally unnecessary.

The general call flow is:

Initialize by calling UsefulOutBuf_Init(). The output buffer given to it can be from the heap, stack or otherwise. UsefulOutBuf_MakeOnStack is a convenience macro that makes a buffer on the stack and initializes it.
Call methods like UsefulOutBuf_InsertString(), UsefulOutBuf_AppendUint32() and UsefulOutBuf_InsertUsefulBuf() to output data. The append calls add data to the end of the valid data. The insert calls take a position argument.
Call UsefulOutBuf_OutUBuf() or UsefulOutBuf_CopyOut() to see there were no errors and to get the serialized output bytes.

UsefulOutBuf can be used in a mode to calculate the size of what would be output without actually outputting anything. This is useful to calculate the size of a buffer that is to be allocated to hold the output. See SizeCalculateUsefulBuf.

Methods like UsefulOutBuf_InsertUint64() always output in network byte order (big endian).

The possible errors are:

The UsefulOutBuf was not initialized or was corrupted.
An attempt was made to add data that will not fit.
An attempt was made to insert data at a position beyond the end of the buffer.
An attempt was made to insert data at a position beyond the valid data in the buffer.

Some inexpensive simple sanity checks are performed before every data addition to guard against use of an uninitialized or corrupted UsefulOutBuf.

UsefulOutBuf has been used to create a CBOR encoder. The CBOR encoder has almost no pointer manipulation in it, is easier to read, and easier to review.

A UsefulOutBuf is small and can go on the stack:

32 bytes (27 bytes plus alignment padding) on a 64-bit CPU
16 bytes (15 bytes plus alignment padding) on a 32-bit CPU

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

/Users/lgl/Code/QCBOR/dev/inc/qcbor/UsefulBuf.h