UsefulBuf.h

Go to the documentation of this file.

/* =========================================================================
 * Copyright (c) 2016-2018, The Linux Foundation.
 * Copyright (c) 2018-2025, Laurence Lundblade.
 * Copyright (c) 2021, Arm Limited. All rights reserved.
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are
 * met:
 *     * Redistributions of source code must retain the above copyright
 *       notice, this list of conditions and the following disclaimer.
 *     * Redistributions in binary form must reproduce the above
 *       copyright notice, this list of conditions and the following
 *       disclaimer in the documentation and/or other materials provided
 *       with the distribution.
 *     * Neither the name of The Linux Foundation nor the names of its
 *       contributors, nor the name "Laurence Lundblade" may be used to
 *       endorse or promote products derived from this software without
 *       specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED "AS IS" AND ANY EXPRESS OR IMPLIED
 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT
 * ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS
 * BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
 * BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
 * OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN
 * IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 * ========================================================================= */
 
/*============================================================================
 FILE:  UsefulBuf.h
 
 DESCRIPTION:  General purpose input and output buffers
 
 EDIT HISTORY FOR FILE:
 
 This section contains comments describing changes made to the module.
 Notice that changes are listed in reverse chronological order.
 
 when         who             what, where, why
 --------     ----            --------------------------------------------------
 11/10/2025   llundblade      Explicitly size integer literals (MSVC fix).
 08/14/2024   llundblade      Add UsefulOutBuf_RetrieveOutputStorage().
 08/13/2024   llundblade      Add UsefulInputBuf_RetrieveUndecodedInput().
 08/08/2024   llundblade      Add UsefulOutBuf_SubString().
 10/05/2024   llundblade      Add Xxx_OffsetToPointer.
 19/12/2022   llundblade      Document that adding empty data is allowed.
 4/11/2022    llundblade      Add GetOutPlace and Advance to UsefulOutBuf.
 9/21/2021    llundbla        Clarify UsefulOutBuf size calculation mode
 8/8/2021     dthaler/llundbla Work with C++ without compiler extensions
 5/11/2021    llundblade      Improve comments and comment formatting.
 3/6/2021     mcr/llundblade  Fix warnings related to --Wcast-qual
 2/17/2021    llundblade      Add method to go from a pointer to an offset.
 1/25/2020    llundblade      Add some casts so static anlyzers don't complain.
 5/21/2019    llundblade      #define configs for efficient endianness handling.
 5/16/2019    llundblade      Add UsefulOutBuf_IsBufferNULL().
 3/23/2019    llundblade      Big documentation & style update. No interface
                              change.
 3/6/2019     llundblade      Add UsefulBuf_IsValue()
 12/17/2018   llundblade      Remove const from UsefulBuf and UsefulBufC .len
 12/13/2018   llundblade      Documentation improvements
 09/18/2018   llundblade      Cleaner distinction between UsefulBuf and
                              UsefulBufC.
 02/02/18     llundbla        Full support for integers in and out; fix pointer
                              alignment bug. Incompatible change: integers
                              in/out are now in network byte order.
 08/12/17     llundbla        Added UsefulOutBuf_AtStart and UsefulBuf_Find
 06/27/17     llundbla        Fix UsefulBuf_Compare() bug. Only affected
                              comparison for < or > for unequal length buffers.
                              Added UsefulBuf_Set() function.
 05/30/17     llundbla        Functions for NULL UsefulBufs and const / unconst
 11/13/16     llundbla        Initial Version.
 
 =============================================================================*/
 
#ifndef _UsefulBuf_h
#define _UsefulBuf_h
 
 
/*
 * Endianness Configuration
 *
 * This code is written so it will work correctly on big- and
 * little-endian CPUs without configuration or any auto-detection of
 * endianness. All code here will run correctly regardless of the
 * endianness of the CPU it is running on.
 *
 * There are four C preprocessor macros that can be set with #define
 * to explicitly configure endianness handling. Setting them can
 * reduce code size a little and improve efficiency a little.
 *
 * Note that most of QCBOR is unaffected by this configuration.  Its
 * endianness handling is integrated with the code that handles
 * alignment and preferred serialization. This configuration does
 * affect QCBOR's (planned) implementation of integer arrays (tagged
 * arrays) and use of the functions here to serialize or deserialize
 * integers and floating-point values.
 *
 * Following is the recipe for configuring the endianness-related
 * #defines.
 *
 * The first option is to not define anything. This will work fine
 * with all CPUs, OS's and compilers. The code for encoding integers
 * may be a little larger and slower.
 *
 * If your CPU is big-endian then define
 * USEFULBUF_CONFIG_BIG_ENDIAN. This will give the most efficient code
 * for big-endian CPUs. It will be small and efficient because there
 * will be no byte swapping.
 *
 * Try defining USEFULBUF_CONFIG_HTON. This will work on most CPUs,
 * OS's and compilers, but not all. On big-endian CPUs this should
 * give the most efficient code, the same as
 * USEFULBUF_CONFIG_BIG_ENDIAN does. On little-endian CPUs it should
 * call the system-defined byte swapping method which is presumably
 * implemented efficiently. In some cases, this will be a dedicated
 * byte swap instruction like Intel's bswap.
 *
 * If USEFULBUF_CONFIG_HTON works and you know your CPU is
 * little-endian, it is also good to define
 * USEFULBUF_CONFIG_LITTLE_ENDIAN.
 *
 * if USEFULBUF_CONFIG_HTON doesn't work and you know your system is
 * little-endian, try defining both USEFULBUF_CONFIG_LITTLE_ENDIAN and
 * USEFULBUF_CONFIG_BSWAP. This should call the most efficient
 * system-defined byte swap method. However, note
 * https://hardwarebug.org/2010/01/14/beware-the-builtins/.  Perhaps
 * this is fixed now. Often hton() and ntoh() will call the built-in
 * __builtin_bswapXX()() function, so this size issue could affect
 * USEFULBUF_CONFIG_HTON.
 *
 * Last, run the tests. They must all pass.
 *
 * These #define config options affect the inline implementation of
 * UsefulOutBuf_InsertUint64() and UsefulInputBuf_GetUint64().  They
 * also affect the 16-, 32-bit, float and double versions of these
 * functions. Since they are inline, the size effect is not in the
 * UsefulBuf object code, but in the calling code.
 *
 * Summary:
 *   USEFULBUF_CONFIG_BIG_ENDIAN -- Force configuration to big-endian.
 *   USEFULBUF_CONFIG_LITTLE_ENDIAN -- Force to little-endian.
 *   USEFULBUF_CONFIG_HTON -- Use hton(), htonl(), ntohl()... to
 *     handle big and little-endian with system option.
 *   USEFULBUF_CONFIG_BSWAP -- With USEFULBUF_CONFIG_LITTLE_ENDIAN,
 *     use __builtin_bswapXX().
 *
 * It is possible to run this code in environments where using floating point is
 * not allowed. Defining USEFULBUF_DISABLE_ALL_FLOAT will disable all the code
 * that is related to handling floating point types, along with related
 * interfaces. This makes it possible to compile the code with the compile
 * option -mgeneral-regs-only.
 */
 
#if defined(USEFULBUF_CONFIG_BIG_ENDIAN) && defined(USEFULBUF_CONFIG_LITTLE_ENDIAN)
#error "Cannot define both USEFULBUF_CONFIG_BIG_ENDIAN and USEFULBUF_CONFIG_LITTLE_ENDIAN"
#endif
 
 
#include <stdint.h> /* for uint8_t, uint16_t.... */
#include <string.h> /* for strlen, memcpy, memmove, memset */
#include <stddef.h> /* for size_t */
 
 
#ifdef USEFULBUF_CONFIG_HTON
#include <arpa/inet.h> /* for htons, htonl, htonll, ntohs... */
#endif
 
#ifdef __cplusplus
extern "C" {
#if 0
} /* Keep editor indention formatting happy */
#endif
#endif
 
typedef struct q_useful_buf_c {
    const void *ptr;
    size_t      len;
} UsefulBufC;
 
 
typedef struct q_useful_buf {
   void  *ptr;
   size_t len;
} UsefulBuf;
 
 
/*
 * NULLUsefulBufC and few other macros have to be
 * definied differently in C than C++ because there
 * is no common construct for a literal structure.
 *
 * In C compound literals are used.
 *
 * In C++ list initalization is used. This only works
 * in C++11 and later.
 *
 * Note that some popular C++ compilers can handle compound
 * literals with on-by-default extensions, however
 * this code aims for full correctness with strict
 * compilers so they are not used.
 */
#ifdef __cplusplus
#define NULLUsefulBufC {NULL, 0}
#else
#define NULLUsefulBufC ((UsefulBufC) {NULL, 0})
#endif
 
#ifdef __cplusplus
#define NULLUsefulBuf  {NULL, 0}
#else
#define NULLUsefulBuf  ((UsefulBuf) {NULL, 0})
#endif
 
 
static inline int UsefulBuf_IsNULL(UsefulBuf UB);
 
 
static inline int UsefulBuf_IsNULLC(UsefulBufC UB);
 
 
static inline int UsefulBuf_IsEmpty(UsefulBuf UB);
 
 
static inline int UsefulBuf_IsEmptyC(UsefulBufC UB);
 
 
static inline int UsefulBuf_IsNULLOrEmpty(UsefulBuf UB);
 
 
static inline int UsefulBuf_IsNULLOrEmptyC(UsefulBufC UB);
 
 
static inline UsefulBufC UsefulBuf_Const(const UsefulBuf UB);
 
 
static inline UsefulBuf UsefulBuf_Unconst(const UsefulBufC UBC);
 
 
#ifdef __cplusplus
#define UsefulBuf_FROM_SZ_LITERAL(szString)  {(szString), sizeof(szString)-1}
#else
#define UsefulBuf_FROM_SZ_LITERAL(szString) \
    ((UsefulBufC) {(szString), sizeof(szString)-1})
#endif
 
 
#ifdef __cplusplus
#define UsefulBuf_FROM_BYTE_ARRAY_LITERAL(pBytes)  {(pBytes), sizeof(pBytes)}
#else
#define UsefulBuf_FROM_BYTE_ARRAY_LITERAL(pBytes) \
   ((UsefulBufC) {(pBytes), sizeof(pBytes)})
#endif
 
#define  UsefulBuf_MAKE_STACK_UB(name, size) \
    uint8_t    __pBuf##name[(size)];\
    UsefulBuf  name = {__pBuf##name , sizeof( __pBuf##name )}
 
 
#ifdef __cplusplus
#define UsefulBuf_FROM_BYTE_ARRAY(pBytes)  {(pBytes), sizeof(pBytes)}
#else
#define UsefulBuf_FROM_BYTE_ARRAY(pBytes) \
   ((UsefulBuf) {(pBytes), sizeof(pBytes)})
#endif
 
 
static inline UsefulBufC UsefulBuf_FromSZ(const char *szString);
 
 
UsefulBufC UsefulBuf_CopyOffset(UsefulBuf Dest, size_t uOffset, const UsefulBufC Src);
 
 
static inline UsefulBufC UsefulBuf_Copy(UsefulBuf Dest, const UsefulBufC Src);
 
 
static inline UsefulBufC UsefulBuf_Set(UsefulBuf pDest, uint8_t value);
 
 
static inline UsefulBufC UsefulBuf_CopyPtr(UsefulBuf Dest,
                                           const void *ptr,
                                           size_t uLen);
 
 
static inline UsefulBufC UsefulBuf_Head(UsefulBufC UB, size_t uAmount);
 
 
static inline UsefulBufC UsefulBuf_Tail(UsefulBufC UB, size_t uAmount);
 
 
int UsefulBuf_Compare(const UsefulBufC UB1, const UsefulBufC UB2);
 
 
size_t UsefulBuf_IsValue(const UsefulBufC UB, uint8_t uValue);
 
 
size_t UsefulBuf_FindBytes(UsefulBufC BytesToSearch, UsefulBufC BytesToFind);
 
 
static inline size_t UsefulBuf_PointerToOffset(UsefulBufC UB, const void *p);
 
 
static inline const void *UsefulBuf_OffsetToPointer(UsefulBufC UB, size_t uOffset);
 
 
#ifndef USEFULBUF_DISABLE_DEPRECATED
#define SZLiteralToUsefulBufC(szString)  UsefulBuf_FROM_SZ_LITERAL(szString)
 
#define  MakeUsefulBufOnStack(name, size) \
    uint8_t    __pBuf##name[(size)];\
    UsefulBuf  name = {__pBuf##name , sizeof( __pBuf##name )}
 
#define ByteArrayLiteralToUsefulBufC(pBytes) \
   UsefulBuf_FROM_BYTE_ARRAY_LITERAL(pBytes)
 
static inline UsefulBuf UsefulBufC_Unconst(const UsefulBufC UBC)
{
   UsefulBuf UB;
 
   /* See UsefulBuf_Unconst() implementation for comment */
   UB.ptr = (void *)(uintptr_t)UBC.ptr;
 
   UB.len = UBC.len;
 
   return UB;
}
#endif /* USEFULBUF_DISABLE_DEPRECATED */
 
 
 
 
#ifndef USEFULBUF_DISABLE_ALL_FLOAT
static inline uint32_t UsefulBufUtil_CopyFloatToUint32(float f);
 
 
static inline uint64_t UsefulBufUtil_CopyDoubleToUint64(double d);
 
 
static inline float UsefulBufUtil_CopyUint32ToFloat(uint32_t u32);
 
 
static inline double UsefulBufUtil_CopyUint64ToDouble(uint64_t u64);
#endif /* USEFULBUF_DISABLE_ALL_FLOAT */
 
 
 
 
typedef struct useful_out_buf {
   /* PRIVATE DATA STRUCTURE */
   UsefulBuf  UB;       /* Memory that is being output to */
   size_t     data_len; /* length of the valid data, the insertion point */
   uint16_t   magic;    /* Used to detect corruption and lack
                         * of initialization */
   uint8_t    err;
} UsefulOutBuf;
 
 
#ifdef __cplusplus
#define SizeCalculateUsefulBuf {NULL, SIZE_MAX}
#else
#define SizeCalculateUsefulBuf ((UsefulBuf) {NULL, SIZE_MAX})
#endif
 
 
void UsefulOutBuf_Init(UsefulOutBuf *pUOutBuf, UsefulBuf Storage);
 
 
#define  UsefulOutBuf_MakeOnStack(name, size) \
   uint8_t       __pBuf##name[(size)];\
   UsefulOutBuf  name;\
   UsefulOutBuf_Init(&(name), (UsefulBuf){__pBuf##name, (size)});
 
 
static inline void UsefulOutBuf_Reset(UsefulOutBuf *pUOutBuf);
 
 
static inline size_t UsefulOutBuf_GetEndPosition(UsefulOutBuf *pUOutBuf);
 
 
static inline int UsefulOutBuf_AtStart(UsefulOutBuf *pUOutBuf);
 
 
void UsefulOutBuf_InsertUsefulBuf(UsefulOutBuf *pUOutBuf,
                                  UsefulBufC NewData,
                                  size_t uPos);
 
 
static inline void UsefulOutBuf_InsertData(UsefulOutBuf *pUOutBuf,
                                           const void *pBytes,
                                           size_t uLen,
                                           size_t uPos);
 
 
static inline void UsefulOutBuf_InsertString(UsefulOutBuf *pUOutBuf,
                                             const char *szString,
                                             size_t uPos);
 
 
static inline void UsefulOutBuf_InsertByte(UsefulOutBuf *pUOutBuf,
                                           uint8_t byte,
                                           size_t uPos);
 
 
static inline void UsefulOutBuf_InsertUint16(UsefulOutBuf *pUOutBuf,
                                             uint16_t uInteger16,
                                             size_t uPos);
 
 
static inline void UsefulOutBuf_InsertUint32(UsefulOutBuf *pUOutBuf,
                                             uint32_t uInteger32,
                                             size_t uPos);
 
 
static inline void UsefulOutBuf_InsertUint64(UsefulOutBuf *pUOutBuf,
                                             uint64_t uInteger64,
                                             size_t uPos);
 
 
#ifndef USEFULBUF_DISABLE_ALL_FLOAT
static inline void UsefulOutBuf_InsertFloat(UsefulOutBuf *pUOutBuf,
                                            float f,
                                            size_t uPos);
 
 
static inline void UsefulOutBuf_InsertDouble(UsefulOutBuf *pUOutBuf,
                                             double d,
                                             size_t uPos);
#endif /* USEFULBUF_DISABLE_ALL_FLOAT */
 
 
static inline void UsefulOutBuf_AppendUsefulBuf(UsefulOutBuf *pUOutBuf,
                                                UsefulBufC NewData);
 
 
static inline void UsefulOutBuf_AppendData(UsefulOutBuf *pUOutBuf,
                                           const void *pBytes,
                                           size_t uLen);
 
 
static inline void UsefulOutBuf_AppendString(UsefulOutBuf *pUOutBuf,
                                             const char *szString);
 
 
static inline void UsefulOutBuf_AppendByte(UsefulOutBuf *pUOutBuf,
                                           uint8_t byte);
 
 
static inline void UsefulOutBuf_AppendUint16(UsefulOutBuf *pUOutBuf,
                                             uint16_t uInteger16);
 
 
static inline void UsefulOutBuf_AppendUint32(UsefulOutBuf *pUOutBuf,
                                             uint32_t uInteger32);
 
 
static inline void UsefulOutBuf_AppendUint64(UsefulOutBuf *pUOutBuf,
                                             uint64_t uInteger64);
 
 
#ifndef USEFULBUF_DISABLE_ALL_FLOAT
static inline void UsefulOutBuf_AppendFloat(UsefulOutBuf *pUOutBuf,
                                            float f);
 
 
static inline void UsefulOutBuf_AppendDouble(UsefulOutBuf *pUOutBuf,
                                             double d);
#endif /* USEFULBUF_DISABLE_ALL_FLOAT */
 
 
static inline int UsefulOutBuf_GetError(UsefulOutBuf *pUOutBuf);
 
 
static inline size_t UsefulOutBuf_RoomLeft(UsefulOutBuf *pUOutBuf);
 
 
static inline int UsefulOutBuf_WillItFit(UsefulOutBuf *pUOutBuf, size_t uLen);
 
 
static inline int UsefulOutBuf_IsBufferNULL(UsefulOutBuf *pUOutBuf);
 
 
static inline UsefulBuf
UsefulOutBuf_GetOutPlace(UsefulOutBuf *pUOutBuf);
 
 
void
UsefulOutBuf_Advance(UsefulOutBuf *pUOutBuf, size_t uAmount);
 
 
UsefulBufC UsefulOutBuf_OutUBuf(UsefulOutBuf *pUOutBuf);
 
 
UsefulBufC UsefulOutBuf_CopyOut(UsefulOutBuf *pUOutBuf, UsefulBuf Dest);
 
 
UsefulBufC UsefulOutBuf_SubString(UsefulOutBuf *pUOutBuf,
                                  const size_t  uStart,
                                  const size_t  uLen);
 
 
static UsefulBuf UsefulOutBuf_RetrieveOutputStorage(UsefulOutBuf *pUOutBuf);
 
 
 
typedef struct useful_input_buf {
   /* PRIVATE DATA STRUCTURE */
   UsefulBufC UB;     /* Data being parsed */
   size_t     cursor; /* Current offset in data being parse */
   uint16_t   magic;  /* Check for corrupted or uninitialized UsefulInputBuf */
   uint8_t    err;    /* Set request goes off end or magic number is bad */
} UsefulInputBuf;
 
#define UIB_MAGIC (0xB00F)
 
 
static inline void UsefulInputBuf_Init(UsefulInputBuf *pUInBuf, UsefulBufC UB);
 
 
static size_t UsefulInputBuf_Tell(UsefulInputBuf *pUInBuf);
 
 
static void UsefulInputBuf_Seek(UsefulInputBuf *pUInBuf, size_t uPos);
 
 
static size_t UsefulInputBuf_BytesUnconsumed(UsefulInputBuf *pUInBuf);
 
 
static int UsefulInputBuf_BytesAvailable(UsefulInputBuf *pUInBuf, size_t uLen);
 
 
static size_t UsefulInputBuf_PointerToOffset(UsefulInputBuf *pUInBuf, const void *p);
 
 
static const void *UsefulInputBuf_OffsetToPointer(UsefulInputBuf *pUInBuf, size_t uOffset);
 
 
const void * UsefulInputBuf_GetBytes(UsefulInputBuf *pUInBuf, size_t uNum);
 
 
static inline UsefulBufC UsefulInputBuf_GetUsefulBuf(UsefulInputBuf *pUInBuf, size_t uNum);
 
 
static inline uint8_t UsefulInputBuf_GetByte(UsefulInputBuf *pUInBuf);
 
 
static inline uint16_t UsefulInputBuf_GetUint16(UsefulInputBuf *pUInBuf);
 
 
static uint32_t UsefulInputBuf_GetUint32(UsefulInputBuf *pUInBuf);
 
 
static uint64_t UsefulInputBuf_GetUint64(UsefulInputBuf *pUInBuf);
 
 
#ifndef USEFULBUF_DISABLE_ALL_FLOAT
static float UsefulInputBuf_GetFloat(UsefulInputBuf *pUInBuf);
 
 
static double UsefulInputBuf_GetDouble(UsefulInputBuf *pUInBuf);
#endif /* USEFULBUF_DISABLE_ALL_FLOAT */
 
 
static int UsefulInputBuf_GetError(UsefulInputBuf *pUInBuf);
 
 
static inline size_t UsefulInputBuf_GetBufferLength(UsefulInputBuf *pUInBuf);
 
 
static void UsefulInputBuf_SetBufferLength(UsefulInputBuf *pUInBuf, size_t uNewLen);
 
 
static UsefulBufC UsefulInputBuf_RetrieveUndecodedInput(UsefulInputBuf *pUInBuf);
 
 
/*----------------------------------------------------------
 Inline implementations.
 */
static inline int UsefulBuf_IsNULL(UsefulBuf UB)
{
   return !UB.ptr;
}
 
 
static inline int UsefulBuf_IsNULLC(UsefulBufC UB)
{
   return !UB.ptr;
}
 
 
static inline int UsefulBuf_IsEmpty(UsefulBuf UB)
{
   return !UB.len;
}
 
 
static inline int UsefulBuf_IsEmptyC(UsefulBufC UB)
{
   return !UB.len;
}
 
 
static inline int UsefulBuf_IsNULLOrEmpty(UsefulBuf UB)
{
   return UsefulBuf_IsEmpty(UB) || UsefulBuf_IsNULL(UB);
}
 
 
static inline int UsefulBuf_IsNULLOrEmptyC(UsefulBufC UB)
{
   return UsefulBuf_IsEmptyC(UB) || UsefulBuf_IsNULLC(UB);
}
 
 
static inline UsefulBufC UsefulBuf_Const(const UsefulBuf UB)
{
   UsefulBufC UBC;
   UBC.ptr = UB.ptr;
   UBC.len = UB.len;
 
   return UBC;
}
 
static inline UsefulBuf UsefulBuf_Unconst(const UsefulBufC UBC)
{
   UsefulBuf UB;
 
   /* -Wcast-qual is a good warning flag to use in general. This is
    * the one place in UsefulBuf where it needs to be quieted.
    */
   UB.ptr = (void *)(uintptr_t)UBC.ptr;
 
   UB.len = UBC.len;
 
   return UB;
}
 
 
static inline UsefulBufC UsefulBuf_FromSZ(const char *szString)
{
   UsefulBufC UBC;
   UBC.ptr = szString;
   UBC.len = strlen(szString);
   return UBC;
}
 
 
static inline UsefulBufC UsefulBuf_Copy(UsefulBuf Dest, const UsefulBufC Src)
{
   return UsefulBuf_CopyOffset(Dest, 0, Src);
}
 
 
static inline UsefulBufC UsefulBuf_Set(UsefulBuf Dest, uint8_t value)
{
   memset(Dest.ptr, value, Dest.len);
 
   UsefulBufC UBC;
   UBC.ptr = Dest.ptr;
   UBC.len = Dest.len;
 
   return UBC;
}
 
 
static inline UsefulBufC UsefulBuf_CopyPtr(UsefulBuf Dest, const void *ptr, size_t len)
{
   UsefulBufC UBC;
   UBC.ptr = ptr;
   UBC.len = len;
   return UsefulBuf_Copy(Dest, UBC);
}
 
 
static inline UsefulBufC UsefulBuf_Head(UsefulBufC UB, size_t uAmount)
{
   if(uAmount > UB.len) {
      return NULLUsefulBufC;
   }
   UsefulBufC UBC;
 
   UBC.ptr = UB.ptr;
   UBC.len = uAmount;
 
   return UBC;
}
 
 
static inline UsefulBufC UsefulBuf_Tail(UsefulBufC UB, size_t uAmount)
{
   UsefulBufC ReturnValue;
 
   if(uAmount > UB.len) {
      ReturnValue = NULLUsefulBufC;
   } else if(UB.ptr == NULL) {
      ReturnValue.ptr = NULL;
      ReturnValue.len = UB.len - uAmount;
   } else {
      ReturnValue.ptr = (const uint8_t *)UB.ptr + uAmount;
      ReturnValue.len = UB.len - uAmount;
   }
 
   return ReturnValue;
}
 
 
static inline size_t UsefulBuf_PointerToOffset(UsefulBufC UB, const void *p)
{
   if(UB.ptr == NULL) {
      return SIZE_MAX;
   }
 
   if(p < UB.ptr) {
      /* given pointer is before start of buffer */
      return SIZE_MAX;
   }
 
   /* Cast to size_t (from ptrdiff_t) is OK because of check above */
   const size_t uOffset = (size_t)((const uint8_t *)p - (const uint8_t *)UB.ptr);
 
    if(uOffset >= UB.len) {
      /* given pointer is off the end of the buffer */
      return SIZE_MAX;
   }
 
   return uOffset;
}
 
 
static inline const void *UsefulBuf_OffsetToPointer(UsefulBufC UB, size_t uOffset)
{
   if(UsefulBuf_IsNULLC(UB) || uOffset >= UB.len) {
      return NULL;
   }
 
   return (const uint8_t *)UB.ptr + uOffset;
}
 
 
 
 
#ifndef USEFULBUF_DISABLE_ALL_FLOAT
static inline uint32_t UsefulBufUtil_CopyFloatToUint32(float f)
{
   uint32_t u32;
   memcpy(&u32, &f, sizeof(uint32_t));
   return u32;
}
 
static inline uint64_t UsefulBufUtil_CopyDoubleToUint64(double d)
{
   uint64_t u64;
   memcpy(&u64, &d, sizeof(uint64_t));
   return u64;
}
 
static inline double UsefulBufUtil_CopyUint64ToDouble(uint64_t u64)
{
   double d;
   memcpy(&d, &u64, sizeof(uint64_t));
   return d;
}
 
static inline float UsefulBufUtil_CopyUint32ToFloat(uint32_t u32)
{
   float f;
   memcpy(&f, &u32, sizeof(uint32_t));
   return f;
}
#endif /* USEFULBUF_DISABLE_ALL_FLOAT */
 
 
 
 
static inline void UsefulOutBuf_Reset(UsefulOutBuf *pMe)
{
   pMe->data_len = 0;
   pMe->err      = 0;
}
 
 
static inline size_t UsefulOutBuf_GetEndPosition(UsefulOutBuf *pMe)
{
   return pMe->data_len;
}
 
 
static inline int UsefulOutBuf_AtStart(UsefulOutBuf *pMe)
{
   return 0 == pMe->data_len;
}
 
 
static inline void UsefulOutBuf_InsertData(UsefulOutBuf *pMe,
                                           const void *pBytes,
                                           size_t uLen,
                                           size_t uPos)
{
   UsefulBufC Data = {pBytes, uLen};
   UsefulOutBuf_InsertUsefulBuf(pMe, Data, uPos);
}
 
 
static inline void UsefulOutBuf_InsertString(UsefulOutBuf *pMe,
                                             const char *szString,
                                             size_t uPos)
{
   UsefulBufC UBC;
   UBC.ptr = szString;
   UBC.len = strlen(szString);
 
   UsefulOutBuf_InsertUsefulBuf(pMe, UBC, uPos);
}
 
 
static inline void UsefulOutBuf_InsertByte(UsefulOutBuf *me,
                                           uint8_t byte,
                                           size_t uPos)
{
   UsefulOutBuf_InsertData(me, &byte, 1, uPos);
}
 
 
static inline void UsefulOutBuf_InsertUint16(UsefulOutBuf *me,
                                             uint16_t uInteger16,
                                             size_t uPos)
{
   /* See UsefulOutBuf_InsertUint64() for comments on this code */
 
   const void *pBytes;
 
#if defined(USEFULBUF_CONFIG_BIG_ENDIAN)
   pBytes = &uInteger16;
 
#elif defined(USEFULBUF_CONFIG_HTON)
   uint16_t uTmp = htons(uInteger16);
   pBytes        = &uTmp;
 
#elif defined(USEFULBUF_CONFIG_LITTLE_ENDIAN) && defined(USEFULBUF_CONFIG_BSWAP)
   uint16_t uTmp = __builtin_bswap16(uInteger16);
   pBytes = &uTmp;
 
#else
   uint8_t aTmp[2];
 
   aTmp[0] = (uint8_t)((uInteger16 & 0xff00) >> 8);
   aTmp[1] = (uint8_t)(uInteger16 & 0xff);
 
   pBytes = aTmp;
#endif
 
   UsefulOutBuf_InsertData(me, pBytes, 2, uPos);
}
 
 
static inline void UsefulOutBuf_InsertUint32(UsefulOutBuf *pMe,
                                             uint32_t uInteger32,
                                             size_t uPos)
{
   /* See UsefulOutBuf_InsertUint64() for comments on this code */
 
   const void *pBytes;
 
#if defined(USEFULBUF_CONFIG_BIG_ENDIAN)
   pBytes = &uInteger32;
 
#elif defined(USEFULBUF_CONFIG_HTON)
   uint32_t uTmp = htonl(uInteger32);
   pBytes = &uTmp;
 
#elif defined(USEFULBUF_CONFIG_LITTLE_ENDIAN) && defined(USEFULBUF_CONFIG_BSWAP)
   uint32_t uTmp = __builtin_bswap32(uInteger32);
 
   pBytes = &uTmp;
 
#else
   uint8_t aTmp[4];
 
   aTmp[0] = (uint8_t)((uInteger32 & 0xff000000) >> 24);
   aTmp[1] = (uint8_t)((uInteger32 & 0xff0000) >> 16);
   aTmp[2] = (uint8_t)((uInteger32 & 0xff00) >> 8);
   aTmp[3] = (uint8_t)(uInteger32 & 0xff);
 
   pBytes = aTmp;
#endif
 
   UsefulOutBuf_InsertData(pMe, pBytes, 4, uPos);
}
 
static inline void UsefulOutBuf_InsertUint64(UsefulOutBuf *pMe,
                                             uint64_t      uInteger64,
                                             size_t        uPos)
{
   const void *pBytes;
 
#if defined(USEFULBUF_CONFIG_BIG_ENDIAN)
   /* We have been told explicitly we are running on a big-endian
    * machine. Network byte order is big endian, so just copy.  There
    * is no issue with alignment here because uInteger64 is always
    * aligned (and it doesn't matter if pBytes is aligned).
    */
   pBytes = &uInteger64;
 
#elif defined(USEFULBUF_CONFIG_HTON)
   /* Use system function to handle big- and little-endian. This works
    * on both big- and little-endian machines, but hton() is not
    * always available or in a standard place so it is not used by
    * default. With some compilers and CPUs the code for this is very
    * compact through use of a special swap instruction and on
    * big-endian machines hton() will reduce to nothing.
    */
   uint64_t uTmp = htonll(uInteger64);
 
   pBytes = &uTmp;
 
#elif defined(USEFULBUF_CONFIG_LITTLE_ENDIAN) && defined(USEFULBUF_CONFIG_BSWAP)
   /* Use built-in function for byte swapping. This usually compiles
    * to an efficient special byte swap instruction. Unlike hton() it
    * does not do this conditionally on the CPU endianness, so this
    * code is also conditional on USEFULBUF_CONFIG_LITTLE_ENDIAN
    */
   uint64_t uTmp = __builtin_bswap64(uInteger64);
 
   pBytes = &uTmp;
 
#else
   /* Default which works on every CPU with no dependency on anything
    * from the CPU, compiler, libraries or OS.  This always works, but
    * it is usually a little larger and slower than hton().
    */
   uint8_t aTmp[8];
 
   aTmp[0] = (uint8_t)((uInteger64 & 0xff00000000000000ULL) >> 56);
   aTmp[1] = (uint8_t)((uInteger64 & 0xff000000000000ULL) >> 48);
   aTmp[2] = (uint8_t)((uInteger64 & 0xff0000000000ULL) >> 40);
   aTmp[3] = (uint8_t)((uInteger64 & 0xff00000000ULL) >> 32);
   aTmp[4] = (uint8_t)((uInteger64 & 0xff000000ULL) >> 24);
   aTmp[5] = (uint8_t)((uInteger64 & 0xff0000ULL) >> 16);
   aTmp[6] = (uint8_t)((uInteger64 & 0xff00ULL) >> 8);
   aTmp[7] = (uint8_t)(uInteger64  & 0xffULL);
 
   pBytes = aTmp;
#endif
 
   /* Do the insert */
   UsefulOutBuf_InsertData(pMe, pBytes, sizeof(uint64_t), uPos);
}
 
 
#ifndef USEFULBUF_DISABLE_ALL_FLOAT
static inline void UsefulOutBuf_InsertFloat(UsefulOutBuf *pMe,
                                            float f,
                                            size_t uPos)
{
   UsefulOutBuf_InsertUint32(pMe, UsefulBufUtil_CopyFloatToUint32(f), uPos);
}
 
 
static inline void UsefulOutBuf_InsertDouble(UsefulOutBuf *pMe,
                                             double d,
                                             size_t uPos)
{
   UsefulOutBuf_InsertUint64(pMe, UsefulBufUtil_CopyDoubleToUint64(d), uPos);
}
#endif /* USEFULBUF_DISABLE_ALL_FLOAT */
 
 
static inline void UsefulOutBuf_AppendUsefulBuf(UsefulOutBuf *pMe,
                                                UsefulBufC NewData)
{
   /* An append is just a insert at the end */
   UsefulOutBuf_InsertUsefulBuf(pMe, NewData, UsefulOutBuf_GetEndPosition(pMe));
}
 
 
static inline void UsefulOutBuf_AppendData(UsefulOutBuf *pMe,
                                           const void *pBytes,
                                           size_t uLen)
{
   UsefulBufC Data = {pBytes, uLen};
   UsefulOutBuf_AppendUsefulBuf(pMe, Data);
}
 
 
static inline void UsefulOutBuf_AppendString(UsefulOutBuf *pMe,
                                             const char *szString)
{
   UsefulBufC UBC;
   UBC.ptr = szString;
   UBC.len = strlen(szString);
 
   UsefulOutBuf_AppendUsefulBuf(pMe, UBC);
}
 
 
static inline void UsefulOutBuf_AppendByte(UsefulOutBuf *pMe,
                                           uint8_t byte)
{
   UsefulOutBuf_AppendData(pMe, &byte, 1);
}
 
 
static inline void UsefulOutBuf_AppendUint16(UsefulOutBuf *pMe,
                                             uint16_t uInteger16)
{
   UsefulOutBuf_InsertUint16(pMe, uInteger16, UsefulOutBuf_GetEndPosition(pMe));
}
 
static inline void UsefulOutBuf_AppendUint32(UsefulOutBuf *pMe,
                                             uint32_t uInteger32)
{
   UsefulOutBuf_InsertUint32(pMe, uInteger32, UsefulOutBuf_GetEndPosition(pMe));
}
 
 
static inline void UsefulOutBuf_AppendUint64(UsefulOutBuf *pMe,
                                             uint64_t uInteger64)
{
   UsefulOutBuf_InsertUint64(pMe, uInteger64, UsefulOutBuf_GetEndPosition(pMe));
}
 
 
#ifndef USEFULBUF_DISABLE_ALL_FLOAT
static inline void UsefulOutBuf_AppendFloat(UsefulOutBuf *pMe,
                                            float f)
{
   UsefulOutBuf_InsertFloat(pMe, f, UsefulOutBuf_GetEndPosition(pMe));
}
 
 
static inline void UsefulOutBuf_AppendDouble(UsefulOutBuf *pMe,
                                             double d)
{
   UsefulOutBuf_InsertDouble(pMe, d, UsefulOutBuf_GetEndPosition(pMe));
}
#endif /* USEFULBUF_DISABLE_ALL_FLOAT */
 
 
static inline int UsefulOutBuf_GetError(UsefulOutBuf *pMe)
{
   return pMe->err;
}
 
 
static inline size_t UsefulOutBuf_RoomLeft(UsefulOutBuf *pMe)
{
   return pMe->UB.len - pMe->data_len;
}
 
 
static inline int UsefulOutBuf_WillItFit(UsefulOutBuf *pMe, size_t uLen)
{
   return uLen <= UsefulOutBuf_RoomLeft(pMe);
}
 
 
static inline int UsefulOutBuf_IsBufferNULL(UsefulOutBuf *pMe)
{
   return pMe->UB.ptr == NULL;
}
 
 
static inline UsefulBuf UsefulOutBuf_GetOutPlace(UsefulOutBuf *pUOutBuf)
{
   UsefulBuf R;
 
   R.len = UsefulOutBuf_RoomLeft(pUOutBuf);
   if(R.len > 0 && pUOutBuf->UB.ptr != NULL) {
      R.ptr = (uint8_t *)pUOutBuf->UB.ptr + pUOutBuf->data_len;
   } else {
      R.ptr = NULL;
   }
 
   return R;
}
 
 
static inline UsefulBuf UsefulOutBuf_RetrieveOutputStorage(UsefulOutBuf *pMe)
{
   return pMe->UB;
}
 
 
 
 
static inline void UsefulInputBuf_Init(UsefulInputBuf *pMe, UsefulBufC UB)
{
   pMe->cursor = 0;
   pMe->err    = 0;
   pMe->magic  = UIB_MAGIC;
   pMe->UB     = UB;
}
 
static inline size_t UsefulInputBuf_Tell(UsefulInputBuf *pMe)
{
   return pMe->cursor;
}
 
 
static inline size_t UsefulInputBuf_GetBufferLength(UsefulInputBuf *pMe)
{
    return pMe->UB.len;
}
 
 
static inline void UsefulInputBuf_Seek(UsefulInputBuf *pMe, size_t uPos)
{
   if(uPos > pMe->UB.len) {
      pMe->err = 1;
   } else {
      pMe->cursor = uPos;
   }
}
 
 
static inline size_t UsefulInputBuf_BytesUnconsumed(UsefulInputBuf *pMe)
{
   /* Code Reviewers: THIS FUNCTION DOES POINTER MATH */
 
   /* Magic number is messed up. Either the structure got overwritten
    * or was never initialized.
    */
   if(pMe->magic != UIB_MAGIC) {
      return 0;
   }
 
   /* The cursor is off the end of the input buffer given.
    * Presuming there are no bugs in this code, this should never happen.
    * If it is so, the struct was corrupted. The check is retained as
    * as a defense in case there is a bug in this code or the struct is
    * corrupted by an attacker or accidentally.
    */
   if(pMe->cursor > pMe->UB.len) {
      return 0;
   }
 
   /* subtraction can't go negative because of check above */
   return pMe->UB.len - pMe->cursor;
}
 
 
static inline int UsefulInputBuf_BytesAvailable(UsefulInputBuf *pMe, size_t uLen)
{
   return UsefulInputBuf_BytesUnconsumed(pMe) >= uLen ? 1 : 0;
}
 
 
static inline size_t UsefulInputBuf_PointerToOffset(UsefulInputBuf *pUInBuf, const void *p)
{
   return UsefulBuf_PointerToOffset(pUInBuf->UB, p);
}
 
 
static inline const void *UsefulInputBuf_OffsetToPointer(UsefulInputBuf *pUInBuf, size_t uOffset)
 {
    return UsefulBuf_OffsetToPointer(pUInBuf->UB, uOffset);
 }
 
 
static inline UsefulBufC UsefulInputBuf_GetUsefulBuf(UsefulInputBuf *pMe, size_t uNum)
{
   const void *pResult = UsefulInputBuf_GetBytes(pMe, uNum);
   if(!pResult) {
      return NULLUsefulBufC;
   } else {
      UsefulBufC UBC;
      UBC.ptr = pResult;
      UBC.len = uNum;
      return UBC;
   }
}
 
 
static inline uint8_t UsefulInputBuf_GetByte(UsefulInputBuf *pMe)
{
   const void *pResult = UsefulInputBuf_GetBytes(pMe, sizeof(uint8_t));
 
   /* The ternary operator is subject to integer promotion, because
    * the operands are smaller than int, so cast back to uint8_t is
    * needed to be completely explicit about types (for static
    * analyzers).
    */
   return (uint8_t)(pResult ? *(const uint8_t *)pResult : 0);
}
 
static inline uint16_t UsefulInputBuf_GetUint16(UsefulInputBuf *pMe)
{
   const uint8_t *pResult = (const uint8_t *)UsefulInputBuf_GetBytes(pMe, sizeof(uint16_t));
 
   if(!pResult) {
      return 0;
   }
 
   /* See UsefulInputBuf_GetUint64() for comments on this code */
#if defined(USEFULBUF_CONFIG_BIG_ENDIAN) || defined(USEFULBUF_CONFIG_HTON) || defined(USEFULBUF_CONFIG_BSWAP)
   uint16_t uTmp;
   memcpy(&uTmp, pResult, sizeof(uint16_t));
 
#if defined(USEFULBUF_CONFIG_BIG_ENDIAN)
   return uTmp;
 
#elif defined(USEFULBUF_CONFIG_HTON)
   return ntohs(uTmp);
 
#else
   return __builtin_bswap16(uTmp);
 
#endif
 
#else
 
   /* The operations here are subject to integer promotion because the
    * operands are smaller than int. They will be promoted to unsigned
    * int for the shift and addition. The cast back to uint16_t is is
    * needed to be completely explicit about types (for static
    * analyzers).
    */
   return (uint16_t)((pResult[0] << 8) + pResult[1]);
 
#endif
}
 
 
static inline uint32_t UsefulInputBuf_GetUint32(UsefulInputBuf *pMe)
{
   const uint8_t *pResult = (const uint8_t *)UsefulInputBuf_GetBytes(pMe, sizeof(uint32_t));
 
   if(!pResult) {
      return 0;
   }
 
   /* See UsefulInputBuf_GetUint64() for comments on this code */
#if defined(USEFULBUF_CONFIG_BIG_ENDIAN) || defined(USEFULBUF_CONFIG_HTON) || defined(USEFULBUF_CONFIG_BSWAP)
   uint32_t uTmp;
   memcpy(&uTmp, pResult, sizeof(uint32_t));
 
#if defined(USEFULBUF_CONFIG_BIG_ENDIAN)
   return uTmp;
 
#elif defined(USEFULBUF_CONFIG_HTON)
   return ntohl(uTmp);
 
#else
   return __builtin_bswap32(uTmp);
 
#endif
 
#else
   return ((uint32_t)pResult[0]<<24) +
          ((uint32_t)pResult[1]<<16) +
          ((uint32_t)pResult[2]<<8)  +
           (uint32_t)pResult[3];
#endif
}
 
 
static inline uint64_t UsefulInputBuf_GetUint64(UsefulInputBuf *pMe)
{
   const uint8_t *pResult = (const uint8_t *)UsefulInputBuf_GetBytes(pMe, sizeof(uint64_t));
 
   if(!pResult) {
      return 0;
   }
 
#if defined(USEFULBUF_CONFIG_BIG_ENDIAN) || defined(USEFULBUF_CONFIG_HTON) || defined(USEFULBUF_CONFIG_BSWAP)
   /* pResult will probably not be aligned.  This memcpy() moves the
    * bytes into a temp variable safely for CPUs that can or can't do
    * unaligned memory access. Many compilers will optimize the
    * memcpy() into a simple move instruction.
    */
   uint64_t uTmp;
   memcpy(&uTmp, pResult, sizeof(uint64_t));
 
#if defined(USEFULBUF_CONFIG_BIG_ENDIAN)
   /* We have been told expliclity this is a big-endian CPU.  Since
    * network byte order is big-endian, there is nothing to do.
    */
 
   return uTmp;
 
#elif defined(USEFULBUF_CONFIG_HTON)
   /* We have been told to use ntoh(), the system function to handle
    * big- and little-endian. This works on both big- and
    * little-endian machines, but ntoh() is not always available or in
    * a standard place so it is not used by default. On some CPUs the
    * code for this is very compact through use of a special swap
    * instruction.
    */
 
   return ntohll(uTmp);
 
#else
   /* Little-endian (since it is not USEFULBUF_CONFIG_BIG_ENDIAN) and
    * USEFULBUF_CONFIG_BSWAP (since it is not USEFULBUF_CONFIG_HTON).
    * __builtin_bswap64() and friends are not conditional on CPU
    * endianness so this must only be used on little-endian machines.
    */
 
   return __builtin_bswap64(uTmp);
 
 
#endif
 
#else
   /* This is the default code that works on every CPU and every
    * endianness with no dependency on ntoh().  This works on CPUs
    * that either allow or do not allow unaligned access. It will
    * always work, but usually is a little less efficient than ntoh().
    */
 
   return   ((uint64_t)pResult[0]<<56) +
            ((uint64_t)pResult[1]<<48) +
            ((uint64_t)pResult[2]<<40) +
            ((uint64_t)pResult[3]<<32) +
            ((uint64_t)pResult[4]<<24) +
            ((uint64_t)pResult[5]<<16) +
            ((uint64_t)pResult[6]<<8)  +
            (uint64_t)pResult[7];
#endif
}
 
 
#ifndef USEFULBUF_DISABLE_ALL_FLOAT
static inline float UsefulInputBuf_GetFloat(UsefulInputBuf *pMe)
{
   uint32_t uResult = UsefulInputBuf_GetUint32(pMe);
 
   return uResult ? UsefulBufUtil_CopyUint32ToFloat(uResult) : 0;
}
 
 
static inline double UsefulInputBuf_GetDouble(UsefulInputBuf *pMe)
{
   uint64_t uResult = UsefulInputBuf_GetUint64(pMe);
 
   return uResult ? UsefulBufUtil_CopyUint64ToDouble(uResult) : 0;
}
#endif /* USEFULBUF_DISABLE_ALL_FLOAT */
 
 
static inline int UsefulInputBuf_GetError(UsefulInputBuf *pMe)
{
   return pMe->err;
}
 
 
static inline void UsefulInputBuf_SetBufferLength(UsefulInputBuf *pMe, size_t uNewLen)
{
    pMe->UB.len = uNewLen;
}
 
static inline UsefulBufC UsefulInputBuf_RetrieveUndecodedInput(UsefulInputBuf *pMe)
{
   return pMe->UB;
}
 
 
#ifdef __cplusplus
}
#endif
 
#endif  /* _UsefulBuf_h */