construct/include/ircd/buffer/README.md

Memory Buffer Tools

This is a modernization of the (char *buf, size_t buf_sz) pattern used when working with segments of RAMs. While in C99 it is possible (and recommended) for a project to create a struct buffer { char *ptr; size_t size; }; and then manually perform object semantics buffer_copy(dst, src); buffer_move(dst, src)``buffer_free(buf); etc, we create those devices using C++ language features here instead.

This suite is born out of (though not directly based on) the boost::asio buffer objects boost::asio::const_buffer and boost::asio::mutable_buffer and the two principal objects used ubiquitously throughout IRCd share the same names and general properties. We also offer conversions between them for developers working with any asio interfaces directly.

To summarize some basics about these tools:

• Most of these interfaces are "thin" and don't own their underlying data, nor will they copy their underlying data even if their instance itself is copied.

• We work with signed char * (and const char *) types. We do not work with void pointers because size integers always represent a count of single bytes and there is no reason to lose or confuse that information. If unsigned char * types are required by some library function an explicit cast to uint8_t * may be required especially to avoid warnings. Note that we compile this project with -fsigned-char and don't support platforms that have incompatible conversions.