.. oe:namespace:: OESystem


.. meta::
   :keywords: OEBitVector, BitVector


.. _OESystem_OEBitVector:

.. oe:class:: OEBitVector

   .. oe:api::

      class OEBitVector

   The :ref:`OEBitVector <OESystem_OEBitVector>` class is used to represent a resizable
   bitmap. These are commonly used to store *fingerprints* in
   cheminformatics.

   .. seealso::

      * :ref:`OESubSearchScreen <OEChem_OESubSearchScreen>` class
      * :ref:`OEFingerPrint <OEGraphSim_OEFingerPrint>` class in **GraphSim TK** manual

   .. oe:method:: Constructors

      .. oe:language:: c++ java csharp

         .. oe:api::

            OEBitVector()
            OEBitVector(unsigned int size)
            OEBitVector(const OEBitVector& src)

      .. oe:language:: python

         .. oe:api:: python

            OEBitVector() -> OEBitVector
            OEBitVector(size: int) -> OEBitVector
            OEBitVector(src: OEBitVector) -> OEBitVector

      When constructed with a ``size`` argument, this specifies the
      initial number of bits in the :ref:`OEBitVector <OESystem_OEBitVector>`.
      When constructed without an argument, the default number of bits
      is architecture dependent, ``32`` bits on 32-bit hosts and
      ``64`` bits on 64-bit hosts. Initially, all the bits are set to
      zero.

      .. oe:language:: c++ java csharp

         .. oe:api::

            OEBitVector(OERandom& rand, unsigned int size)

      .. oe:language:: python

         .. oe:api:: python

            OEBitVector(rand: OERandom, size: int) -> OEBitVector

      Creates a :ref:`OEBitVector <OESystem_OEBitVector>` with ``size`` bits
      randomly initialized from the ``rand`` object.

      .. oe:language:: c++ java csharp

         .. oe:api::

            OEBitVector(const unsigned char* data, unsigned int size)

      .. oe:language:: python

         .. oe:api:: python

            OEBitVector(data: str, size: int) -> OEBitVector

      Using this constructor is equivalent to creating a default
      constructed :ref:`OEBitVector <OESystem_OEBitVector>` and then immediately
      calling :oe:meth:`OESystem::OEBitVector::SetData` with the
      ``data`` and ``size`` arguments.

   .. oe:method:: operator<
      :language: c++

      .. oe:api::

         bool operator<(const OEBitVector &other) const

   .. oe:method:: operator=
      :language: c++

      .. oe:api::

         OEBitVector &operator=(const OEBitVector &src)

      Assignment operator.


   .. oe:method:: operator&=
      :language: c++

      .. oe:api::

         OEBitVector &operator&=(const OEBitVector &)

   .. oe:method:: operator-=
      :language: c++

      .. oe:api::

         OEBitVector &operator-=(const OEBitVector &)

   .. oe:method:: operator[]
      :language: c++

      .. oe:api::

         bool operator[](unsigned int bit) const

   .. oe:method:: operator^=
      :language: c++

      .. oe:api::

         OEBitVector &operator^=(unsigned int bit)
         OEBitVector &operator^=(const OEBitVector &)

   .. oe:method:: operator|=
      :language: c++

      .. oe:api::

         OEBitVector &operator|=(unsigned int bit)
         OEBitVector &operator|=(const OEBitVector &)

   .. oe:method:: ClearBits

      .. oe:language:: c++ java csharp

         .. oe:api::

            void ClearBits()

      .. oe:language:: python

         .. oe:api:: python

            ClearBits() -> None

      Clears all of the bits of the :ref:`OEBitVector <OESystem_OEBitVector>` to zero.

   .. oe:method:: CountBits

      .. oe:language:: c++ java csharp

         .. oe:api::

            unsigned int CountBits() const

      .. oe:language:: python

         .. oe:api:: python

            CountBits() -> int

      Counts the number of bits that are set to one, in the
      :ref:`OEBitVector <OESystem_OEBitVector>` object.

   .. oe:method:: CountRangeBits

      .. oe:language:: c++ java csharp

         .. oe:api::

            unsigned int CountRangeBits(const unsigned start,
                                        const unsigned end) const

      .. oe:language:: python

         .. oe:api:: python

            CountRangeBits(start: int, end: int) -> int

      Counts the number of bits that are set to one in the
      given bit range.

   .. oe:method:: FirstBit

      .. oe:language:: c++ java csharp

         .. oe:api::

            int FirstBit() const

      .. oe:language:: python

         .. oe:api:: python

            FirstBit() -> int

      Returns the index of the first bit, *i.e.* the
      set bit with the lowest index, in the
      :ref:`OEBitVector <OESystem_OEBitVector>`.
      Bit position
      indices are numbered from zero, and have a maximum of
      :oe:meth:`OESystem::OEBitVector::GetSize` ``-1``.
      If the :ref:`OEBitVector <OESystem_OEBitVector>` has no bits set,
      *i.e.* :oe:meth:`OESystem::OEBitVector::IsEmpty` returns
      ``true``, this method return will
      return the value ``-1``.

   .. oe:method:: FromHexString

      .. oe:language:: c++ java csharp

         .. oe:api::

            void FromHexString(const char* bvs)
            void FromHexString(const std::string& bvs)

      .. oe:language:: python

         .. oe:api:: python

            FromHexString(bvs: str) -> None

      Converts a hexadecimal string, in either upper, lower or mixed case,
      into an :ref:`OEBitVector <OESystem_OEBitVector>`.  Each valid hexadecimal digit
      (0-9, a-f, A-F) translates to four bits in the
      :ref:`OEBitVector <OESystem_OEBitVector>`.
      Note: Because :oe:cls:`OEBitVectors<OESystem::OEBitVector>` may have a
      length not divisible by four,
      the last character of an OEChem-generated hexadecimal string may
      be a non-hex digit encoding the correct length of the
      :ref:`OEBitVector <OESystem_OEBitVector>`. Don't worry if you see a non-hex
      digit at the end of a hexadecimal string.

      .. seealso::

         * :oe:meth:`OESystem::OEBitVector::ToHexString` method

   .. oe:method:: GetData

      .. oe:language:: c++ java csharp

         .. oe:api::

            const unsigned char* GetData() const

      .. oe:language:: python

         .. oe:api:: python

            GetData() -> str

      Returns a pointer to the internal storage of
      the :ref:`OEBitVector <OESystem_OEBitVector>`'s bitmap.
      This pointer to a sequence of at least
      (:oe:meth:`OESystem::OEBitVector::GetSize` ``+7)/8`` consecutive bytes. Bit index zero
      corresponds to the least significant bit of the first byte. All
      bits beyond :oe:meth:`OESystem::OEBitVector::GetSize` in the last byte are guaranteed
      to be zero. The :oe:meth:`OESystem::OEBitVector::GetData` method always returns a valid non-NULL
      pointer even if the number of bits is zero.

   .. oe:method:: GetSize

      .. oe:language:: c++ java csharp

         .. oe:api::

            unsigned int GetSize() const

      .. oe:language:: python

         .. oe:api:: python

            GetSize() -> int

      Returns the size, in bits, of the
      :ref:`OEBitVector <OESystem_OEBitVector>`.
      An :ref:`OEBitVector <OESystem_OEBitVector>` may potentially contain zero bits.

   .. oe:method:: IsBitOn

      .. oe:language:: c++ java csharp

         .. oe:api::

            bool IsBitOn(unsigned int bit) const

      .. oe:language:: python

         .. oe:api:: python

            IsBitOn(bit: int) -> bool

      Tests whether the bit as the
      specified position/index of an :ref:`OEBitVector <OESystem_OEBitVector>` is set.
      Bit position
      indices are numbered from zero, and have a maximum of
      :oe:meth:`OESystem::OEBitVector::GetSize` ``-1``. This method returns ``false`` for all
      indices greater than or equal to :oe:meth:`OESystem::OEBitVector::GetSize`.

   .. oe:method:: IsEmpty

      .. oe:language:: c++ java csharp

         .. oe:api::

            bool IsEmpty() const

      .. oe:language:: python

         .. oe:api:: python

            IsEmpty() -> bool

      Returns ``true`` if all the bits of an :ref:`OEBitVector <OESystem_OEBitVector>` are zero.
      This is
      equivalent to, but much more efficient than, testing that
      :oe:meth:`OESystem::OEBitVector::CountBits` == 0. An :ref:`OEBitVector <OESystem_OEBitVector>` of
      zero size is considered empty.

   .. oe:method:: LastBit

      .. oe:language:: c++ java csharp

         .. oe:api::

            int LastBit() const

      .. oe:language:: python

         .. oe:api:: python

            LastBit() -> int

      Returns the index of the last bit, *i.e.* the
      set bit with the highest index, in the
      :ref:`OEBitVector <OESystem_OEBitVector>`.
      Bit position indices are numbered from zero, and have a maximum of
      :oe:meth:`OESystem::OEBitVector::GetSize` ``-1``. If the
      :ref:`OEBitVector <OESystem_OEBitVector>` has no bits set,
      *i.e.* :oe:meth:`OESystem::OEBitVector::IsEmpty` returns
      ``true``, this method return will
      return the value ``-1``.

   .. oe:method:: NegateBits

      .. oe:language:: c++ java csharp

         .. oe:api::

            void NegateBits()

      .. oe:language:: python

         .. oe:api:: python

            NegateBits() -> None

      Inverts all of the bits of an :ref:`OEBitVector <OESystem_OEBitVector>`.

   .. oe:method:: NextBit

      .. oe:language:: c++ java csharp

         .. oe:api::

            int NextBit(unsigned int) const

      .. oe:language:: python

         .. oe:api:: python

            NextBit(arg2: int) -> int

      Returns the next set bit after the specified
      bit position, *i.e.* the set bit with the lowest index greater
      than the argument. If there are no such set bits, or the value
      of bit is greater than or equal to :oe:meth:`OESystem::OEBitVector::GetSize`, this
      method returns the value ``-1``.

   .. oe:method:: PrevBit

      .. oe:language:: c++ java csharp

         .. oe:api::

            int PrevBit(unsigned int) const

      .. oe:language:: python

         .. oe:api:: python

            PrevBit(arg2: int) -> int

      Returns the previous set bit before the
      specified bit position, *i.e.* the set bit with the highest index
      less than the argument. If there are no such set bits, this
      method returns the value ``-1``. If the specified value of bit is
      greater than or equal to :oe:meth:`OESystem::OEBitVector::GetSize`, this method
      returns the same values as :oe:meth:`OESystem::OEBitVector::LastBit`.

   .. oe:method:: SetBitOff

      .. oe:language:: c++ java csharp

         .. oe:api::

            void SetBitOff(unsigned int bit)

      .. oe:language:: python

         .. oe:api:: python

            SetBitOff(bit: int) -> None

      Clears the bit at the specified bit
      position/index of an :ref:`OEBitVector <OESystem_OEBitVector>`. Bit position indices are
      numbered from zero, and have a maximum of
      :oe:meth:`OESystem::OEBitVector::GetSize` ``-1``. If the value of 'bit' is greater than
      or equal to :oe:meth:`OESystem::OEBitVector::GetSize`, the bitmap is resized to
      'bit'+1 bits. All of the new bits are initialized to zero.

   .. oe:method:: SetBitOn

      .. oe:language:: c++ java csharp

         .. oe:api::

            void SetBitOn(unsigned int bit)

      .. oe:language:: python

         .. oe:api:: python

            SetBitOn(bit: int) -> None

      Tests whether the bit as the
      specified position/index of an :ref:`OEBitVector <OESystem_OEBitVector>` is set. Bit position
      indices are numbered from zero, and have a maximum of
      :oe:meth:`OESystem::OEBitVector::GetSize` ``-1``. This method returns ``false`` for all
      indices greater than or equal to :oe:meth:`OESystem::OEBitVector::GetSize`.

   .. oe:method:: SetData

      .. oe:language:: c++ java csharp

         .. oe:api::

            void SetData(const unsigned char* data, unsigned int nbits)

      .. oe:language:: python

         .. oe:api:: python

            SetData(data: str, nbits: int) -> None

      Initialize the :ref:`OEBitVector <OESystem_OEBitVector>` by the binary data
      pointed to by ``data``, possibly resizing the
      :ref:`OEBitVector <OESystem_OEBitVector>` to accommodate the ``nbits`` of
      data. ``data`` should point to at least ``nbits/8`` bytes of
      data. If a non-multiple of 8 bits is to be copied it is the
      users responsibility to make sure the remainder of bits in the
      last byte are zeroed out.

   .. oe:method:: SetRangeOff

      .. oe:language:: c++ java csharp

         .. oe:api::

            void SetRangeOff(unsigned int start, unsigned int end)

      .. oe:language:: python

         .. oe:api:: python

            SetRangeOff(start: int, end: int) -> None

   .. oe:method:: SetRangeOn

      .. oe:language:: c++ java csharp

         .. oe:api::

            void SetRangeOn(unsigned int start, unsigned int end)

      .. oe:language:: python

         .. oe:api:: python

            SetRangeOn(start: int, end: int) -> None

   .. oe:method:: SetSize

      .. oe:language:: c++ java csharp

         .. oe:api::

            void SetSize(unsigned int bits)

      .. oe:language:: python

         .. oe:api:: python

            SetSize(bits: int) -> None

      Resizes an :ref:`OEBitVector <OESystem_OEBitVector>` to the specified
      number of bits. A size argument of zero is allowed. If this
      method increases the size of an :ref:`OEBitVector <OESystem_OEBitVector>` all of the new bit
      positions are initialized to zero.

   .. oe:method:: ToHexString

      .. oe:language:: c++ java csharp

         .. oe:api::

            void ToHexString(std::string& bvs) const

      .. oe:language:: python

         .. oe:api:: python

            ToHexString() -> str

      Generates a hexadecimal string representation of an
      :ref:`OEBitVector <OESystem_OEBitVector>`.
      Each "nibble" of four bits is converted into an uppercase hexadecimal
      character.

      .. figure:: ../images/OEBitVector_ToHexString.*
         :align:  center

         **The interpretation of the four-bit long "nibble"-s (big-endian system)**

      The four-bit long "nibble" shown above is encoded as hexadecimal 'A':

      :math:`0 * 2^0 + 1 * 2^1 + 0 * 2^2 + 1 * 2^3 = 0 + 2 + 0 + 8 = 10 (dec) = A (hex)`

      Because :oe:cls:`OEBitVectors<OESystem::OEBitVector>` may have a length
      that is not a multiple of four, an extra non-hexadecimal digit is added
      to the end of the string to encode the correct
      :ref:`OEBitVector <OESystem_OEBitVector>` length.

      .. table:: **Interpretation of last character**

         ========================= ===========================================
         last character            number of extra bits
         ========================= ===========================================
         'J'                       0
         'G'                       1
         'H'                       2
         'I'                       3
         ========================= ===========================================

      For example, if the size of the bit-vector is 8 (multiple of four), then
      the last character of the returned string will be 'J'.
      If the size of the bit-vector is 9, then the last character will be 'I',
      since there will be three extra bits to add up to a number that can be
      multiplied by four.

      .. seealso::

         * :oe:meth:`OESystem::OEBitVector::FromHexString` method

   .. oe:method:: ToggleBit

      .. oe:language:: c++ java csharp

         .. oe:api::

            void ToggleBit(unsigned int bit)

      .. oe:language:: python

         .. oe:api:: python

            ToggleBit(bit: int) -> None

      Inverts the bit at the specified bit
      position/index of an :ref:`OEBitVector <OESystem_OEBitVector>`. Bit position indices are
      numbered from zero, and have a maximum of
      :oe:meth:`OESystem::OEBitVector::GetSize` ``-1``. If the value of 'bit' is greater than
      or equal to :oe:meth:`OESystem::OEBitVector::GetSize`, the bitmap is resized to
      'bit'+1 bits. All of the new bits other than the one specified in
      the argument, *i.e.* the last, are initialized to zero.
