Line data    Source code

       1             : /* ✔ */
       2             : 
       3             : #pragma once
       4             : 
       5             : #include <AH/Error/Error.hpp>
       6             : #include <AH/Settings/NamespaceSettings.hpp>
       7             : #include <stdint.h>
       8             : 
       9             : BEGIN_AH_NAMESPACE
      10             : 
      11             : /// @addtogroup AH_Containers
      12             : /// @{
      13             : 
      14             : /**
      15             :  * @brief   A class for arrays of bits.
      16             :  * 
      17             :  * @tparam  N
      18             :  *          The number of bits.
      19             :  */
      20             : template <uint16_t N>
      21             : class BitArray {
      22             :   public:
      23             :     /**
      24             :      * @brief   Get the value of the given bit.
      25             :      * 
      26             :      * @param   bitIndex
      27             :      *          The (zero-based) index of the bit to read.
      28             :      */
      29          65 :     bool get(uint16_t bitIndex) const {
      30          65 :         return buffer[getBufferIndex(bitIndex)] & getBufferMask(bitIndex);
      31             :     }
      32             : 
      33             :     /**
      34             :      * @brief   Set the value of the given bit to 1.
      35             :      * 
      36             :      * @param   bitIndex
      37             :      *          The (zero-based) index of the bit to set.
      38             :      */
      39           3 :     void set(uint16_t bitIndex) {
      40           3 :         buffer[getBufferIndex(bitIndex)] |= getBufferMask(bitIndex);
      41           3 :     }
      42             : 
      43             :     /**
      44             :      * @brief   Clear the value of the given bit to 0.
      45             :      * 
      46             :      * @param   bitIndex
      47             :      *          The (zero-based) index of the bit to clear.
      48             :      */
      49           2 :     void clear(uint16_t bitIndex) {
      50           2 :         buffer[getBufferIndex(bitIndex)] &= ~getBufferMask(bitIndex);
      51           2 :     }
      52             : 
      53             :     /**
      54             :      * @brief   Set the value of the given bit to the given state.
      55             :      * 
      56             :      * @param   bitIndex
      57             :      *          The (zero-based) index of the bit to set.
      58             :      * @param   state
      59             :      *          The value to set the bit to.
      60             :      */
      61           2 :     void set(uint16_t bitIndex, bool state) {
      62           2 :         state ? set(bitIndex) : clear(bitIndex);
      63           2 :     }
      64             : 
      65             :     /**
      66             :      * @brief   Check the given byte index, and return it if it is within the
      67             :      *          bounds of the array, otherwise, throw an error, and return
      68             :      *          the last valid index.
      69             :      * 
      70             :      * @param   byteIndex 
      71             :      *          The index to check.
      72             :      */
      73          70 :     uint16_t safeIndex(uint16_t byteIndex) const {
      74          70 :         if (byteIndex >= getBufferLength()) {
      75           1 :             ERROR(F("Error: index out of bounds (")
      76             :                       << byteIndex << F(", length is ") << getBufferLength()
      77             :                       << ')',
      78             :                   0xFFFF);
      79             :             return getBufferLength() - 1; // LCOV_EXCL_LINE
      80             :         }
      81          69 :         return byteIndex;
      82             :     }
      83             : 
      84             :     /**
      85             :      * @brief   Get the byte at the given index.
      86             :      * 
      87             :      * This function can be used to quickly access all of the bits, to send 
      88             :      * them out to a shift register, for example.
      89             :      * 
      90             :      * @note    No bounds checking is performed.
      91             :      * 
      92             :      * @param   byteIndex
      93             :      *          The index of the byte within the array. 
      94             :      */
      95             :     const uint8_t &getByte(uint16_t byteIndex) const {
      96             :         return buffer[byteIndex];
      97             :         // return buffer[safeIndex(byteIndex)];
      98             :     }
      99             :     /// @copydoc AH::BitArray::getByte(uint16_t) const
     100             :     uint8_t &getByte(uint16_t byteIndex) {
     101             :         return buffer[byteIndex];
     102             :         // return buffer[safeIndex(byteIndex)];
     103             :     }
     104             : 
     105             :     /**
     106             :      * @brief   Set the byte at the given index.
     107             :      * 
     108             :      * This function can be used to quickly write all of the bits, when reading
     109             :      * them in from an I/O expander, for example.
     110             :      * 
     111             :      * @note    No bounds checking is performed.
     112             :      * 
     113             :      * @param   byteIndex
     114             :      *          The index of the byte within the array. 
     115             :      * @param   value
     116             :      *          The byte to write.
     117             :      */
     118             :     void setByte(uint16_t byteIndex, uint8_t value) {
     119             :         buffer[byteIndex] = value;
     120             :     }
     121             : 
     122             :     /**
     123             :      * @brief   Get the buffer length in bytes.
     124             :      */
     125          71 :     uint16_t getBufferLength() const { return bufferLength; }
     126             : 
     127             :   private:
     128          70 :     uint16_t getBufferIndex(uint16_t bitIndex) const {
     129          70 :         return safeIndex(bitIndex / 8);
     130             :     }
     131          69 :     uint8_t getBufferBit(uint16_t bitIndex) const { return bitIndex % 8; }
     132          69 :     uint8_t getBufferMask(uint16_t bitIndex) const {
     133          69 :         return 1 << getBufferBit(bitIndex);
     134             :     }
     135             : 
     136             :     constexpr static uint16_t bufferLength = (uint16_t)((N + 7) / 8);
     137             :     uint8_t buffer[bufferLength] = {};
     138             : };
     139             : 
     140             : /// @}
     141             : 
     142             : END_AH_NAMESPACE