src/chip_data/hei_chip_data_stream.hpp

#pragma once

/**
@file hei_chip_data_stream.hpp
@brief Description:  The ChipDataStream class

ChipDataStream makes it possible to read a buffer of binary data using the
stream operators, ">>".

Instantiate ChipDataStream class with a pointer to a data buffer
and its size in bytes as below:

    ChipDataStream cds(streamData,552);

Use the ">>" stream operator then to read the basic integral types
(bool, char, uint8_t, int8_t, uint16_t, int16_t, uint32_t,
int32_t, uint64_t, and int64_t).

Endian issues are taken care of by template specialization.
**/

#include <endian.h>
#include <hei_includes.hpp>
#include <string.h>

namespace libhei
{

/**
 * ChipDataStream
 * ChipDataStream offers convenient stream operator access to binary data.
 **/
class ChipDataStream
{

  private:

    /** iv_buffer points to the first address of the Chip Data File
        buffer.  **/
    const void * const iv_buffer;
    /** iv_bufferSize is the size of the data buffer.  It is
        initialized when the ChipDataStream class is instantiated. **/
    const size_t iv_bufferSize;
    /** iv_asyncOffset keeps an offset into the buffer.  This
        offset is incremented appropriately as data is read. **/
    size_t iv_asyncOffset;

  public:

    /* Constructors */

    /**
    When instantiating the ChipDataStream object a pointer to a
    data buffer containing all the data and its size is passed
    into the class.
    **/
    ChipDataStream(void * i_buffer, size_t i_bufferSize) :
        iv_asyncOffset(0), iv_buffer(i_buffer), iv_bufferSize(i_bufferSize)
    {}

    /** Eliminate copy and assignment operator constructors **/
    ChipDataStream(const ChipDataStream &) = delete;
    ChipDataStream & operator=(const ChipDataStream &) = delete;

    /** Destructor **/

    ~ChipDataStream() = default;

    /** Functions **/

    /**
     *@brief Default case for "operator>>" template.
     *@param             D:       A type
     *@param             o_right: A pointer to where the data is stored
     *@return            *this:   A pointer to "this" object
     **/
    template <class D>
    ChipDataStream & operator>>(D & o_right)
    {
        read(&o_right, sizeof(D));
        return *this;
    }

  private:

    /**
     *@brief Read does the copy from the buffer
     *@param o_buf       a pointer to the location to copy to
     *@param i_size      the size (in bytes) to copy
     *@return            None\n\n
     **/
    void read(void * o_buf, size_t i_size)
    {
        /* Ensure memory is not accessed outside i_buffer */
        HEI_ASSERT((iv_asyncOffset + i_size) <= iv_bufferSize);
        /* Copy appropriate bytes from i_buffer to o_buff */
        memcpy(o_buf, (char *)iv_buffer + iv_asyncOffset, i_size);
        /* Increment asynchronous offset to next piece of data */
        iv_asyncOffset = iv_asyncOffset + i_size;
    }
};

/*
 *   Note:  The specializations below ensure the big-endian Chip Data File
 *          format is converted into the host format.
 */

/**
 *   @brief This template extracts a uint16_t data type from the data buffer
 *   @param             o_right: A pointer to where the data is stored
 *   @return            *this:   A pointer to "this" object
 **/
template <> inline
ChipDataStream & ChipDataStream::operator>>(uint16_t & o_right)
{
    read(&o_right, sizeof(o_right));
    be16toh(o_right);
    return *this;
}

/**@brief This template extracts an int16_t type from the data buffer
 *  @param             o_right: A pointer to where the data is stored
 *  @return            *this:   A pointer to "this" object
 **/
template <> inline
ChipDataStream & ChipDataStream::operator>>(int16_t & o_right)
{
    read(&o_right, sizeof(o_right));
    be16toh(o_right);
    return *this;
}

/**@brief This template extracts a uint32_t type from the data buffer
 *  @param             o_right: A pointer to where the data is stored
 *  @return            *this:   A pointer to "this" object
 **/
template <> inline
ChipDataStream & ChipDataStream::operator>>(uint32_t & o_right)
{
    read(&o_right, sizeof(o_right));
    be32toh(o_right);
    return *this;
}

/**@brief This template extracts an int32_t type from the data buffer
 *  @param             o_right: A pointer to where the data is stored
 *  @return            *this:   A pointer to "this" object
 **/
template <> inline
ChipDataStream & ChipDataStream::operator>>(int32_t & o_right)
{
    read(&o_right, sizeof(o_right));
    be32toh(o_right);
    return *this;
}

/**@brief This template extracts a uint64_t type from the data buffer
 *  @param             o_right: A pointer to where the data is stored
 *  @return            *this:   A pointer to "this" object
 **/
template <> inline
ChipDataStream & ChipDataStream::operator>>(uint64_t & o_right)
{
    read(&o_right, sizeof(o_right));
    be64toh(o_right);
    return *this;
}

/**@brief This template extracts an int64_t type from the data buffer
 *  @param             o_right: A pointer to where the data is stored
 *  @return            *this:   A pointer to "this" object
 **/
template <> inline
ChipDataStream & ChipDataStream::operator>>(int64_t & o_right)
{
    read(&o_right, sizeof(o_right));
    be64toh(o_right);
    return *this;
}

} // namespace libhei