Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| Cryptix V3.2
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## cryptix.util.math
Class BigRegister

    java.lang.Object
      |
      +--cryptix.util.math.BigRegister

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
`static int` | `MAXIMUM_SIZE` Maximum allowed number of bits in a `BigRegister` object.

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

Method Summary
`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.

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`.

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| Cryptix V3.2
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright (C) 1995-2000 The Cryptix Foundation Ltd. All rights reserved.