+ View the NASA Portal

Search JPL

Search CLARAty

- Algorithms- Infrastructure - Doxygen (public)- Doxygen (private)- Tutorials

- Repository- Nightly Build- Nightly Regression- Feature/Bug Tracking- Build Targets- Procedure- Conventions- Tools

bits.h

Go to the documentation of this file.

// -*-c++-*-
//---------------------------< /-/ CLARAty /-/ >------------------------------
/**
 * @file  bits.h
 *
 * Bit field manipulations. Bits are used for Digital I/O
 *
 * <br>@b Designer(s):  Issa A.D. Nesnas, Won S. Kim
 * <br>@b Author(s):    Won S. Kim, Issa A.D. Nesnas
 * <br>@b Date:         August 15, 2002
 *
 * <b>Software License:</b><br>
 * <code> http://claraty.jpl.nasa.gov/license/open_src/  or 
 *        file: license/open_src.txt </code> 
 *
 * &copy; 2006, Jet Propulsion Laboratory, California Institute of Technology<br>
 *
 * $Revision: 1.7 $
 */
//-----------------------------------------------------------------------------

#ifndef BITS_H
#define BITS_H

#include "claraty/share.h"

#include <iostream>
#include <string>               // C++ string

namespace claraty {

/**
 * @defgroup hardware_io I/O
 * @ingroup hardware_pkg
 *
 * Hardware I/O Module
 */
//@{
//@}

/**
 *  @ingroup hardware_io
 *
 *  Based on the STL bitset source code for the single-word specialization.
 */
//@{
//@}

// maximum number of bits --- machine dependent; mostly 32 bits
//
const size_t MAX_BITS = sizeof(unsigned long) * 8;      // # of bytes * 8 bits

class Bits {

  //
  // based on the STL bitset source code for the single-word specialization
  //

public:
  class reference;                              // reference to single bit b[i]
  friend class reference;

  /** @{ @name Constructors/Destructors */

  Bits(unsigned long val = 0, size_t n_bits = MAX_BITS);        // constructor
  explicit Bits(const std::string& str, size_t n_bits = MAX_BITS);      // constructor

  // copy constructor
  // Bits(const Bits&)                          // use default copy constructor



  // destructor
  // ~Bits()                                    // use default destructor
  /** @} */


  /** @{ @name Assignment/index operations */

  // assignment operator
  Bits& operator=(const Bits& rhs);             // assignment operator

  // index operator or subscript operator
  reference operator[](size_t pos);             // b[i] as an lvalue temporary
  bool operator[](size_t pos) const;            // b[i] as const

  /** @} */

  /** @{ @name Bit manipulation operators  */

  Bits& operator&=(const Bits& rhs);            // bitwise AND
  Bits& operator|=(const Bits& rhs);            // bitwise OR
  Bits& operator^=(const Bits& rhs);            // bitwise EXCLUSIVE-OR
  Bits& operator<<=(size_t n);                  // shift left: fill with zeros
  Bits& operator>>=(size_t n);                  // shift right: fill with zeros

  // bit manipulation functions

  Bits& set();                                  // set every bit to 1
  Bits& set_bit(size_t pos, bool val = true);   // b[pos] = val (default true)
  Bits& set_bits(size_t pos, size_t n);         // b[pos] = ... = b[pos+n-1] = 1
  Bits& clr();                                  // set every bit to 0
  Bits& clr_bit(size_t pos);                    // b[pos] = 0
  Bits& clr_bits(size_t pos, size_t n);         // b[pos] = ... = b[pos+n-1] = 0
  Bits& toggle();                               // change the value of every bit
  Bits& toggle_bit(size_t pos);                 // change the value of b[pos]

  Bits& unchecked_set(unsigned long data);      // b._data = data
                                                // data is assumed sanitized
  /** @} */

  // other bit operations that do not change the object (lhs)

  Bits operator<<(size_t n) const;              // for b2 = b1<<3; b1 unchanged
  Bits operator>>(size_t n) const;              // for b2 = b1>>3; b1 unchanged
  Bits operator~() const;                       // for b2 = ~b1;   b1 unchanged


  /** @{ @name Bit testing operations */

  bool operator==(const Bits& rhs) const;       // for b1==b2 and for b1==0x14
  bool operator!=(const Bits& rhs) const;       // for b1!=b2 and for b1!=0x14
  bool test(size_t pos) const;                  // true if b[pos] is 1
  bool is_set(size_t pos) const;                // true if b[pos] is 1
  bool get_bit(size_t pos) const;               // retrieves b[pos]

  // bool is_set (int pos) const;               // alias for test()
  // bool get_bit(size_t pos) const;            // alias for test()
  bool any() const;                             // true if any bit is 1
  bool none() const;                            // true if no bit is 1

  /** @} */

  //  bit size

  size_t size() const;                          // number of bits


  // named conversion instead of conversion operators to avoid confusion

  unsigned long to_ulong() const;               // conversion to unsigned long

  std::string to_str() const;

  // printout

  void  print(const char* msg = "") const;      // specially formatted printing

private:
  void _sanitize();                     // zero out the unused high-order bits

private:
  unsigned long _data;                          // bit data
  size_t        _Nbits;                         // number of bits --- bit size
};

//
// static functions to generate the mask bit patterns
//
static unsigned long _maskbit(size_t pos)
{
  // only one mask bit at pos is 1;
  // mask[pos]=1; all other bits = 0
  //
  return (static_cast<unsigned long>(1) << pos);
}
//------------------------------------------------------------------------

static unsigned long _maskbits(size_t pos, size_t n)
{
  // n mask bits starting from pos are 1;
  // mask[pos] = ... = mask[pos+n-1] = 1; all other bits = 0
  //
  return (~(~static_cast<unsigned long>(0) << n)) << pos;
}
//------------------------------------------------------------------------


//
//  non-member binary operator functions
//
inline Bits operator&(const Bits& lhs, const Bits& rhs);
inline Bits operator|(const Bits& lhs, const Bits& rhs);
inline Bits operator^(const Bits&, const Bits&);
std::ostream& operator<<(std::ostream& ostr, const Bits& rhs);


//
//-------------------<< Bits::reference class declaration>>--------------
//

class Bits::reference
{
  //
  // Bits::reference class --- reference to a single bit; b[i]
  // this nested class is needed, since there is no built-in pointer
  //   to address a single bit diretcly
  // see p. 492, C++ Programming Language, 3rd ed., Stroustrup
  //
  friend class Bits;

  unsigned long* _data_p;       // pointer to _data
  size_t _bit_pos;                      // bit position

  reference();                  // left undefined; should never be called

public:
  reference(Bits& b, size_t pos);               // constructor
  ~reference() {}                               // empty default destructor

  reference& operator= (bool x);                        // for b[i] = x
  reference& operator= (const reference& j);            // for b[i] = b[j];
  bool operator~ () const;                              // return ~b[i]
  operator bool() const;                                // for x = b[i];
  reference& toggle();                                  // for b[i].toggle();
};
//------------------------------------------------------------------------

inline Bits::reference::reference(Bits& b, size_t pos)
  : _data_p(&b._data), _bit_pos(pos)
{
  // constructor
  //
  // initialization is all we need
}
//------------------------------------------------------------------------


//
//------------------<< Bits::reference inline Functions >>---------------
//

//
//  bit manipulations using index of b[i]
//
//  b[1] = 0
//  b[2] = b[3]
//  b[2] = ~b[3]
//  b[2].toggle()
//  b[3] = b[1] & b[2]
//  bool x = b[1]
//  b[3] = b[1] | x;
//  bool y = b[1] ^ 1;
//

inline Bits::reference& Bits::reference::operator= (bool x)
{
  // for b[i] = x
  //
  if ( x )
    *_data_p |= _maskbit(_bit_pos);
  else
    *_data_p &= ~_maskbit(_bit_pos);

  return *this;
}

inline Bits::reference& Bits::reference::operator= (const Bits::reference& j)
{
  // for b[i] = b[j];
  //
  if ( *j._data_p & _maskbit(j._bit_pos) )
    *_data_p |= _maskbit(_bit_pos);
  else
    *_data_p &= ~_maskbit(_bit_pos);

  return *this;
}

inline bool Bits::reference::operator~() const
{
  // return ~b[i]
  //
  return (*_data_p & _maskbit(_bit_pos)) == 0;
}

inline Bits::reference::operator bool() const
{
  // for x = b[i]; conversion operator to a built-in type bool
  //
  return (*_data_p & _maskbit(_bit_pos)) != 0;  // != has precedence over &
}

inline Bits::reference& Bits::reference::toggle()
{
  // for b[i].toggle();
  //
  *_data_p ^= _maskbit(_bit_pos);
  return *this;
}


//
//-------------------------<< Bits inline Functions >>-------------------
//

//
// Constructors
//
inline Bits::Bits (unsigned long val, size_t n_bits)
   : _data(val), _Nbits(n_bits)
{
  // Constructor
  //
  // default args:
  //   unsigned long val = 0
  //   size_t n_bits = MAX_BITS = sizeof(unsigned long)
  //
  // input args:
  //    unsigned long val --- bit pattern in hexadecimal/octal/decimal number
  //    size_t n_bits --- number of bits ( >= MAX_BITS )
  //
  // Bits b1;                   // b1 = 0000 0000 0000 0000 (_Nbits = MAX_BITS)
  // Bits b1(0x14);             // b1 = 0000 0000 0001 0100 (_Nbits = MAX_BITS)
  // Bits b1 = 0x14;            // same as above (not using assignment operator)
  // Bits b1(0x14, 5);          // b1 = ---- ---- ---1 0100 (_Nbits = 5)
  //
  // Bits(unsigned long) allows automatic type conversion from "unsigned long"
  //   to "Bits" with _Nbits = MAX_BITS
  //
  if ((int) _Nbits > (int) MAX_BITS) {
    // throw out_of_range("Bits::Bits");
    // For now, clamp to MAX_BITS and let user check size to see if it worked.
    _Nbits = MAX_BITS;
    std::cerr << "THROW ERROR: out_of_range - Bits::Bits" << std::endl;
  } else {
      _sanitize();
  }
}

//------------------------------------------------------------------------

//
// Bits(0, ...) ambiguity problem between unsigned long and char
//   for input argument 0. To avoid this ambiguity, char* must be
//   replaced by string STL.
inline Bits::Bits (const std::string& str, size_t n_bits)
  : _Nbits(n_bits)
{
  // Constructor
  //
  // default args:
  //   size_t n_bits = MAX_BITS = sizeof(unsigned long)
  //
  // input args:
  //    unsigned char* str ---binary-format number, e.g, "0100 0111 0000 1010"
  //    size_t n_bits --- number of bits ( >= MAX_BITS )
  //
  // explicit: no implicit automatic conversion allowed from char* str to Bits;
  //   Bits(const char* str) must be explicitly used for the conversion
  //
  // Bits b1("");               // b1 = 0000 0000 0000 0000 (_Nbits = MAX_BITS)
  // Bits b2("01 0100");        // b1 = 0000 0000 0001 0100 (_Nbits = MAX_BITS)
  // Bits b2("01 0100", 5);     // b1 = ---- ---- ---1 0100 (_Nbits = 5)
  //
  if ((int) _Nbits > (int) MAX_BITS)
    // throw out_of_range("Bits::Bits");
    std::cerr << "THROW ERROR: out_of_range - Bits::Bits" << std::endl;

  _data = 0;    // clear all bits initially

  int i = 0;    // bit index

  // for (int j = strlen(str) - 1; j >= 0; j--) {
  for (int j = str.length() - 1; j >= 0; j--) {

    switch (str[j]) {
    case '0':
      i++;
      break;
    case '1':           // set bit[i] of _data = 1
      _data |= _maskbit(i);
      i++;
      break;
    case ' ':           // skip space
      break;
    default:
      // throw invalid_argument("Bits::Bits");
      std::cerr << "THROW ERROR: invalid_argument - Bits::Bits" << std::endl;
    }

    if (i >= (int) _Nbits) {                    // warning ??????
      std::cerr << "Warning: input data too large" << std::endl;
      break;
    }
  }
}

//
// Copy constructor
//

// Bits::Bits (const Bits&)
// {
  // Copy constructor
  //
  // Bits b2(b1);       // construct b2 and copy b1 into b2; copy _Nbits too
  // Bits b2 = b1;      // performs Bits b2(b1), not the Assignment operator
  //
  // func (Bits b1);    // passing a Bits object by value to func()
  // Bits b2 = func (); // returning a Bits object by value from func()
  //
  // use the compiler-synthesized default copy constructor --- it simply copies
  //   all data members from an existing object into the new object;
  //   it could be equivalently written as:
  //
  //   Bits::Bits (const Bits& b) : _data(b._data), _Nbits(b._Nbits) {}
// }
//------------------------------------------------------------------------


//
// Assignment operator
//

inline Bits& Bits::operator= (const Bits& rhs)
{
  // Assignment operator
  //
  // b2 = b1;           // copies _data, but not _Nbits; zeroes out unused bits
  // b2 = 0x14;         // first does automatic conversion using Bits(0x14)
  //
  // cannot not use the compiler-synthesized default assignment operator that
  //   copies both the _data and _Nbits member data; it is desirable to keep
  //   _Nbits unchanged and zero out the unused high-order bits accordingly;
  //   the idea is similar to the assignment statement that involves
  //   automatic type conversion (e.g., between char and int)
  //
  _data = rhs._data;
  _sanitize();          // zero out the unused high-order bits
  return *this;
}
//------------------------------------------------------------------------


//
// Destructor
//

// inline ~Bits()
// {
  // Destructor
  //
  // The only work needed is to destroy data members, and the system does
  //   the work automatically; Since there is no other work needed,
  //   use the compiler-synthesized "empty-body" default destructor, which
  //   is equivalently written as:
  //
  //   ~Bits() {}
// }
//------------------------------------------------------------------------


//
// index operator (subscript operator) --- b[i]
//
inline Bits::reference Bits::operator[](size_t pos)
{
  // single bit element access using b[i] used as lvalue
  // - it sets the member data  _bit_pos = pos first, and then
  //   returns an lvalue temporay object of type "reference" not "reference&"
  // - the returned temporary object together with the assigment operators
  //     Bits::reference& Bits::reference::operator=(const reference&) and
  //     Bits::reference& Bits::reference::operator=(bool)
  //   enables such statement as
  //     b[i] = b[j] = 1;
  //   After the execution, the i-th and j-th bits of b (a Bits object) are
  //   set to 1, and the temporary "reference" object created by b[i]
  //   dissappears.
  //
  return reference(*this, pos);
}
//------------------------------------------------------------------------

inline bool Bits::operator[](size_t pos) const
{
  // single bit element access using b[i]
  // - when returning a built-in type by value, it automatically implies
  //   a "const" return; it returns a value not a variable; namely,
  //   bool f() is the same as const bool f()
  // - the "const" return type cannot be a lvalue
  //
  return (_data & _maskbit(pos)) != 0;
}
//------------------------------------------------------------------------


//
// Bit manipulation operators --- &=, |=, ^=, <<=, >>= (compound-assignment ops)
// - the left operand is updated, and is returned by reference (Bits&)
// - self-reference --- returns the updated self object *this
//   by reference Bits&;
//
//   b1 &= b2;
//   b1 |= 0x14;        // first does the automatic conversion using Bits(0x14)
//   b1 ^= b2;
//   b1 <<= 2;
//   b1 >>= 3;
//

inline  Bits& Bits::operator&= (const Bits& rhs)
{
  // bitwise AND
  //
  _data &= rhs._data;           // _sanitize unnecessary
  return *this;
}
//------------------------------------------------------------------------

inline  Bits& Bits::operator|= (const Bits& rhs)
{
  // bitwise OR
  //
  _data |= rhs._data;
  _sanitize();
  return *this;
}
//------------------------------------------------------------------------

inline  Bits& Bits::operator^= (const Bits& rhs)
{
  // bitwise EXCLUSIVE-OR
  //
  _data ^= rhs._data;
  _sanitize();
  return *this;
}
//------------------------------------------------------------------------

inline  Bits& Bits::operator<<= (size_t n)
{
  // shift left: fill with zeros
  //
  _data <<= n;
  _sanitize();
  return *this;
}
//------------------------------------------------------------------------

inline  Bits& Bits::operator>>= (size_t n)
{
  // shift right: fill with zeros
  //
  _data >>= n;
  _sanitize();
  return *this;
}
//------------------------------------------------------------------------


//
// Bit manipulation functions --- set, clr, and toggle.
//
// self-reference --- returns the updated self object *this by reference
//   Bits& (not Bits); this enables chaining (concatenation) of functions,
//   for instance,
//
//   b1.set_bit(1).set_bit(3).clr_bit(4)
//
//   b1.set()           // b1 = ~0
//   b1.set_bit(3)      // b[3] = 1
//   b1.set_bits(2,3);  // b1[2] = b1[3] = b[4] = 1
//   b1.clr()           // b1 = 0
//   b1.clr_bit(3)      // b[3] = 0
//   b1.clr_bits(2,3)   // b1[2] = b1[3] = b[4] = 0
//   b1.toggle()        // b1 = ~b1
//   b1.toggle_bit(3)   // b[3] = ~b[3]
//
inline  Bits& Bits::set()
{
  // set every bit to 1
  //
  _data = ~static_cast<unsigned long>(0);
  _sanitize();
  return *this;
}
//------------------------------------------------------------------------

// Bits& Bits::set_bit(size_t pos, bool val = true)
inline  Bits& Bits::set_bit(size_t pos, bool val)
{
  // b[pos] = val; don't change other bits
  // default bool val = true; b[pos] = 1 (set to 1)
  //
  if (pos >= _Nbits)
    // throw out_of_range("Bits::set_bit");
    std::cerr << "Bits WARNING: out_of_range - Bits::set_bit" << std::endl;

  if (val)
    _data |= _maskbit(pos);
  else
    _data &= ~_maskbit(pos);

  return *this;
}
//------------------------------------------------------------------------

inline  Bits& Bits::set_bits(size_t pos, size_t n)
{
  // extension from STL bitset
  // b[pos] =  ... = b[pos+n-1] = 1; don't change other bits
  //
  if (pos + n > _Nbits)                 // + has precedence over >=
    // throw out_of_range("Bits::set_bits");
    std::cerr << "Bits WARNING: out_of_range - Bits::set_bits" << std::endl;

  _data |= _maskbits(pos, n);

  return *this;
}
//------------------------------------------------------------------------

inline  Bits& Bits::clr()
{
  // set every bit to 0 (clear all bits)
  //
  _data = 0;
  return *this;
}
//------------------------------------------------------------------------

inline  Bits& Bits::clr_bit(size_t pos)
{
  // b[pos] = 0 (clear one bit)
  //
  if (pos >= _Nbits)
    // throw out_of_range("Bits::clr_bit");
    std::cerr << "Bits WARNING: out_of_range - Bits::clr_bit" << std::endl;

  _data &= ~_maskbit(pos);

  return *this;
}
//------------------------------------------------------------------------

inline  Bits& Bits::clr_bits(size_t pos, size_t n)
{
  // extension from STL bitset
  // b[pos] =  ... = b[pos+n-1] = 0; don't change other bits
  //
  if (pos + n > _Nbits)         // + has precedence over >=
    // throw out_of_range("Bits::clr_bits");
    std::cerr << "Bits WARNING: out_of_range - Bits::clr_bits" << std::endl;

  _data &= ~_maskbits(pos, n);

  return *this;
}
//------------------------------------------------------------------------

inline  Bits& Bits::toggle()
{
  // change the value of every bit
  //
  _data = ~_data;
  _sanitize();

  return *this;
}
//------------------------------------------------------------------------

inline  Bits& Bits::toggle_bit(size_t pos)
{
  // change the value of b[pos]
  //
  if (pos >= _Nbits)
    // throw out_of_range("Bits::toggle_bit");
    std::cerr << "Bits WARNING: out_of_range - Bits::toggle_bit" << std::endl;

  _data ^= _maskbit(pos);
  return *this;
}
//------------------------------------------------------------------------

inline Bits& Bits::unchecked_set(unsigned long data)
{
  _data = data;                 // user must ensure data is sanitized
  // _sanitize();               // does not do data sanity check

  return *this;
}
//------------------------------------------------------------------------



//
// Access function
//
inline size_t Bits::size() const
{
  // get bit size
  //
  return _Nbits;                                // number of bits
}
//------------------------------------------------------------------------

// REPLACE WITH OPERATOR
// Type conversion
//
// named conversions are provided instead of conversion operators
//   to avoid conversion confusions between Bits and built-in types
//
inline unsigned long Bits::to_ulong() const
{
  // conversion to unsigned long
  //
  // unsigned long x = b1.to_ulong();
  // unsigned short y = b1.to_ulong();
  // unsigned char z = b1.to_ulong();
  // BYTE z = b1.to_ulong();                    // BYTE = unsigned char
  //
  return _data;
}
//------------------------------------------------------------------------


//
// Other operators:
// - evaluates the expression and retuns by value without changing
//   the original object
//

inline  bool Bits::operator==(const Bits& rhs) const
{
  // for b1==b2 and also for b1==0x14
  // compare _data only not _Nbits
  //
  return _data == rhs._data;
}
//------------------------------------------------------------------------

inline  bool Bits::operator!=(const Bits& rhs) const
{
  // for b1!=b2 and also for b1!=0x14
  // compare _data only not _Nbits
  //
  return _data != rhs._data;
}
//------------------------------------------------------------------------

inline bool
Bits::test(size_t pos) const
{
  // true if b[pos] is 1
  //
  if (pos >= _Nbits)
    // throw out_of_range("Bits::test");
    std::cerr << "THROW ERROR: out_of_range - Bits::test" << std::endl;

  return (_data & _maskbit(pos)) != 0;
}
//------------------------------------------------------------------------

inline bool
Bits::is_set(size_t pos) const
{
    return test(pos);
}
//------------------------------------------------------------------------

inline bool
Bits::get_bit(size_t pos) const
{
    return test(pos);
}
//------------------------------------------------------------------------

inline  bool Bits::any() const
{
  // true if any bit is 1
  //
  return _data != 0;
}
//------------------------------------------------------------------------

inline  bool Bits::none() const
{
  // true if no bit is 1
  //
  return _data == 0;
}
//------------------------------------------------------------------------

inline  Bits Bits::operator<<(size_t n) const
{
  // for return (b1<<3) and also for b2 = b1<<3; b1 unchanged
  // make a left-shifted copy without changing the original object (*this)
  // e.g., the statement b2 = b1 << 3 should not change b1.
  // returns the updated object by value (Bits), not by reference (Bits&)
  //
  return Bits(*this) <<= n;
}
//------------------------------------------------------------------------

inline  Bits Bits::operator>>(size_t n) const
{
  // for return (b1>>3) and also for b2 = b1>>3; b1 unchanged
  // make right-shifted set
  //
  return Bits(*this) >>= n;
}
//------------------------------------------------------------------------

inline  Bits Bits::operator~() const
{
  // for return (~b1) and also for b2 = ~b1; b1 unchanged
  // make complement set
  //
  return Bits(*this).toggle();
}
//------------------------------------------------------------------------


inline void Bits::_sanitize()
{
  // zero out the unused high-order bits
  //
  if (_Nbits != MAX_BITS)
    _data &= ~( ~static_cast<unsigned long>(0) << _Nbits );
}
//------------------------------------------------------------------------


//
//  non-member binary operator functions
//
// inline Bits operator&(const Bits& lhs, const Bits& rhs);
// inline Bits operator|(const Bits& lhs, const Bits& rhs);
// inline Bits operator^(const Bits&, const Bits&);
// ostream& operator<<(ostream& ostr, const Bits& rhs);
//

inline Bits operator&(const Bits& lhs, const Bits& rhs)
{
  Bits tmp = lhs;

  tmp &= rhs;
  return tmp;
}

inline Bits operator|(const Bits& lhs, const Bits& rhs)
{
  Bits tmp = lhs;

  tmp |= rhs;
  return tmp;
}

inline Bits operator^(const Bits& lhs, const Bits& rhs)
{
  Bits tmp = lhs;

  tmp ^= rhs;
  return tmp;
}
//-------------------------------------------------------------------------

//------------------------------------------------------------------------
//-------------------< Auto-Generated Operators >-------------------------
//------------------------------------------------------------------------
// - Need to uncomment and test on all rovers in order to have a complete set
//   of bit functionality - IAN
//#define CL_OP_TYPE Bits
//#define CL_OP_MODE CL_BITS_OP_MODE
//#include "claraty_opgen.h"

} // namespace claraty

#endif // __BITS_H

Last modified: June 05 2007 10:19:53

JPL PRIVACY STATEMENT GLOSSARY SITEMAP FEEDBACK CONTACT US

Site Manager: Issa A.D. Nesnas
Site Maintainer: Kelly Breed
Document Clearance #: CL 07-0635