org.writersforge.catalan.text
Class AsciiFieldManager

java.lang.Object
  org.writersforge.catalan.text.AsciiFieldManager

public class AsciiFieldManager

extends java.lang.Object

A field-level manager for packing and unpacking ASCII data. Provides methods for loading a special field format specification string and using that to extract packed data from an ASCII string into Java data types, and to insert Java data types into ASCII strings.

The field spec is a series of field type and size declarations encoded into a single String parameter in the AsciiFieldManager constructor. Each field contains a mandatory numerical length and type, and an optional array count. The field length determines how many ASCII characters of data correspond to a single element of that field data. The array count determines how many consecutive elements field exist in that slice of the ASCII data. Whitespace in the field spec is completely ignored.

The field type must be one of six categories:

Type	Description	Java Type
x	padding	N/A
b	byte	java.lang.Byte
c	character	java.lang.Character
i	integer	java.lang.Integer
s	string	java.lang.String
f	float	java.lang.Double

Non-array field specs are simply the field length and the type. Thus, the field spec "4s 3i" declares seven characters of ASCII data; the first four characters make up a String object and the final three characters are converted into an Integer object. Thus, the ASCII data "1234567" would yield a String field of "1234" and an Integer field of 567. This association works both ways, so conversely a String field of "nope" and an Integer of 34 would pack into ASCII data "nope34 ".

Array field specs provide an easy way to load large chunks of uniformly sized data fields into a single Java array object. To declare an array spec, append the array size to the field spec, surrounded by square brackets. For example, a field spec of "2s 2i[4]" declares one two-character String and four two-character Integer objects. The ASCII data "0123456789" would unpack into a String of "01" and an Integer[] array equivalent to the Java code: new Integer[] { 23, 45, 67, 89 }.

Author:

jsheets

Constructor Summary

AsciiFieldManager(java.lang.String fieldFormat)
Creates a new instance of AsciiFieldManager.

Method Summary

java.lang.Object	extractValue(int fieldIndex, java.lang.String asciiData) Parses the asciiData input data and pulls out the data corresponding to the given field index, then converts that data to the correct Java data type.
int	getFieldArraySize(int field) Retrieves the number of array elements of the given field.
int	getFieldCount() Calculates the number of discrete fields in the format spec.
int	getFieldLength(int field) Retrieves the length of the given field in its ASCII version.
java.lang.Class	getFieldType(int field) Retrieves the Java type that corresponds to the given field number.
void	insertValue(int fieldIndex, java.lang.StringBuffer asciiData, java.lang.Object newValue) Converts the newValue object into ASCII content and inserts it into the asciiData buffer.
void	normalize(java.lang.StringBuffer data) Fills in current padding without touching any existing data fields.
void	setPadding(java.lang.String padding) Assigns a new custom padding specification.

Methods inherited from class java.lang.Object

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

Constructor Detail

AsciiFieldManager

public AsciiFieldManager(java.lang.String fieldFormat)
                  throws java.lang.IllegalArgumentException

Creates a new instance of AsciiFieldManager.

Parameters:

fieldFormat - Python-style packing format specification

Throws:

java.lang.IllegalArgumentException - if fieldFormat is not syntactically valid

Method Detail

getFieldCount

public int getFieldCount()

Calculates the number of discrete fields in the format spec. For example, a format spec of "12s3d[1]5i[5]" would have 3 fields.

Returns:

the number of fields

getFieldType

public java.lang.Class getFieldType(int field)

Retrieves the Java type that corresponds to the given field number. For example, given a format spec of "12s3d[1]5i[6]", field 0 would be a String, field 1 would be a Double[], and field 2 would be a Integer[].

Parameters:

field - the index of the field in the format spec

Returns:

a Java class that represents the type of the given field

getFieldLength

public int getFieldLength(int field)

Retrieves the length of the given field in its ASCII version. For example, given a format spec of "12s3d[1]5i[6]", field 0 would have a length of 12, field 1 would have a length of 3, and field2 would have a length of 5 (not 30). Thus, the field length represents the size of a single array element in the field.

Parameters:

field - the index of the field in the format spec

Returns:

the expected length of one field element in its ASCII form

getFieldArraySize

public int getFieldArraySize(int field)

Retrieves the number of array elements of the given field. For example, given a format spec of "12s3d[1]5i[6]", field 0 would have an array size of 1 (the field's class type would specify that it is not an array), field 1 would have an array size of 1, and field 2 would have an array size of 6.

Parameters:

field - the index of the field in the format spec

Returns:

the expected length of the field in its ASCII form

setPadding

public void setPadding(java.lang.String padding)

Assigns a new custom padding specification. The default padding spec is a single space character, " ".

See Also:

normalize(java.lang.StringBuffer)

normalize

public void normalize(java.lang.StringBuffer data)

Fills in current padding without touching any existing data fields. Extends the buffer with space characters to cover non-existent fields. Always uses space characters for data fields, regardless of the current padding string. Calling normalize() on an empty StringBuffer with default padding will result in a StringBuffer filled with spaces to the exact data length determined by the field spec. The padding string will be cycled through across multiple padding fields. This allows for complex padding. For example, given the following code:

   String spec = "2x2s4x3s3x";
   AsciiFieldManager fields = new AsciiFieldManager (spec);
   fields.setPadding ("--XXXX");
   StringBuffer data = new StringBuffer ();
   fields.normalize (data);

The new value of data would be:

 "--  XXXX   --X"

The padding is split across the first two padding fields, and cycled through again in the third padding field.

Parameters:

data - the ASCII data to normalize

extractValue

public java.lang.Object extractValue(int fieldIndex,
                                     java.lang.String asciiData)
                              throws java.lang.IllegalArgumentException

Parses the asciiData input data and pulls out the data corresponding to the given field index, then converts that data to the correct Java data type. If the input data is too short, or if the raw field data can't be converted to the proper type, it will throw an exception.

Parameters:

fieldIndex - the index of the field in the format spec

asciiData - input data that follows the format spec

Returns:

a Java object loaded with the given field's value

Throws:

java.lang.IllegalArgumentException - if asciiData cannot be converted into a valid object for the given field

insertValue

public void insertValue(int fieldIndex,
                        java.lang.StringBuffer asciiData,
                        java.lang.Object newValue)

Converts the newValue object into ASCII content and inserts it into the asciiData buffer. If asciiData isn't currently large enough, it will be expanded to fit, and any previous data in the given field will be overwritten.

Parameters:

fieldIndex - the index of the field in the format spec

asciiData - output target to write the data to

newValue - the input data to write to asciiData