com.flagstone.transform
Class FSCoder

java.lang.Object
  extended by com.flagstone.transform.FSCoder

public class FSCoder
extends java.lang.Object

FSCoder is a similar to Java stream classes, allowing words and bit fields to be read and written from an internal array of bytes. FSCoder supports both little-endian and big-endian byte ordering. The FSCoder 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, getPointer() and setPointer() 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.


Field Summary
static int BIG_ENDIAN
          Identifies that multibyte words are stored in big-endian format with the most significant byte in a word stored first.
static int LITTLE_ENDIAN
          Identifies that multibyte words are stored in little-endian format with the least significant byte in a word stored first.
static int TransparentColors
          TransparentColors is used to pass information to FSCOlor objects when they are being encoded or decoded so that the alpha channel will be included.
static int Version
          Version is used to pass the current version of Flash that an object is being encoded or decoded for.
 
Constructor Summary
FSCoder(int order, byte[] bytes)
          Constructs an FSCoder object containing an array of bytes with the specified byte order.
FSCoder(int order, int size)
          Constructs an FSCoder object containing an array of bytes with the specified byte ordering.
 
Method Summary
 void addCapacity(int size)
          Increases the size of the internal buffer.
 void adjustPointer(int offset)
          Adds offset, in bits, to the internal pointer to change the location where the next value will be read or written.
 void alignToByte()
          Moves the internal pointer forward so it is aligned on a byte boundary.
 boolean eof()
          Returns true of the internal pointer is at the end of the buffer.
 boolean equals(FSCoder coder)
           
 boolean findBits(int value, int numberOfBits, int step)
          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)
          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.
 int getCapacity()
          Return the size of the internal buffer in bytes.
 int getContext(int key)
           
 byte[] getData()
          Returns a copy of the array of bytes.
 java.lang.String getEncoding()
          Return the string representation of the character encoding scheme used when encoding or decoding strings as a sequence of bytes.
 int getPointer()
          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)
          Read a bit field from the internal buffer.
 int readBytes(byte[] bytes)
          Reads an array of bytes from the internal buffer.
 double readDouble()
          Read a double-precision floating point number from a sequence of bytes using the byte-ordering of the buffer.
 float readFixedBits(int numberOfBits, int fractionSize)
          Read a fixed point number, in either (8.8) or (16.16) format from a bit field.
 float readFixedWord(int mantissaSize, int fractionSize)
          Read a fixed point number, in either (8.8) or (16.16) format from a word field, accounting for the byte-ordering used.
 java.lang.String readString()
          Read a null-terminated string using the default character encoding scheme.
 java.lang.String readString(int length)
          Read a string containing the specified number of characters using the default character encoding scheme.
 java.lang.String readString(int length, java.lang.String enc)
          Read a string containing the specified number of characters with the given character encoding scheme.
 java.lang.String readString(java.lang.String enc)
          Read a null-terminated string using the specified character encoding scheme.
 int readWord(int numberOfBytes, boolean signed)
          Read a word from the internal buffer.
 int scanBits(int numberOfBits, boolean signed)
          Read a bit field without adjusting the internal pointer.
 int scanWord(int numberOfBytes, boolean signed)
          Read a word without adjusting the internal pointer.
 void setContext(int key, int value)
           
 void setData(int order, byte[] bytes)
          Sets the array of bytes used to read or write data to.
 void setEncoding(java.lang.String enc)
          Sets the string representation of the character encoding scheme used when encoding or decoding strings as a sequence of bytes.
 void setPointer(int location)
          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)
          Write a bit value to the internal buffer.
 int writeBytes(byte[] bytes)
          Writes an array of bytes from the internal buffer.
 void writeDouble(double value)
          Write a double-precision floating point number as a sequence of bytes using the byte-ordering of the buffer.
 void writeFixedBits(float value, int numberOfBits, int fractionSize)
          Write a fixed point number, in either (8.8) or (16.16) format to a bit field.
 void writeFixedWord(float value, int mantissaSize, int fractionSize)
          Write a fixed point number, in either (8.8) or (16.16) format to a word field, accounting for the byte-ordering used.
 int writeString(java.lang.String str)
          Write a string to the internal buffer using the default character encoding scheme.
 int writeString(java.lang.String str, java.lang.String enc)
          Write a string to the internal buffer using the specified character encoding scheme.
 void writeWord(int value, int numberOfBytes)
          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
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
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

TransparentColors

public static final int TransparentColors
TransparentColors is used to pass information to FSCOlor objects when they are being encoded or decoded so that the alpha channel will be included.

See Also:
Constant Field Values

Version

public static final int Version
Version is used to pass the current version of Flash that an object is being encoded or decoded for.

See Also:
Constant Field Values
Constructor Detail

FSCoder

public FSCoder(int order,
               int size)
Constructs an FSCoder object containing an array of bytes with the specified byte ordering.

Parameters:
order - the byte-order for words, eitherLITTLE_ENDIAN or BIG_ENDIAN.
size - the size of the internal buffer to be created.

FSCoder

public FSCoder(int order,
               byte[] bytes)
Constructs an FSCoder object containing an array of bytes with the specified byte order.

Parameters:
order - the byte-order for words, either LITTLE_ENDIAN or BIG_ENDIAN.
bytes - an array of bytes where the data will be read or written.
Method Detail

equals

public boolean equals(FSCoder coder)

getEncoding

public java.lang.String getEncoding()
Return the string representation of the character encoding scheme used when encoding or decoding strings as a sequence of bytes.

Returns:
the string the name of the encoding scheme for characters.

setEncoding

public void setEncoding(java.lang.String enc)
Sets the string representation of the character encoding scheme used when encoding or decoding strings as a sequence of bytes.

Parameters:
enc - the string the name of the encoding scheme for characters.

getData

public byte[] getData()
Returns a copy of the array of bytes.

Returns:
a copy of the internal buffer.

setData

public void setData(int order,
                    byte[] bytes)
Sets the array of bytes used to read or write data to.

Parameters:
order - the byte-order for words, either FSCoder.LITTLE_ENDIAN or FSCoder.BIG_ENDIAN.
bytes - a byte array that will be used as the internal buffer.

addCapacity

public void addCapacity(int size)
Increases the size of the internal buffer. This method is used when encoding data to automatically adjust the buffer size to avoid overflows.

Parameters:
size - the number of bytes to add to the buffer.

getCapacity

public int getCapacity()
Return the size of the internal buffer in bytes.

Returns:
the size of the buffer.

getPointer

public int getPointer()
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.

setPointer

public void setPointer(int location)
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 an IllegalArgumentException will be thrown.

Parameters:
location - the offset in bits from the start of the array of bytes.

adjustPointer

public void adjustPointer(int offset)
Adds offset, in bits, to the internal pointer to change the location where the next value will be read or written. If the adjust causes the point to fall outside the bounds of the internal data then the value is clamped to either the start of end of the array.

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

alignToByte

public void alignToByte()
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()
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.

readBits

public int readBits(int numberOfBits,
                    boolean signed)
Read a bit field from the internal buffer. If a buffer overflow would occur then the bits which would cause the error when read 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)
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)
Read a word from the internal buffer. If a buffer overflow would occur then the bytes which would cause the error when read 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)
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)
Reads an array of bytes from the internal buffer. If a read overflow would occur 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)
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.

scanBits

public int scanBits(int numberOfBits,
                    boolean signed)
Read a bit field without adjusting the internal pointer.

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.

scanWord

public int scanWord(int numberOfBytes,
                    boolean signed)
Read a word without adjusting the internal pointer.

Parameters:
numberOfBytes - the number of bytes to read.
signed - a boolean flag indicating whether the value read should be sign extended.
Returns:
the value read.

readFixedBits

public float readFixedBits(int numberOfBits,
                           int fractionSize)
Read a fixed point number, in either (8.8) or (16.16) format from a bit field.

Parameters:
numberOfBits - the number of bits the number is encoded in.
fractionSize - the number of bits occupied by the fractional part of the number. The integer part will be signed extended.
Returns:
the value read as a floating-point number.

writeFixedBits

public void writeFixedBits(float value,
                           int numberOfBits,
                           int fractionSize)
Write a fixed point number, in either (8.8) or (16.16) format to a bit field.

Parameters:
value - the value to be ecoded.
numberOfBits - the number of bits the number is encoded in.
fractionSize - the number of bits occupied by the fractional part of the number. The integer part will be signed extended.

readFixedWord

public float readFixedWord(int mantissaSize,
                           int fractionSize)
Read a fixed point number, in either (8.8) or (16.16) format from a word field, accounting for the byte-ordering used.

Parameters:
mantissaSize - the number of bits occupied by the integer part of the number. This will be signed extended.
fractionSize - the number of bits occupied by the fractional part of the number.
Returns:
the value read as a floating-point number.

writeFixedWord

public void writeFixedWord(float value,
                           int mantissaSize,
                           int fractionSize)
Write a fixed point number, in either (8.8) or (16.16) format to a word field, accounting for the byte-ordering used.

Parameters:
value - the value to be written.
mantissaSize - the number of bits occupied by the integer part of the number.
fractionSize - the number of bits occupied by the fractional part of the number.

readDouble

public double readDouble()
Read a double-precision floating point number from a sequence of bytes using the byte-ordering of the buffer.

Returns:
the value.

writeDouble

public void writeDouble(double value)
Write a double-precision floating point number as a sequence of bytes using the byte-ordering of the buffer.

Parameters:
value - the value to be written.

readString

public java.lang.String readString(int length)
Read a string containing the specified number of characters using the default character encoding scheme.

Parameters:
length - the number of characters to read.
Returns:
the string containing the specified number of characters.

readString

public java.lang.String readString(int length,
                                   java.lang.String enc)
Read a string containing the specified number of characters with the given character encoding scheme.

Parameters:
length - the number of characters to read.
Returns:
enc, the string the name of the encoding schemd for characters.

readString

public java.lang.String readString()
Read a null-terminated string using the default character encoding scheme.

Returns:
the string read from the internal buffer.

readString

public java.lang.String readString(java.lang.String enc)
Read a null-terminated string using the specified character encoding scheme.

Returns:
the string read from the internal buffer.

writeString

public int writeString(java.lang.String str)
Write a string to the internal buffer using the default character encoding scheme.

Parameters:
str - the string.
Returns:
the number of bytes written.

writeString

public int writeString(java.lang.String str,
                       java.lang.String enc)
Write a string to the internal buffer using the specified character encoding scheme.

Parameters:
str - the string.
Returns:
the number of bytes written.

findBits

public boolean findBits(int value,
                        int numberOfBits,
                        int step)
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)
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.

getContext

public int getContext(int key)

setContext

public void setContext(int key,
                       int value)