Sharkysoft home

lava.array
Class ByteArray32

java.lang.Object
  |
  +--lava.array.ByteArray32

public final class ByteArray32
extends java.lang.Object

232-entry virtual byte array.

Details: A ByteArray32 is an array of 232 bytes. Every element in the array is available for reading and writing.

Because very few computing environments are equipped to handle physically allocated arrays of this size, ByteArray32 uses an on-demand page allocation scheme where only the dirty pages are actually allocated. In other words, segments of the "4 billion byte array" are allocated only as needed. These segments are allocated in aligned 256-byte chunks. All 4 billion members of the array are "virtually initialized" with a default value at construction time.

ByteArray32 is ideal for applications that require large, sparsely-populated byte arrays where the offsets of the values that are populated tend to cluster in contiguous or nearly contiguous groups. ByteArray32 is efficient because it never requires array resizing, array copying, or address hashing (unlike a growable Vector- or Hashtable-based implementation). ByteArray32 also permits a sequential enumeration of occupied memory cells (unlike a Hashtable, which does not produce sequential output).

Array indices for this "virtual byte array" are specified using unsigned ints. Byte elements can be accessed 1 byte or 4 bytes at a time. When 4 bytes are accessed simultaneously, the values are combined into a single int structure. Indices used to access 4 bytes at a time are automatically aligned (ANDed with 0xfffffffc).

Since:
a long time ago
Version:
1999.09.13
Author:
Sharky

Constructor Summary
ByteArray32(byte default_byte)
          Initializes with default value.
 
Method Summary
 int compact()
          Reduces storage requirements.
 void fill(int index, int amount, byte value)
          Fills array.
 byte get(int index)
          Retrieves byte.
 void get(int index, byte[] dest, int dest_from, int amount)
          Retrieves bytes.
 int getIntBe(int index)
          Retrieves 32-bit word.
 int getIntLe(int index)
          Retrieves 32-bit word.
 long search(int index, int amount, byte value)
          Searches for value.
 void set(int index, byte value)
          Sets byte.
 void set(int index, byte[] src, int src_from, int amount)
          Sets bytes.
 void setIntBe(int index, int value)
          Sets 32-bit word.
 void setIntLe(int index, int value)
          Sets 32-bit word.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

ByteArray32

public ByteArray32(byte default_byte)
Initializes with default value.

Details: This constructor initializes a new ByteArray32 with all bytes set to the given initial value (default_byte).

Parameters:
default_byte - the initial value
Method Detail

get

public byte get(int index)
Retrieves byte.

Details: get returns the byte at the given address (index).

Parameters:
index - (unsigned) the address
Returns:
the byte

set

public void set(int index,
                byte value)
Sets byte.

Details: set sets the byte at the given address (index) to the given value (value).

Parameters:
index - (unsigned) the address
value - the value

get

public void get(int index,
                byte[] dest,
                int dest_from,
                int amount)
Retrieves bytes.

Details: get retrieves the given range of bytes (index, amount) and writes them into the destination array (dest).

Parameters:
index - (unsigned) the address
dest - the destination array
dest_from - index of first byte in dest
amount - number of bytes to retrieve

set

public void set(int index,
                byte[] src,
                int src_from,
                int amount)
Sets bytes.

Details: set writes the given sequence of bytes (src, src_from, amount) into this array, starting at the given address (index).

Parameters:
index - the address
src - the byte sequence
src_from - index of first byte in src
amount - number of bytes to write

getIntBe

public int getIntBe(int index)
Retrieves 32-bit word.

Details: getIntBe returns the 32-bit word stored at the given address (index). The word is assembled using "big endian" byte ordering.

Parameters:
index - the address
Returns:
the word

getIntLe

public int getIntLe(int index)
Retrieves 32-bit word.

Details: getIntBe returns the 32-bit word stored at the given address (index). The word is assembled using "little endian" byte ordering.

Parameters:
index - the address
Returns:
the word

setIntBe

public void setIntBe(int index,
                     int value)
Sets 32-bit word.

Details: setIntBe sets the 32-bit word at the given address (index). The word is broken into bytes and the bytes are written in "big endian" byte order.

Parameters:
index - the address
value - the word

setIntLe

public void setIntLe(int index,
                     int value)
Sets 32-bit word.

Details: setIntLe sets the 32-bit word at the given address (index). The word is broken into bytes and the bytes are written in "little endian" byte order.

Parameters:
index - the address
value - the word

fill

public void fill(int index,
                 int amount,
                 byte value)
Fills array.

Details: fill writes the given byte value (value) into the given span of bytes (index, amount). For fill amounts greater than 256, this method can potentially reduce the storage requirements for this virtual array, especially if the fill value is the same as the default value by which this array was constructed.

Parameters:
index - the address
amount - the number of bytes to fill
value - the value to write

search

public long search(int index,
                   int amount,
                   byte value)
Searches for value.

Details: search scans the array for the given value (value), beginning at the given address (index) and searching through amount bytes. If the value is found, its address is returned. Otherwise, -1 is returned.

Parameters:
index - the address of the first byte
amount - number of bytes to search
value - the value to seach for
Returns:
the address of the first matching byte

compact

public int compact()
Reduces storage requirements.

Details: compact scans this array and, if possible, reduces its physical memory requirements by unallocating physical storage for pages whose byte values are all the same. If all of the bytes in this array are the same value, that value is returned. Otherwise, -1 is returned.

Returns:
value of all bytes

Sharkysoft home