UsefulOutBuf is a structure and functions (an object) that are good for serializing data into a buffer such as is often done with network protocols or data written to files.

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

The functions to 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.

Basically, if you initialized with the correct buffer, there is no way to ever write off the end of that buffer when calling the Add and Insert functions here.

The functions to add data do not return an error. The working model is that the caller just makes all the calls to add data without any error checking on each one. The error is instead checked after all the data is added when the result is to be used. This makes the caller's code cleaner.

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

The general call flow is like this:

• Initialize the UsefulOutBuf with the buffer that is to have the data added. The caller allocates the buffer. It can be heap or stack or shared memory (or other).
• Make calls to add data to the output buffer. Insert and append are both supported. The append and insert calls will never write off the end of the buffer.
• When all data is added, check the error status to make sure everything fit.
• Get the resulting serialized data either as a UsefulBuf (a pointer and length) or have it copied to another buffer.

UsefulOutBuf can be initialized with just a buffer length by passing NULL as the pointer to the output buffer. This is useful if you want to go through the whole serialization process to either see if it will fit into a given buffer or compute the size of the buffer needed. Pass a very large buffer size when calling Init, if you want just to compute the size.

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

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

A UsefulOutBuf is 27 bytes or 15 bytes on 64- or 32-bit machines so it can go on the stack or be a C99 function parameter.

Definition at line 642 of file UsefulBuf.h.