Class MaskedLong
- All Implemented Interfaces:
Comparable<MaskedLong>
64
-bit value where each bit is 0
, 1
, or x
(undefined)-
Field Summary
Modifier and TypeFieldDescriptionprotected long
static final MaskedLong
static final MaskedLong
protected long
static final MaskedLong
-
Constructor Summary
ModifierConstructorDescriptionprotected
MaskedLong
(long msk, long val) Create a masked long given a mask and value -
Method Summary
Modifier and TypeMethodDescriptionadd
(MaskedLong that) Compute the arithmetic sum of this and another masked longboolean
agrees
(long that) Checks if this and a long agreeboolean
agrees
(MaskedLong that) Checks if this and another masked long agreeboolean
Check if this and another object agreeand
(MaskedLong that) Compute the bitwise AND of this and another masked longbyteSwap
(int n) Reverse the least significantn
bytescombine
(MaskedLong that) Combine this and another masked long into one, by taking defined bits from eitherint
compareTo
(MaskedLong that) "Compare" two masked longsdivideSigned
(MaskedLong that) divideUnsigned
(MaskedLong that) Compute the unsigned arithmetic quotient: this masked long divided by anotherboolean
Check for equalityfillMask()
Set all undefined bits to 0static MaskedLong
fromLong
(long val) Create a fully-defined value from the bits of a longstatic MaskedLong
fromMaskAndValue
(long msk, long val) Create a masked value from a mask and a longlong
getMask()
Get the mask as a longint
hashCode()
invAnd
(MaskedLong that) Solves the expressionA & B = C, for B, given C and A
Compute the arithmetic quotient as a solution to unsigned multiplicationinvOr
(MaskedLong that) Solves the expression A | B = C, for B, given C and AinvShiftLeft
(long n) Invert a left shift ofn
positions, that is shift rightInvert a left shift ofn
positions, that is shift rightinvShiftRight
(long n) Invert an arithmetic right shift ofn
positions, that is shift leftInvert an arithmetic right shift ofn
positions, that is shift leftinvShiftRightLogical
(long n) Invert a logical right shift ofn
positions, that is shift leftInvert a logical right shift ofn
positions, that is shift leftboolean
True iff there are no undefined bitsboolean
True iff there are no defined bitsboolean
isInRange
(long max, boolean signed) Check if the masked value falls within a given rangelong
Obtain the value as a long, where all undefined bits are treated as0
mask
(long mask) Apply an additional mask to this masked longmultiply
(MaskedLong that) Compute the arithmetic product of this and another masked longnegate()
Negate the valuenot()
Compute the bitwise NOTor
(MaskedLong that) Compute the bitwise OR of this and another masked longshiftCircular
(long n, int size, int dir) Shiftsize
bits @{code n) positions circularly in a given directionshiftCircular
(MaskedLong n, int size, int dir) Shiftsize
bits @{code n) positions circularly in a given directionshiftLeft
(long n) Shift the bits @{code n} positions leftShift the bitsn
positions leftshiftRight
(long n) Shift the bits arithmeticallyn
positions rightShift the bits arithmeticallyn
positions rightshiftRightLogical
(long n) Shift the bits logicallyn
positions rightShift the bits logicallyn
positions rightshiftRightPositional
(long n) Shift the bits positionallyn
positions rightSign extend the masked value, according to its mask, to a full longsignExtend
(int n) Sign extend the masked value as if of the given size in bits, to a full longprotected static long
signExtend
(long val, int bits) Sign extend a number of the given size in bits, to a full longsubtract
(MaskedLong that) Compute the arithmetic difference: this masked long minus anothertoString()
unknownExtend
(int n) Mask out all but the lowestn
bits of the valuexor
(MaskedLong that) Compute the bitwise XOR of this and another masked longZero extend the masked value, according to its mask, to a full longzeroExtend
(int n) Zero extend the masked value as if of the given size in bits, to a full longprotected static long
zeroExtend
(long val, int bits) Zero extend a number of the given size in bits, to a full long
-
Field Details
-
ZERO
-
UNKS
-
ONES
-
msk
protected long msk -
val
protected long val
-
-
Constructor Details
-
MaskedLong
protected MaskedLong(long msk, long val) Create a masked long given a mask and value
-
-
Method Details
-
fromMaskAndValue
Create a masked value from a mask and a longAny positions in
msk
set to 0 create anx
in the corresponding position of the result. Otherwise, the position takes the corresponding bit fromval
.- Parameters:
msk
- the maskval
- the value- Returns:
- the constructed masked long
-
fromLong
Create a fully-defined value from the bits of a long- Parameters:
val
- the value to take- Returns:
- the constructed masked long
-
longValue
public long longValue()Obtain the value as a long, where all undefined bits are treated as0
- Returns:
- the value as a long
-
getMask
public long getMask()Get the mask as a longPositions with a defined bit are
1
; positions with an undefined bit are0
.- Returns:
- the mask as a long
-
isFullyDefined
public boolean isFullyDefined()True iff there are no undefined bits- Returns:
- true if fully-defined, false otherwise
-
isFullyUndefined
public boolean isFullyUndefined()True iff there are no defined bits- Returns:
- true if full-undefined, false otherwise
-
mask
Apply an additional mask to this masked longAny
0
bit inmsk
will result in an undefined bit in the result.1
bits result in a copy of the corresponding bit in the result.- Parameters:
mask
- the mask to apply- Returns:
- the result.
-
signExtend
Sign extend the masked value, according to its mask, to a full longThe leftmost defined bit is taken as the sign bit, and extended to the left.
- Returns:
- the sign-extended masked long
-
zeroExtend
Zero extend the masked value, according to its mask, to a full longAll bits to the left of the leftmost defined bit are set to 0.
- Returns:
- the zero-extended masked long
-
unknownExtend
Mask out all but the lowestn
bits of the value- Parameters:
n
- the number of bits to take (right-to-left)- Returns:
- the unknown-extended masked long
-
signExtend
Sign extend the masked value as if of the given size in bits, to a full long- Parameters:
n
- the number of bits to take (right-to-left)- Returns:
- the sign-extended masked long
-
zeroExtend
Zero extend the masked value as if of the given size in bits, to a full long- Parameters:
n
- the number of bits to take (right-to-left)- Returns:
- the zero-extended masked long
-
combine
Combine this and another masked long into one, by taking defined bits from eitherIf this masked long agrees with the other, then the two are combined. For each bit position in the result, the defined bit from either corresponding position is taken. If neither is defined, then the position is undefined in the result. If both are defined, they must agree.
- Parameters:
that
- the other masked long- Returns:
- the combined masked long
- Throws:
SolverException
- if this and the other masked long disagree
-
shiftCircular
Shiftsize
bits @{code n) positions circularly in a given directionThe shifted bits are the least significant
size
bits. The remaining bits are unaffected.- Parameters:
n
- the number of positionssize
- the number of bits (least significant) to include in the shiftdir
- the direction to shift (0 for left, 1 for right)- Returns:
- the result
-
shiftCircular
Shiftsize
bits @{code n) positions circularly in a given directionThe shifted bits are the least significant
size
bits. The remaining bits are unaffected.- Parameters:
n
- the number of positionssize
- the number of bits (least significant) to include in the shiftdir
- the direction to shift (0 for left, 1 for right)- Returns:
- the result
-
shiftLeft
Shift the bits @{code n} positions leftThis implements both a signed and unsigned shift.
- Parameters:
n
- the number of positions.- Returns:
- the result.
-
shiftLeft
Shift the bitsn
positions leftThis implements both a signed and unsigned shift.
- Parameters:
n
- the number of positions.- Returns:
- the result.
-
invShiftLeft
Invert a left shift ofn
positions, that is shift rightThis is different from a normal shift right, in that it inserts unknowns at the left. The normal right shift inserts zeros or sign bits. Additionally, if any ones would fall off the right, the inversion is undefined.
- Parameters:
n
- the number of positions- Returns:
- the result
- Throws:
SolverException
- if the inversion is undefined
-
invShiftLeft
Invert a left shift ofn
positions, that is shift rightThis is different from a normal shift right, in that it inserts unknowns at the left. The normal right shift inserts zeros or sign bits. Additionally, if any ones would fall off the right, the inversion is undefined.
- Parameters:
n
- the number of positions- Returns:
- the result
- Throws:
SolverException
- if the inversion is undefined
-
shiftRight
Shift the bits arithmeticallyn
positions rightThis implements a signed shift.
- Parameters:
n
- the number of positions.- Returns:
- the result.
-
shiftRight
Shift the bits arithmeticallyn
positions rightThis implements a signed shift.
- Parameters:
n
- the number of positions.- Returns:
- the result.
-
invShiftRight
Invert an arithmetic right shift ofn
positions, that is shift leftThis is different from a normal shift left, in that it inserts unknowns at the right. The normal left shift inserts zeros. Additionally, all bits that fall off the left must match the resulting sign bit, or else the inversion is undefined.
- Parameters:
n
- the number of positions- Returns:
- the result
- Throws:
SolverException
- if the inversion is undefined
-
invShiftRight
Invert an arithmetic right shift ofn
positions, that is shift leftThis is different from a normal shift left, in that it inserts unknowns at the right. The normal left shift inserts zeros. Additionally, all bits that fall off the left must match the resulting sign bit, or else the inversion is undefined.
- Parameters:
n
- the number of positions- Returns:
- the result
- Throws:
SolverException
- if the inversion is undefined
-
shiftRightLogical
Shift the bits logicallyn
positions rightThis implements an unsigned shift.
- Parameters:
n
- the number of positions.- Returns:
- the result.
-
shiftRightLogical
Shift the bits logicallyn
positions rightThis implements an unsigned shift.
- Parameters:
n
- the number of positions.- Returns:
- the result.
-
shiftRightPositional
Shift the bits positionallyn
positions rightThis fills the left with unknown bits
- Parameters:
n
-- Returns:
-
invShiftRightLogical
Invert a logical right shift ofn
positions, that is shift leftThis is different from a normal shift left, in that it inserts unknowns at the right. The normal left shift inserts zeros. Additionally, if any ones would fall off the left, the inversion is undefined.
- Parameters:
n
- the number of positions- Returns:
- the result
- Throws:
SolverException
- if the inversion is undefined
-
invShiftRightLogical
Invert a logical right shift ofn
positions, that is shift leftThis is different from a normal shift left, in that it inserts unknowns at the right. The normal left shift inserts zeros. Additionally, if any ones would fall off the left, the inversion is undefined.
- Parameters:
n
- the number of positions- Returns:
- the result
- Throws:
SolverException
- if the inversion is undefined
-
byteSwap
Reverse the least significantn
bytesThis interprets the bits as an
n
-byte value and changes the endianness. Any bits outside of the interpretation are truncated, i.e., become unknown.- Parameters:
n
- the size, in bytes, of the interpreted value.- Returns:
- the result.
-
and
Compute the bitwise AND of this and another masked longTo handle unknown bits, the result is derived from the following truth table:
0 x 1 <= A (this) 0 0 0 0 x 0 x x 1 0 x 1 ^ B (that)
- Parameters:
that
- the other masked long (B
).- Returns:
- the result.
-
invAnd
Solves the expressionA & B = C, for B, given C and A
To handle unknown bits, the solution is derived from the following truth table, where
*
indicates no solution:0 x 1 <= A (that) 0 x x 0 x x x x 1 * 1 1 ^ B (this)
- Parameters:
that
- the other masked long (B
).- Returns:
- the result.
- Throws:
SolverException
- if no solution exists.
-
or
Compute the bitwise OR of this and another masked longTo handle unknown bits, the result is derived from the following truth table:
0 x 1 <= A (this) 0 0 x 1 x x x 1 1 1 1 1 ^ B (that)
- Parameters:
that
- the other masked long (B
).- Returns:
- the result.
-
invOr
Solves the expression A | B = C, for B, given C and ATo handle unknown bits, the solution is derived from the following truth table, where
*
indicates no solution:0 x 1 <= A (that) 0 0 0 * x x x x 1 1 x x ^ B (this)
- Parameters:
that
- the other masked long (B
).- Returns:
- the result.
- Throws:
SolverException
- if not solution exists.
-
xor
Compute the bitwise XOR of this and another masked longTo handle unknown bits, the result is derived from the following truth table:
0 x 1 <= A (this) 0 0 x 1 x x x x 1 1 x 0 ^ B (that)
- Parameters:
that
- the other masked long (B
).- Returns:
- the result.
-
negate
Negate the value- Returns:
- the result.
-
not
Compute the bitwise NOTTo handle unknown bits, the result is derived from the following truth table:
0 x 1 <= A (this) 1 x 0
- Returns:
- the result.
-
add
Compute the arithmetic sum of this and another masked long- Parameters:
that
- the other masked long.- Returns:
- the result.
-
subtract
Compute the arithmetic difference: this masked long minus another- Parameters:
that
- the other masked long.- Returns:
- the result.
-
multiply
Compute the arithmetic product of this and another masked long- Parameters:
that
- the other masked long.- Returns:
- the result.
-
divideSigned
-
divideUnsigned
Compute the unsigned arithmetic quotient: this masked long divided by another- Parameters:
that
- the other masked long.- Returns:
- the result.
-
invMultiplyUnsigned
Compute the arithmetic quotient as a solution to unsigned multiplicationThis is slightly different than
divideUnsigned(MaskedLong)
in its treatment of unknowns.- Parameters:
that
- the known factor- Returns:
- a solution to that*x == this, if possible
- Throws:
SolverException
-
agrees
Checks if this and another masked long agreeTwo masked longs agree iff their corresponding defined bit positions are equal. Where either or both positions are undefined, no check is applied. In the case that both masked longs are fully-defined, this is the same as an equality check on the values.
- Parameters:
that
- the other masked long.- Returns:
- true if this and that agree.
-
agrees
public boolean agrees(long that) Checks if this and a long agreeThe masked long agrees with the given long iff the masked long's defined bit positions agree with the corresponding bit positions in the given long. Where there are undefined bits, no check is applied. In the case that the masked long is fully-defined, this is the same as an equality check on the value.
- Parameters:
that
- the long- Returns:
- true if this and that agree.
-
agrees
Check if this and another object agree- Parameters:
that
- aMaskedLong
orLong
to check.- Returns:
- true if this and that agree.
- See Also:
-
isInRange
public boolean isInRange(long max, boolean signed) Check if the masked value falls within a given rangeThe range is defined by a maximum and a signedness. The maximum must be one less than a positive power of 2. In other words, it defines a maximum number of bits, including the sign bit if applicable.
The defined bits of this masked long are then checked to fall in the given range. The effective value is derived by sign/zero extending the value according to its mask. In general, if any
1
bits exist outside of the given max, the value is rejected, unless that1
is purely a result of signedness.- Parameters:
max
- the maximum value, taken as an unsigned long.signed
- true to interpret the masked value as signed.- Returns:
- true if the masked value "fits" into the given range.
-
compareTo
"Compare" two masked longsThis is not meant to reflect a numerical comparison. Rather, this is just to impose an ordering for the sake of storing these in sorted collections.
- Specified by:
compareTo
in interfaceComparable<MaskedLong>
-
equals
Check for equalityThis will only return true if the other object is a masked long, even if this one is fully-defined, and the value is equal to a given long (or
Long
). The other masked long must have the same mask and value to be considered equal. For other sorts of "equality" checks, seeagrees(Object)
and friends. -
hashCode
public int hashCode() -
toString
-
signExtend
protected static long signExtend(long val, int bits) Sign extend a number of the given size in bits, to a full long- Parameters:
val
- the value to extendbits
- the number of bits to take (right-to-left)- Returns:
- the sign-extended value as a long
-
zeroExtend
protected static long zeroExtend(long val, int bits) Zero extend a number of the given size in bits, to a full long- Parameters:
val
- the value to extendbits
- the number of bits to take (right-to-left)- Returns:
- the zero-extended value as a long
-
fillMask
Set all undefined bits to 0- Returns:
- the result
-