com.flagstone.transform.util
Class FSCodec

java.lang.Object
  com.flagstone.transform.util.FSCodec

Deprecated. FSCoded is replaced by FSCoder from com.flagstone.transform so there is only one class for reading and writing data. FSCodec is a similar to Java stream classes, allowing words and bit fields to be read and written from an internal array of bytes. FSCodec supports both little-endian and big-endian byte ordering. The primary use of the class is to support post-processing of sound files loaded using the FSSoundConstructor class where the encoded sound samples contain bits fields. For example compressing 16-bit, byte-aligned sound samples to the ADPCM format. However the class may be used in any situation where data must be encoded or decoded to an array of bytes. The FSCodec class maintains an internal pointer which points to the next bit in the internal array where data will be read or written. When calculating an offset in bytes to jump to simply multiply the offset by 8 for the correct bit position. The class provides accessor methods, getPosition() and setPosition() to change the location of the internal pointer. When writing to an array the size of the array is changed dynamically should a write operation cause a buffer overflow. For reads if an overflow results then the bits/bytes that overflowed will be set to zero, rather than throwing an exception. The eof() method can be used to determine whether the end of the buffer has been reached.

public class FSCodec
extends java.lang.Object

Field Summary

static int	BIG_ENDIAN Deprecated. Identifies that multibyte words are stored in big-endian format with the most significant byte in a word stored first.
static int	LITTLE_ENDIAN Deprecated. Identifies that multibyte words are stored in little-endian format with the least significant byte in a word stored first.

Constructor Summary

FSCodec(int order, byte[] bytes)
Deprecated. Constructs and FSCodec object containing an array of bytes with the specified byte ordering.

FSCodec(int order, int size)
Deprecated. Constructs and FSCodec object containing an array of bytes with the specified byte ordering.

Method Summary

void	alignToByte() Deprecated. Moves the internal pointer forward so it is aligned on a byte boundary.
boolean	eof() Deprecated. Returns true of the internal pointer is at the end of the buffer.
boolean	findBits(int value, int numberOfBits, int step) Deprecated. Searches the internal buffer for a bit pattern and advances the pointer to the start of the bit field, returning true to signal a successful search.
boolean	findWord(int value, int numberOfBytes, int step) Deprecated. Searches the internal buffer for a word and advances the pointer to the location where the word was found, returning true to signal a successful search.
byte[]	getData() Deprecated. Returns a copy of the array of bytes.
int	getPosition() Deprecated. Returns the offset, in bits, from the start of the buffer where the next value will be read or written.
int	readBits(int numberOfBits, boolean signed) Deprecated. Read a bit field from the internal buffer.
int	readBytes(byte[] bytes) Deprecated. Reads an array of bytes from the internal buffer.
int	readWord(int numberOfBytes, boolean signed) Deprecated. Read a word from the internal buffer.
void	setData(byte[] bytes) Deprecated. Sets the array of bytes used to read or write data to.
void	setData(int order, byte[] bytes) Deprecated. Sets the array of bytes used to read or write data to.
void	setPosition(int offset) Deprecated. Sets the offset, in bits, from the start of the buffer where the next value will be read or written.
void	writeBits(int value, int numberOfBits) Deprecated. Write a bit value to the internal buffer.
int	writeBytes(byte[] bytes) Deprecated. Writes an array of bytes from the internal buffer.
void	writeWord(int value, int numberOfBytes) Deprecated. Write a word to the internal buffer.

Methods inherited from class java.lang.Object

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

Field Detail

LITTLE_ENDIAN

public static final int LITTLE_ENDIAN

Deprecated.

Identifies that multibyte words are stored in little-endian format with the least significant byte in a word stored first.

See Also:

Constant Field Values

BIG_ENDIAN

public static final int BIG_ENDIAN

Deprecated.

Identifies that multibyte words are stored in big-endian format with the most significant byte in a word stored first.

See Also:

Constant Field Values

Constructor Detail

FSCodec

public FSCodec(int order,
               byte[] bytes)

Deprecated.

Constructs and FSCodec object containing an array of bytes with the specified byte ordering.

Parameters:

order - the byte-order for words, either FSCodec.LITTLE_ENDIAN or FSCodec.BIG_ENDIAN.

bytes - an array of bytes where the data will be read or written.

FSCodec

public FSCodec(int order,
               int size)

Deprecated.

Constructs and FSCodec object containing an array of bytes with the specified byte ordering.

Parameters:

order - the byte-order for words, either FSCodec.LITTLE_ENDIAN or FSCodec.BIG_ENDIAN.

size - the size of the internal buffer to be created.

Method Detail

getData

public byte[] getData()

Deprecated.

Returns a copy of the array of bytes.

Returns:

a copy of the internal buffer.

setData

public void setData(byte[] bytes)

Deprecated.

Sets the array of bytes used to read or write data to. The size of the array must be calculated in advance to avoid buffer overflows.

Parameters:

bytes - a byte array that will be used as the internal buffer.

setData

public void setData(int order,
                    byte[] bytes)

Deprecated.

Sets the array of bytes used to read or write data to. The byte-order for words read or written is also specified. The size of the array must be calculated in advance to avoid buffer overflows.

Parameters:

order - the byte-order for words, either FSCodec.LITTLE_ENDIAN or FSCodec.BIG_ENDIAN.

bytes - a byte array that will be used as the internal buffer.

getPosition

public int getPosition()

Deprecated.

Returns the offset, in bits, from the start of the buffer where the next value will be read or written.

Returns:

the offset in bits where the next value will be read or written.

setPosition

public void setPosition(int offset)

Deprecated.

Sets the offset, in bits, from the start of the buffer where the next value will be read or written. If the offset falls outside of the bits range supported by the buffer then the pointer is clamped to either the start or end of the buffer.

Parameters:

offset - the offset in bits from the start of the array of bytes.

alignToByte

public void alignToByte()

Deprecated.

Moves the internal pointer forward so it is aligned on a byte boundary. All word values read and written to the internal buffer must be byte-aligned.

eof

public boolean eof()

Deprecated.

Returns true of the internal pointer is at the end of the buffer.

Returns:

true if the pointer is at the end of the buffer, false otherwise.

findBits

public boolean findBits(int value,
                        int numberOfBits,
                        int step)

Deprecated.

Searches the internal buffer for a bit pattern and advances the pointer to the start of the bit field, returning true to signal a successful search. If the bit pattern cannot be found then the method returns false and the position of the internal pointer is not changed. The step, in bits, added to the pointer can be specified, allowing the number of bits being searched to be independent of the location in the internal buffer. This is useful for example when searching for a bit field that begins on a byte or word boundary.

Parameters:

value - an integer containing the bit patter to search for.

numberOfBits - least significant n bits in the value to search for.

step - the increment in bits to add to the internal pointer as the buffer is searched.

Returns:

true if the pattern was found, false otherwise.

findWord

public boolean findWord(int value,
                        int numberOfBytes,
                        int step)

Deprecated.

Searches the internal buffer for a word and advances the pointer to the location where the word was found, returning true to signal a successful search. The search will begin on the next byte boundary. If word cannot be found then the method returns false and the position of the internal pointer is not changed. Specifying the number of bytes in the search value allows word of either 8, 16, 24 or 32 bits to be searched for. Searches for words are performed faster than using the findBits() method.

Parameters:

value - an integer containing the word to search for.

numberOfBytes - least significant n bytes in the value to search for.

step - the increment in bits to add to the internal pointer as the buffer is searched.

Returns:

true if the pattern was found, false otherwise.

readBits

public int readBits(int numberOfBits,
                    boolean signed)

Deprecated.

Read a bit field from the internal buffer. If a buffer overflow occurs then the number of bits which cause the overflow will be set to zero.

Parameters:

numberOfBits - the number of bits to read.

signed - a boolean flag indicating whether the value read should be sign extended.

Returns:

the value read.

writeBits

public void writeBits(int value,
                      int numberOfBits)

Deprecated.

Write a bit value to the internal buffer. The buffer will resize automatically if required.

Parameters:

value - an integer containing the value to be written.

numberOfBits - the least significant n bits from the value that will be written to the buffer.

readWord

public int readWord(int numberOfBytes,
                    boolean signed)

Deprecated.

Read a word from the internal buffer. If a buffer overflow occurs then the number of bytes which cause the overflow will be set to zero.

Parameters:

numberOfBytes - the number of bytes read in the range 1..4.

signed - a boolean flag indicating whether the value read should be sign extended.

Returns:

the value read.

writeWord

public void writeWord(int value,
                      int numberOfBytes)

Deprecated.

Write a word to the internal buffer. The buffer will resize automatically if required.

Parameters:

value - an integer containing the value to be written.

numberOfBytes - the least significant n bytes from the value that will be written to the buffer.

readBytes

public int readBytes(byte[] bytes)

Deprecated.

Reads an array of bytes from the internal buffer. If a read overflow occurs while reading the internal buffer then the remaining bytes in the array will not be filled. The method returns the number of bytes read.

Parameters:

bytes - the array that will contain the bytes read.

Returns:

the number of bytes read from the buffer.

writeBytes

public int writeBytes(byte[] bytes)

Deprecated.

Writes an array of bytes from the internal buffer. The internal buffer will be resized automatically if required.

Parameters:

bytes - the array containing the data to be written.

Returns:

the number of bytes written to the buffer.