cryptix.util.math

Class BigRegister

java.lang.Object

cryptix.util.math.BigRegister

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable

Direct Known Subclasses:

TrinomialLFSR

public class BigRegister
extends java.lang.Object
implements java.lang.Cloneable, java.io.Serializable

Utility class to manage a large bit-register of a given size as a mutable object.

The bits are indexed from 0 (rightmost) to size - 1, (leftmost) where size is this register's designated (at instantiation time) bit capacity.

Copyright © 1995-1997 Systemics Ltd on behalf of the Cryptix Development Team.
All rights reserved.

$Revision: 1.2 $

Author:

Raif S. Naffah

See Also:

Serialized Form

Field Summary

Fields

Modifier and Type	Field and Description
static int	MAXIMUM_SIZE Maximum allowed number of bits in a BigRegister object.

Constructor Summary

Constructors

Constructor and Description
BigRegister(int size) Instantiate a BigRegister of a given size with all its bits set to zeroes.

Method Summary

Modifier and Type	Method and Description
void	and(BigRegister source) Compute this &= source.
void	andNot(BigRegister source) Compute this &= ~source.
void	atRandom() Fill this BigRegister object with random data generated from the default source.
void	atRandom(java.security.SecureRandom source) Fill this BigRegister object with random data generated from a designated source.
int	byteValue() Return the rightmost byte value in this BigRegister.
void	clearBit(int n) Set the bit at the designated position to 0; ie.
java.lang.Object	clone() Return a reference to a duplicate of this.
int	compareTo(BigRegister x) Compare this BigRegister's contents to that of the argument, returning -1, 0 or 1 for less than, equal to, or greater than comparison result.
int	countSetBits() Return the number of bits set (to 1) in this.
void	flipBit(int n) Flip the value of the bit at the designated position.
int	getBit(int n) Return 1 or 0 if the designated bit was set or cleared respectively.
long	getBits(int n, int count) Return count bits starting at offset n framed in a long, right justified and left padded with binary zeroes.
int	getSize() Return the size of this object as specified at its instantiation time.
int	highestSetBit() Return the index of the leftmost non-zero bit in this.
int	intValue() Return the rightmost 32-bit value in this BigRegister as an int.
void	invertOrder() Invert the bit order of the current contents of this.
boolean	isSameValue(BigRegister x) Return true if the parameters of the BigRegister x (size and bits) are equal to this one; false otherwise.
void	load(BigRegister source) Copy the argument's value into this.
void	load(byte[] source) Copy the bit values from a byte array into this.
long	longValue() Return the rightmost 64-bit value in this BigRegister as a long.
int	lowestSetBit() Return the index of the rightmost non-zero bit in this.
void	not() Compute this = ~this.
void	or(BigRegister source) Compute this |= source.
void	reset() Reset to zeroes all this BigRegister's bits.
void	rotateLeft(int n) Circular left shift over the size of this register.
void	rotateRight(int n) Circular right shift over the size of this register.
void	setBit(int n) Set the bit at the designated position to 1.
void	setBits(int n, int count, long value) Set count bits starting at offset n to a given value.
void	shiftLeft(int n) Execute a left shift of this BigRegister's contents by a given number of bit positions.
void	shiftRight(int n) Execute a right shift of this BigRegister's contents by a given number of bit positions.
boolean	testBit(int n) Return true if the designated bit is set or false otherwise.
byte[]	toByteArray() Return a copy of this BigRegister's contents in a byte array with the LSB at index position 0.
java.lang.String	toString() Return a formatted String representation of the binary contents of this.
BigRegister	valueOf(long n) Return a BigRegister, of the same size as this set to the specified value.
void	xor(BigRegister source) Compute this ^= source.

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

MAXIMUM_SIZE

public static final int MAXIMUM_SIZE

Maximum allowed number of bits in a BigRegister object.

See Also:

Constant Field Values

Constructor Detail

BigRegister

public BigRegister(int size)

Instantiate a BigRegister of a given size with all its bits set to zeroes.

Parameters:

size - Number of meaningful bits in this object.

Throws:

java.lang.IllegalArgumentException - If the argument is less than 2 or greater than the maximum allowed value.

See Also:

MAXIMUM_SIZE

Method Detail

clone

public java.lang.Object clone()

Return a reference to a duplicate of this.

Overrides:

clone in class java.lang.Object

and

public void and(BigRegister source)

Compute this &= source.

Throws:

java.lang.IllegalArgumentException - If the argument is of different size than this.

andNot

public void andNot(BigRegister source)

Compute this &= ~source.

Throws:

java.lang.IllegalArgumentException - If the argument is of different size than this.

or

public void or(BigRegister source)

Compute this |= source.

Throws:

java.lang.IllegalArgumentException - If the argument is of different size than this.

not

public void not()

Compute this = ~this.

xor

public void xor(BigRegister source)

Compute this ^= source.

Throws:

java.lang.IllegalArgumentException - If the argument is of different size than this.

shiftLeft

public void shiftLeft(int n)

Execute a left shift of this BigRegister's contents by a given number of bit positions. If the number is negative, a right shift is executed.

Parameters:

n - Number of bit positions to shift by. If this value is negative then a shift in the opposite direction is executed.

shiftRight

public void shiftRight(int n)

Execute a right shift of this BigRegister's contents by a given number of bit positions. If the number is negative, a left shift is executed.

Parameters:

n - Number of bit positions to shift by. If this value is negative then a shift in the opposite direction is executed.

rotateLeft

public void rotateLeft(int n)

Circular left shift over the size of this register.

Effectively compute this = this << n | this >> (size - n).

If the number of positions to rotate by is negative, then a right instead of left rotation is executed.

rotateRight

public void rotateRight(int n)

Circular right shift over the size of this register.

Effectively compute this = this >> n | this << (size - n).

If the number of positions to rotate by is negative, then a left instead of right rotation is executed.

invertOrder

public void invertOrder()

Invert the bit order of the current contents of this.

testBit

public boolean testBit(int n)

Return true if the designated bit is set or false otherwise.

Parameters:

n - Index of the bit to test.

Returns:

true if the designated bit is set or false otherwise.

isSameValue

public boolean isSameValue(BigRegister x)

Return true if the parameters of the BigRegister x (size and bits) are equal to this one; false otherwise.

NOTE: the equals method is not used, because this is a mutable object (see the requirements for equals in the Java Language Spec).

Parameters:

x - BigRegister to test for equality.

Returns:

true iff x has equal size and contents.

compareTo

public int compareTo(BigRegister x)

Compare this BigRegister's contents to that of the argument, returning -1, 0 or 1 for less than, equal to, or greater than comparison result.

Parameters:

x - A BigRegister object to compare to.

Returns:

-1, 0, +1 If the contents of this object are respectively less than, equal to, or greater than those of the argument.

setBit

public void setBit(int n)

Set the bit at the designated position to 1.

Parameters:

n - The bit position to alter.

Throws:

java.lang.IllegalArgumentException - If the argument would cause an ArrayOutOfBOundsException while accessing the bits array.

setBits

public void setBits(int n,
                    int count,
                    long value)

Set count bits starting at offset n to a given value.

Parameters:

n - The index of the first bit to set.

count - Number of bits to set.

value - New bits value, right justified in a long.

Throws:

java.lang.IllegalArgumentException - If any of the arguments would cause an ArrayOutOfBOundsException while accessing the bits array, or count is < 1 or > 64.

clearBit

public void clearBit(int n)

Set the bit at the designated position to 0; ie. clear it.

Parameters:

n - The bit position to alter.

Throws:

java.lang.IllegalArgumentException - If the argument would cause an ArrayOutOfBOundsException while accessing the bits array.

flipBit

public void flipBit(int n)

Flip the value of the bit at the designated position.

Parameters:

n - The bit position to alter.

Throws:

java.lang.IllegalArgumentException - If the argument would cause an ArrayOutOfBOundsException while accessing the bits array.

getBit

public int getBit(int n)

Return 1 or 0 if the designated bit was set or cleared respectively.

Parameters:

n - The index of the bit to retrieve.

Throws:

java.lang.IllegalArgumentException - If the argument would cause an ArrayOutOfBOundsException while accessing the bits array.

getBits

public long getBits(int n,
                    int count)

Return count bits starting at offset n framed in a long, right justified and left padded with binary zeroes.

Parameters:

n - The index of the first bit to retrieve.

count - Number of bits to retrieve.

Returns:

Right justified count bits starting from bit index n in a java long.

Throws:

java.lang.IllegalArgumentException - If any of the arguments would cause an ArrayOutOfBOundsException while accessing the bits array, or count is < 1 or > 64.

byteValue

public int byteValue()

Return the rightmost byte value in this BigRegister.

Returns:

The rightmost byte value in this.

intValue

public int intValue()

Return the rightmost 32-bit value in this BigRegister as an int.

Returns:

The rightmost 32-bit value in this as an int.

longValue

public long longValue()

Return the rightmost 64-bit value in this BigRegister as a long.

Returns:

The rightmost 64-bit value in this as a long.

valueOf

public BigRegister valueOf(long n)

Return a BigRegister, of the same size as this set to the specified value.

Returns:

A BigRegister, of the same size as this set to the specified value.

reset

public void reset()

Reset to zeroes all this BigRegister's bits.

atRandom

public void atRandom()

Fill this BigRegister object with random data generated from the default source.

atRandom

public void atRandom(java.security.SecureRandom source)

Fill this BigRegister object with random data generated from a designated source.

load

public void load(BigRegister source)

Copy the argument's value into this.

Throws:

java.lang.IllegalArgumentException - If the argument is of different size than this.

load

public void load(byte[] source)

Copy the bit values from a byte array into this. Byte array order is assumed to have its Least Significant Byte (LSB) at index position 0. This format mirrors that of the output returned by the toByteArray() method.

Bits unprovided for in the source array are cleared. It is a more tolerant way of initialising a register than that obtained by invoking the same method with a BigRegister argument.

Parameters:

source - The source bits organised in a byte array with their LSB at index 0.

Throws:

java.lang.IllegalArgumentException - If the argument is of greater size than this.

See Also:

toByteArray()

toByteArray

public byte[] toByteArray()

Return a copy of this BigRegister's contents in a byte array with the LSB at index position 0. This format is compatible with the load([B) method of this class.

Returns:

The bits of this in a byte array with the LSB at index position 0.

getSize

public int getSize()

Return the size of this object as specified at its instantiation time.

Returns:

The size of this object as specified at its instantiation time.

countSetBits

public int countSetBits()

Return the number of bits set (to 1) in this.

Returns:

The number of set bits in this.

highestSetBit

public int highestSetBit()

Return the index of the leftmost non-zero bit in this.

Returns:

Index of the leftmost non-zero bit in this, or -1 if all bits are zeroes.

lowestSetBit

public int lowestSetBit()

Return the index of the rightmost non-zero bit in this.

Returns:

Index of the rightmost non-zero bit in this, or -1 if all bits are zeroes.

toString

public java.lang.String toString()

Return a formatted String representation of the binary contents of this.

Overrides:

toString in class java.lang.Object

Returns:

A formatted string representation of the binary contents of this.