esi::BitVector Class Reference

A lightweight, non-owning bit vector view backed by a byte array span. More...

#include <Values.h>

Inheritance diagram for esi::BitVector:

Collaboration diagram for esi::BitVector:

Classes
class	bit_iterator
	Forward iterator for iterating over bits from LSB (index 0) to MSB. More...

Public Types
using	byte = uint8_t

Public Member Functions
	BitVector (std::span< const byte > bytes, std::optional< size_t > width=std::nullopt, uint8_t bitIndex=0)
	Construct from an existing span.
	BitVector ()=default
	BitVector (const BitVector &other)
BitVector &	operator= (const BitVector &other)
size_t	width () const
size_t	size () const
bool	getBit (size_t i) const
	Return the i-th bit (0 = LSB) as boolean.
std::span< const byte >	getSpan () const
	Return a handle to the underlying span.
BitVector	operator>> (size_t n) const
	Logical right shift that drops the least-significant n bits by advancing the byte/bit index and reducing width.
BitVector &	operator>>= (size_t n)
BitVector	slice (size_t offset, size_t sliceWidth) const
	Create a new immutable view of a contiguous bit slice [offset, offset+sliceWidth).
BitVector	lsb (size_t n) const
	Return a view of the N least-significant bits.
BitVector	msb (size_t n) const
	Return a view of the N most-significant bits.
std::string	toString (unsigned base=16) const
bool	operator== (const BitVector &rhs) const
bool	operator!= (const BitVector &rhs) const
bit_iterator	begin () const
	Return an iterator to the first bit (LSB).
bit_iterator	end () const
	Return an iterator past the last bit.

Protected Member Functions
void	checkHighBytesEqual (unsigned lowExclusive, uint8_t expectedByte, const char *fmt, unsigned target) const

Protected Attributes
std::span< const byte >	data {}
size_t	bitWidth = 0
uint8_t	bitIndex = 0

Friends
MutableBitVector	operator& (const BitVector &a, const BitVector &b)
	Bitwise AND: creates a new MutableBitVector with the result.
MutableBitVector	operator| (const BitVector &a, const BitVector &b)
	Bitwise OR: creates a new MutableBitVector with the result.
MutableBitVector	operator^ (const BitVector &a, const BitVector &b)
	Bitwise XOR: creates a new MutableBitVector with the result.

Detailed Description

A lightweight, non-owning bit vector view backed by a byte array span.

BitVector is immutable wrt. modifying the underlying bits, and provides read-only access to bits. It supports bit-level access and returns new views for operations.

Lifetime: BitVector, IntView, and UIntView (defined just below) are non-owning views, in the same family as std::span / std::string_view. They store only a span pointer + width + bitIndex and do not extend the lifetime of the underlying buffer. A view returned from an accessor of a temporary dangles once the temporary is destroyed; bind the parent to a named local, or construct an owning Int / UInt / MutableBitVector from the view if the value needs to outlive its source.

Definition at line 51 of file Values.h.

Member Typedef Documentation

byte

using esi::BitVector::byte = uint8_t

Definition at line 53 of file Values.h.

Constructor & Destructor Documentation

BitVector() [1/3]

BitVector::BitVector	(	std::span< const byte >	bytes,
		std::optional< size_t >	width = std::nullopt,
		uint8_t	bitIndex = 0 )

Construct from an existing span.

Width defaults to the number of bits in the span (size * 8). The BitVector does not take ownership.

Definition at line 16 of file Values.cpp.

References bitIndex, bitWidth, data, size(), and width().

Referenced by esi::BitVector::bit_iterator::bit_iterator(), BitVector(), BitVector(), lsb(), msb(), esi::MutableBitVector::MutableBitVector(), esi::MutableBitVector::MutableBitVector(), esi::MutableBitVector::MutableBitVector(), esi::MutableBitVector::MutableBitVector(), esi::MutableBitVector::MutableBitVector(), operator!=(), operator&, esi::MutableBitVector::operator&(), operator=(), operator==(), operator>>(), operator>>=(), operator^, esi::MutableBitVector::operator^(), operator|, esi::MutableBitVector::operator|(), and slice().

BitVector() [2/3]

esi::BitVector::BitVector ( )

default

References BitVector().

BitVector() [3/3]

BitVector::BitVector

(

const BitVector &

other

)

Definition at line 29 of file Values.cpp.

References bitIndex, BitVector(), bitWidth, and data.

Member Function Documentation

begin()

bit_iterator esi::BitVector::begin ( ) const

inline

Return an iterator to the first bit (LSB).

Definition at line 180 of file Values.h.

checkHighBytesEqual()

void BitVector::checkHighBytesEqual ( unsigned lowExclusive, uint8_t expectedByte, const char * fmt, unsigned target ) const

protected

Definition at line 437 of file Values.cpp.

References bitIndex, bitWidth, and data.

Referenced by esi::IntView::toI64(), esi::IntView::toInt(), esi::UIntView::toUI64(), and esi::UIntView::toUInt().

end()

bit_iterator esi::BitVector::end ( ) const

inline

Return an iterator past the last bit.

Definition at line 183 of file Values.h.

References bitWidth.

getBit()

bool BitVector::getBit

(

size_t

i

)

const

Return the i-th bit (0 = LSB) as boolean.

Definition at line 41 of file Values.cpp.

References bitIndex, bitWidth, and data.

Referenced by esi::MutableBitVector::MutableBitVector(), esi::MutableBitVector::operator&=(), esi::MutableBitVector::operator<<=(), esi::MutableBitVector::operator<<=(), esi::MutableBitVector::operator^=(), esi::MutableBitVector::operator|=(), esi::MutableBitVector::operator~(), toDecimalString(), esi::IntView::toI64(), esi::IntView::toInt(), toString(), and esi::UIntView::toUI64().

getSpan()

std::span< const byte > esi::BitVector::getSpan ( ) const

inline

Return a handle to the underlying span.

Throws if the current bit index is not 0 (since a non-zero bit offset breaks raw byte alignment).

Definition at line 71 of file Values.h.

References bitIndex, and data.

lsb()

BitVector esi::BitVector::lsb ( size_t n ) const

inline

Return a view of the N least-significant bits.

Definition at line 90 of file Values.h.

References BitVector(), and slice().

Referenced by esi::UnionType::deserialize().

msb()

BitVector esi::BitVector::msb ( size_t n ) const

inline

Return a view of the N most-significant bits.

Definition at line 93 of file Values.h.

References BitVector(), bitWidth, and slice().

operator!=()

bool esi::BitVector::operator!= ( const BitVector & rhs ) const

inline

Definition at line 102 of file Values.h.

References BitVector().

operator=()

BitVector & BitVector::operator=

(

const BitVector &

other

)

Definition at line 32 of file Values.cpp.

References bitIndex, BitVector(), bitWidth, and data.

operator==()

bool BitVector::operator==

(

const BitVector &

rhs

)

const

Definition at line 420 of file Values.cpp.

References BitVector(), and bitWidth.

operator>>()

BitVector BitVector::operator>>

(

size_t

n

)

const

Logical right shift that drops the least-significant n bits by advancing the byte/bit index and reducing width.

Returns a new immutable view. Does not modify the underlying storage contents.

Definition at line 50 of file Values.cpp.

References BitVector(), bitWidth, and empty.

operator>>=()

BitVector & BitVector::operator>>=

(

size_t

n

)

Definition at line 78 of file Values.cpp.

References BitVector().

size()

size_t esi::BitVector::size ( ) const

inline

Definition at line 64 of file Values.h.

References width().

Referenced by BitVector().

slice()

BitVector BitVector::slice	(	size_t	offset,
		size_t	sliceWidth ) const

Create a new immutable view of a contiguous bit slice [offset, offset+sliceWidth).

The returned BitVector is a view (not an owning copy) into the same underlying span. Throws if the requested slice exceeds the current width.

Definition at line 83 of file Values.cpp.

References bitIndex, BitVector(), bitWidth, and data.

Referenced by lsb(), and msb().

toString()

std::string BitVector::toString

(

unsigned

base = 16

)

const

Definition at line 362 of file Values.cpp.

References bitWidth, getBit(), toDecimalString(), and toPowerOfTwoString().

Referenced by esi::operator<<().

width()

size_t esi::BitVector::width ( ) const

inline

Definition at line 63 of file Values.h.

References bitWidth.

Referenced by BitVector(), esi::Int::Int(), esi::Int::Int(), esi::Int::MutableBitVector(), esi::MutableBitVector::MutableBitVector(), esi::MutableBitVector::MutableBitVector(), esi::MutableBitVector::MutableBitVector(), esi::MutableBitVector::MutableBitVector(), esi::MutableBitVector::operator<<=(), esi::SIntType::serialize(), esi::StructType::serialize(), esi::UIntType::serialize(), size(), toDecimalString(), esi::IntView::toInt(), esi::UIntView::toUInt(), esi::UInt::UInt(), and esi::UInt::UInt().

Friends And Related Symbol Documentation

operator&

MutableBitVector operator& ( const BitVector & a, const BitVector & b )

friend

Bitwise AND: creates a new MutableBitVector with the result.

References BitVector().

operator^

MutableBitVector operator^ ( const BitVector & a, const BitVector & b )

friend

Bitwise XOR: creates a new MutableBitVector with the result.

References BitVector().

operator|

MutableBitVector operator| ( const BitVector & a, const BitVector & b )

friend

Bitwise OR: creates a new MutableBitVector with the result.

References BitVector().

Member Data Documentation

bitIndex

uint8_t esi::BitVector::bitIndex = 0

protected

Definition at line 189 of file Values.h.

Referenced by BitVector(), BitVector(), esi::UIntView::BitVector(), checkHighBytesEqual(), getBit(), getSpan(), esi::MutableBitVector::MutableBitVector(), esi::MutableBitVector::MutableBitVector(), esi::MutableBitVector::MutableBitVector(), esi::MutableBitVector::MutableBitVector(), esi::MutableBitVector::MutableBitVector(), esi::MutableBitVector::MutableBitVector(), esi::MutableBitVector::operator<<=(), esi::MutableBitVector::operator<<=(), operator=(), esi::MutableBitVector::operator=(), esi::MutableBitVector::operator=(), esi::MutableBitVector::operator>>=(), and slice().

bitWidth

size_t esi::BitVector::bitWidth = 0

protected

Definition at line 188 of file Values.h.

Referenced by BitVector(), BitVector(), checkHighBytesEqual(), end(), getBit(), msb(), esi::MutableBitVector::MutableBitVector(), esi::MutableBitVector::MutableBitVector(), esi::MutableBitVector::MutableBitVector(), esi::MutableBitVector::MutableBitVector(), esi::MutableBitVector::MutableBitVector(), esi::MutableBitVector::MutableBitVector(), esi::MutableBitVector::operator&=(), esi::MutableBitVector::operator<<=(), esi::MutableBitVector::operator<<=(), operator=(), esi::MutableBitVector::operator=(), esi::MutableBitVector::operator=(), operator==(), operator>>(), esi::MutableBitVector::operator>>=(), esi::MutableBitVector::operator^=(), esi::MutableBitVector::operator|=(), esi::MutableBitVector::operator~(), esi::MutableBitVector::setBit(), slice(), esi::IntView::toI64(), toString(), esi::UIntView::toUI64(), and width().

data

std::span<const byte> esi::BitVector::data {}

protected

Definition at line 187 of file Values.h.

Referenced by BitVector(), BitVector(), esi::UIntView::BitVector(), checkHighBytesEqual(), tests.integration.test_hostmem_read._Dut::expected(), getBit(), getSpan(), esi::MutableBitVector::getSpan(), esi::MutableBitVector::MutableBitVector(), esi::MutableBitVector::MutableBitVector(), esi::MutableBitVector::MutableBitVector(), esi::MutableBitVector::MutableBitVector(), esi::MutableBitVector::MutableBitVector(), esi::MutableBitVector::MutableBitVector(), esi::MutableBitVector::operator<<=(), esi::MutableBitVector::operator<<=(), operator=(), esi::MutableBitVector::operator=(), esi::MutableBitVector::operator=(), esi::MutableBitVector::operator>>=(), and slice().

---

The documentation for this class was generated from the following files:

• /home/runner/work/circt-www/circt-www/circt_src/lib/Dialect/ESI/runtime/cpp/include/esi/Values.h
• /home/runner/work/circt-www/circt-www/circt_src/lib/Dialect/ESI/runtime/cpp/lib/Values.cpp