public class BitVector
extends java.lang.Object
Bits can be in the invalid, true, or
false state. The string representations for these values are "
-", "1", and "0", respectively. To help
catch bugs, bits are invalid (i.e., undefined or unknown) until
they have been explicitly set and BitVector
methods crash if
you attempt to read an invalid bit. Here are some examples to
indicate how BitVector values are represented and used:
Bit representation | BitVector example | ||
---|---|---|---|
example 1 | example 2 | example 3 | |
String | 011 | 1-01 | 1000000000 |
BigInteger | 3 | undefined | 512 |
"LittleInteger" | 6 | undefined | 1 |
BitVector state at index 0,1,2,... | false,true,true | true,invalid,false,true | true,false,false,... |
bits scanned into scan chain | 1,1,0 | undefined | 0,0,0,0,0,0,0,0,0,1 |
chain element states along s_in | 0,1,1 | undefined | 1,0,0,0,0,0,0,0,0,0 |
Bit zero is the LAST bit scanned into the scan chain. Thus the bit index
matches the position of the corresponding scan chain element along the s_in
chain. BitVector
uses the big endian bit order convention for
the String representation. Strings should be read from left to right,
starting at bit zero. Thus the strings match the order in which scan chain
elements appear in most schematics. The MSB of a BigInteger
or
int
is stored in bit 0 of the BitVector
. That
is, the bit order is opposite to that of the integer.
Key differences from BitSet
: 1) addition of the invalid
state; 2) the bit vector is fixed length; 3) ranges are specified by
(startIndex, numBits) rather than (startIndex, endIndex); 4) different
toString() method; addition of BigInteger I/O methods.
Modifier and Type | Field and Description |
---|---|
static int |
noNameSeverity
Severity of action when an unnamed BitVector is created.
|
Constructor and Description |
---|
BitVector(BitVector b)
Convenience constructor copies contents of existing BitVector
|
BitVector(int numBits)
Deprecated.
|
BitVector(int[] bitArray,
java.lang.String name)
Convenience constructor creates a bit vector from the input string.
|
BitVector(int numBits,
java.lang.String name)
Main constructor creates a vector of
numBits bits, set to
the invalid state. |
BitVector(java.lang.String bitString)
Deprecated.
|
BitVector(java.lang.String bitString,
java.lang.String name)
Convenience constructor creates a bit vector from the input string.
|
Modifier and Type | Method and Description |
---|---|
BitVector |
add(BitVector bv)
Sign extend the shorter operand to the length of the longer
longer operand.
|
BitVector |
and(BitVector b)
Logical AND this BitVector with b.
|
BitVector |
bitReverse()
Return a new BitVector that is the bit reverse of the
bits in this BitVector.
|
int |
cardinality()
Returns the number of bits set to true in this
BitVector . |
BitVector |
cat(BitVector b)
Generate concatenation of bit vectors.
|
void |
clear(int bitIndex)
Sets the bit specified by the index to false.
|
boolean |
equals(java.lang.Object o)
Compare BitVectors.
|
boolean |
equalsLong(long v)
sign extend shorter operand to length of longer operand.
|
void |
flip(int bitIndex)
Sets the bit at the specified index to to the complement of its current
value.
|
void |
flip(int fromIndex,
int nbits)
Sets the bits in the specified index range to to the complements of their
current values.
|
boolean |
get(int bitIndex)
Returns the value of the bit with the specified index.
|
BitVector |
get(int fromIndex,
int nbits)
Returns a new
BitVector composed of a subset of
numBits bits from this BitVector . |
BitVector |
getIndiscriminate(int fromIndex,
int nbits)
Like
get(int, int) , but the range is allowed to include invalid
bits. |
java.lang.String |
getName()
Returns the name of the bit vector.
|
int |
getNumBits()
Returns number of bits in the bit vector
|
java.lang.String |
getState()
Returns a string representation of the entire bit sequence, starting with
the lowest-index bit.
|
int |
hashCode() |
void |
invalidate()
Sets the entire bit vector to the invalid state.
|
void |
invalidate(int bitIndex)
Sets the bit specified by the index to the invalid state.
|
boolean |
isEmpty()
Returns true if this
BitSet contains only bits
that are false. |
boolean |
isInvalid()
Returns true if all of the bits in this
BitSet
are in the invalid state. |
boolean |
isValid(int bitIndex)
Returns true if specified bit has a known state.
|
static void |
main(java.lang.String[] args)
Unit test, sets and prints some bit vectors.
|
BitVector |
not()
Generate the complement all bits
|
void |
put(int fromIndex,
BitVector source)
Copies the source bit vector into the receiver, starting at index
fromIndex . |
void |
put(int fromIndex,
int[] array)
Sets bits in bit vector according to an
int[] , starting at bit index fromIndex . |
void |
put(int fromIndex,
int nbits,
java.math.BigInteger inp)
Sets
nbits bits in bit vector according to the bit
sequence in a BigInteger , starting at bit index
fromIndex . |
void |
put(int fromIndex,
java.lang.String inp)
Sets bits in bit vector according to a big endian input
String , starting at bit index fromIndex . |
void |
putIndiscriminate(int fromIndex,
BitVector source)
Like
put(int, BitVector) , but the source bit vector is allowed
to have invalid bits. |
void |
putLittle(int fromIndex,
int nbits,
java.math.BigInteger inp)
Sets
nbits bits in bit vector according to the bit
sequence in a BigInteger , starting at bit index
fromIndex . |
BitVector |
rotateLeft(int amountToRotate)
Return a new BitVector that consists of the
bits in this BitVector rotated left.
|
BitVector |
rotateRight(int amountToRotate)
Return a new BitVector that consists of the
bits in this BitVector rotated right.
|
void |
set(int bitIndex)
Sets the bit at the specified index to true.
|
void |
set(int bitIndex,
boolean value)
Sets the bit at the specified index to the specified value.
|
void |
set(int fromIndex,
int nbits,
boolean value)
Sets the
nbits bits starting at fromIndex
(inclusive) to the specified value. |
void |
setFromBigInteger(java.math.BigInteger bigValue)
Set the value of BitVector from a BigInteger.
|
void |
setFromLong(long longValue)
Set the value of BitVector from an long value.
|
void |
setName(java.lang.String name)
Set the name of the bit vector.
|
BitVector |
shiftRight(int n)
Shift right, filling with sign bit
|
BitVector |
subtract(BitVector bv)
Sign extend the shorter operand to the length of the longer
longer operand.
|
java.math.BigInteger |
toBigInteger()
Returns a
BigInteger representation of the entire bit
vector, with bit 0 in the MSB. |
int[] |
toIntArray()
Returns an
int array representation of the entire bit
vector. |
java.math.BigInteger |
toLittleInteger()
Returns a
BigInteger representation of the entire bit
vector, with bit 0 in the LSB. |
long |
toLong()
convert to long.
|
java.lang.String |
toString()
Returns the name and the bit vector and a string representing the entire
bit sequence, starting with the lowest-index bit.
|
public static int noNameSeverity
Infrastructure.SEVERITY_WARNING
public BitVector(int numBits)
numBits
bits, set to the invalid state.numBits
- number of bits in the vectorpublic BitVector(int numBits, java.lang.String name)
numBits
bits, set to
the invalid state.numBits
- number of bits in the vectorname
- identifying name of the bit vector, e.g. for errorspublic BitVector(java.lang.String bitString)
bitString
- bit sequence to initialize vector topublic BitVector(java.lang.String bitString, java.lang.String name)
bitString
- bit sequence to initialize vector toname
- identifying name of the bit vector, e.g. for errorspublic BitVector(BitVector b)
b
- BitVector to copypublic BitVector(int[] bitArray, java.lang.String name)
bitArray
- bit sequence to initialize vector toname
- identifying name of the bit vector, e.g. for errorspublic int getNumBits()
public java.lang.String getName()
public void setName(java.lang.String name)
name
- The name to set.public java.lang.String getState()
public java.lang.String toString()
toString
in class java.lang.Object
public java.math.BigInteger toBigInteger()
BigInteger
representation of the entire bit
vector, with bit 0 in the MSB.BigInteger
representation of bit sequencepublic java.math.BigInteger toLittleInteger()
BigInteger
representation of the entire bit
vector, with bit 0 in the LSB. Compare to toBigInteger().BigInteger
representation of bit sequencetoBigInteger()
public int[] toIntArray()
int
array representation of the entire bit
vector. Values in the array are either 0, 1, or -1 for false, true, and
undefined, respectively.public boolean isValid(int bitIndex)
bitIndex
- index of bit to be checkedpublic void invalidate(int bitIndex)
bitIndex
- the index of the bit to be invalidatedpublic void invalidate()
public boolean get(int bitIndex)
bitIndex
is
currently set in this BitVector
; otherwise, the result is
false.bitIndex
- the bit indexpublic void flip(int bitIndex)
bitIndex
- the index of the bit to flippublic void flip(int fromIndex, int nbits)
fromIndex
- the starting index of the bits to flipnbits
- the number of bits to flippublic void clear(int bitIndex)
bitIndex
- the index of the bit to be clearedpublic void set(int bitIndex)
bitIndex
- a bit indexpublic void set(int bitIndex, boolean value)
bitIndex
- a bit index.value
- a boolean value to setpublic void set(int fromIndex, int nbits, boolean value)
nbits
bits starting at fromIndex
(inclusive) to the specified value.fromIndex
- index of the first bit to be setnbits
- number of bits to setvalue
- value to set the selected bits topublic BitVector get(int fromIndex, int nbits)
BitVector
composed of a subset of
numBits
bits from this BitVector
. Range is
from fromIndex
(inclusive) to
(toIndex + nbits)
(exclusive). Note this interface is
different from that of BitSet.get()
. The range is not
allowed to include any invalid bits.fromIndex
- index of the first bit to includenbits
- number of bits to includepublic BitVector getIndiscriminate(int fromIndex, int nbits)
get(int, int)
, but the range is allowed to include invalid
bits.fromIndex
- index of the first bit to includenbits
- number of bits to includepublic void put(int fromIndex, BitVector source)
fromIndex
. If the source bit vector does not extend to
the end of the receiver, the high-index bits will not be modified. The
source bit vector is required to contain no invalid bits.fromIndex
- starting indexsource
- source bitspublic void putIndiscriminate(int fromIndex, BitVector source)
put(int, BitVector)
, but the source bit vector is allowed
to have invalid bits.fromIndex
- starting indexsource
- source bitspublic void put(int fromIndex, java.lang.String inp)
String
, starting at bit index fromIndex
.
If the string does not extend to the end of the bit vector, the
high-index bits will not be modified.fromIndex
- index of the first bit to be setinp
- new bit values (e.g., "10101")public void put(int fromIndex, int[] array)
int[]
, starting at bit index fromIndex
.
If the array does not extend to the end of the bit vector, the
high-index bits will not be modified. The array must
be an array of 1's and 0's (1 for true, 0 for false).fromIndex
- index of the first bit to be setarray
- new bit valuespublic void put(int fromIndex, int nbits, java.math.BigInteger inp)
nbits
bits in bit vector according to the bit
sequence in a BigInteger
, starting at bit index
fromIndex
. The integer's bit sequence is reversed upon
storage.fromIndex
- index of the first bit to be setnbits
- number of bits to setinp
- number containing new bit values in reverse orderpublic void putLittle(int fromIndex, int nbits, java.math.BigInteger inp)
nbits
bits in bit vector according to the bit
sequence in a BigInteger
, starting at bit index
fromIndex
.fromIndex
- index of the first bit to be setnbits
- number of bits to setinp
- number containing new bit values in reverse orderpublic int cardinality()
BitVector
.BitVector
.public boolean isEmpty()
BitSet
contains only bits
that are false.BitSet
is empty.public boolean isInvalid()
BitSet
are in the invalid state.BitSet
is completely invalid.public boolean equals(java.lang.Object o)
equals
in class java.lang.Object
public int hashCode()
hashCode
in class java.lang.Object
public BitVector cat(BitVector b)
public BitVector not()
public BitVector and(BitVector b)
b
- second operandpublic BitVector bitReverse()
public void setFromLong(long longValue)
public void setFromBigInteger(java.math.BigInteger bigValue)
public BitVector add(BitVector bv)
public BitVector subtract(BitVector bv)
public BitVector shiftRight(int n)
public long toLong()
public boolean equalsLong(long v)
public BitVector rotateLeft(int amountToRotate)
amountToRotate
- number of bit positions to rotatepublic BitVector rotateRight(int amountToRotate)
amountToRotate
- number of bit positions to rotatepublic static void main(java.lang.String[] args)
BitVector b1
to. If
args[1] is prsent, it is the string to set BitVector b2
to. Otherwise default values of "1101" and "1001" are used.