/*
 * (c) Copyright, Real-Time Innovations, 2002-2024.
 * All rights reserved.
 *
 * No duplications, whole or partial, manual or electronic, may be made
 * without express written permission.  Any such copies, or
 * revisions thereof, must display this notice unaltered.
 * This code contains trade secrets of Real-Time Innovations, Inc.
 */

#ifndef osapi_bufferUtils_h
#define osapi_bufferUtils_h

#include "osapi/osapi_dll.h"
#include "osapi/osapi_type.h"

#ifdef __cplusplus
extern "C" {
#endif

/** @internal \file
 *   \brief Memory management utilities.
 */

/** @internal \defgroup RTIOsapiMemoryClass RTIOsapiMemory
 * \ingroup RTIOsapiModule
 * \brief These are utilities for OS-independent memory manipulation such
 * as filling & copying.
 */

/** @internal \ingroup RTIOsapiMemoryClass
 * \brief Copies size bytes from non-overlapping src to dest.
 *
 * @pre Valid dest and src >= size, where size >= 0.  The src
 * and dst memory regions should NOT overlap or the results will
 * be undetermined
 *
 * @post size number of bytes from in [dest, dest+size) are identical to
 * [src, src+size).
 *
 * @param dest \b Out. Pointer to destination memory region.
 * @param src \b In. Pointer to source memory region.
 * @param size \b In. Number of bytes to copy starting at dest.
 *
 * @exception none.
 *
 * @mtsafety src cannot be modified concurrently and dest cannot be
 * not modified or read concurrently.
 */
extern RTIOsapiDllExport void RTIOsapiMemory_copy(
        void *dest,
        const void *src,
        int size);

/** @internal \ingroup RTIOsapiMemoryClass
 * \brief Moves size bytes from potentionally-overlapping src to dest.
 *
 * @pre Valid dest and src >= size, where size >= 0.  The src
 * and dst memory regions may overlap
 *
 * @post size number of bytes from in [dest, dest+size) are identical to
 * what was in [src, src+size) before the call.
 *
 * @param dest \b Out. Pointer to destination memory region.
 * @param src \b In. Pointer to source memory region.
 * @param size \b In. Number of bytes to copy starting at dest.
 *
 * @exception none.
 *
 * @mtsafety src cannot be modified concurrently and dest cannot be
 * not modified or read concurrently.
 */
extern RTIOsapiDllExport void RTIOsapiMemory_move(
        void *dest,
        const void *src,
        int size);

/** @internal \ingroup RTIOsapiMemoryClass
 * \brief Sets memory region to 0.
 *
 * @pre Valid memory >= size, where size >= 0.
 *
 * @post [mem, mem+size) filled with 0.
 *
 * @param mem \b Out. Pointer to memory region to be modified.
 * @param size \b In. Number of bytes to zero starting at mem.
 *
 * @exception none.
 *
 * @mtsafety mem cannot be modified or read concurrently.
 */
extern RTIOsapiDllExport void RTIOsapiMemory_zero(void *mem, int size);

/** @internal \ingroup RTIOsapiMemoryClass
 * \brief bytewise compare of 2 memory region.
 *
 * @pre Valid left and right >= 0, where size >= 0.
 *
 * @post left and right unchanged.
 *
 * @param left \b In. Pointer to logical "left" side of the inequality test.
 * @param right \b In. Pointer to logical "right" side of the inequality test.
 * @param size \b In. Number of bytes to compare starting at left and right.
 *
 * @return less than, equal to, or greater than  0, according as left is
 * lexicographically less than, equal to, or greater than right when
 * taken to be unsigned characters.
 *
 * @exception none
 *
 * @mtsafety neither left nor right can be modified concurrently.
 */
extern RTIOsapiDllExport int RTIOsapiMemory_compare(
        const void *left,
        const void *right,
        int size);

/** @internal \ingroup RTIOsapiMemoryClass
 * \brief Checks if a memory region is all zero
 *
 * @param memory \b In. Pointer to a memory region (no alignment requirements)
 * @param length \b In. Number of bytes to check
 *
 * @return RTI_TRUE if all bytes between memory and memory + length are zero
 */
extern RTIOsapiDllExport RTIBool
RTIOsapiMemory_isZero(char *memory, unsigned int length);

/** @internal \ingroup RTIOsapiMemoryClass
 * \brief Prints an hexadecimal dump (and a printable character dump) of the
 * provided buffer, with an optional string prefix.
 *
 * @param prefix \b In. String prefix to be printed at the beginning of each
 *                      dump line.
 * @param buffer \b In. Pointer to the memory region to dump.
 * @param size \b In.   Number of bytes to print.
 */
extern RTIOsapiDllExport void RTIOsapiMemory_hexdump(
        const char *prefix,
        const void *buffer,
        unsigned int size);

#ifdef __cplusplus
} /* extern "C" */
#endif

/* Pick up hidden performance boosting macros and optimizations */
#include "osapi/osapi_bufferUtils_impl.h"

#endif /* osapi_bufferUtils_h */