lava.array
Class ByteArray32

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

public final class ByteArray32

extends java.lang.Object

2³²-entry virtual byte array.

Details: A ByteArray32 is an array of 2³² 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