Package org.geotools.util

Class LineFormat

Object

Format

LineFormat

All Implemented Interfaces:

Serializable, Cloneable

public class LineFormat
extends Format

Parses a line of text data. This class is mostly used for parsing lines in a matrix or a table. Each column may contains numbers, dates, or other objects parseable by some Format implementations. The example below reads dates in the first column and numbers in all remaining columns.

 final LineParser parser = new LineFormat(new Format[] {
     DateFormat.getDateTimeInstance(),
     NumberFormat.getNumberInstance()
 });
 

LineFormat may be used for reading a matrix with an unknow number of columns, while requiring that all lines have the same number of columns. The example below gets the number of columns while reading the first line, and ensure that all subsequent lines have the same number of columns. If one line violate this condition, then a ParseException will be thrown. The check if performed by the getValues(double[]) method when the data array is non-nul.

  double[] data=null;
  final BufferedReader in = new BufferedReader(new FileReader("MATRIX.TXT"));
  for (String line; (line=in.readLine()) != null;) {
      parser.setLine(line);
      data = parser.getValues(data);
      // ... process 'data' here ...
  });
 

This code can work as well with dates instead of numbers. In this case, the values returned will be microseconds ellapsed since January 1st, 1970.

A ParseException may be thrown because a string can't be parsed, because an object can't be converted into a number or because a line don't have the expected number of columns. In all case, it is possible to gets the index of the first problem found using ParseException.getErrorOffset().

Since:

2.0

Author:

Martin Desruisseaux (IRD)

See Also:

Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from class Format

Format.Field

Constructor Summary

Constructors

Constructor	Description
LineFormat()	Constructs a new line parser for the default locale.
LineFormat(Format format)	Constructs a new line parser using the specified format for every columns.
LineFormat(Format... formats)	Constructs a new line parser using the specified format objects.
LineFormat(Locale locale)	Constructs a new line parser for the specified locale.

Method Summary

Modifier and Type	Method	Description
void	clear()	Clears this parser.
LineFormat	clone()	Returns a clone of this parser.
StringBuffer	format(Object values, StringBuffer toAppendTo, FieldPosition position)	Formats an object and appends the resulting text to a given string buffer.
Object	getValue(int index)	Returns the value at the specified index.
int	getValueCount()	Returns the number of elements found in the last line parsed by setLine(String).
byte[]	getValues(byte[] array)	Copies all values to the specified array.
double[]	getValues(double[] array)	Copies all values to the specified array.
float[]	getValues(float[] array)	Copies all values to the specified array.
int[]	getValues(int[] array)	Copies all values to the specified array.
long[]	getValues(long[] array)	Copies all values to the specified array.
short[]	getValues(short[] array)	Copies all values to the specified array.
Object	parseObject(String source)	Parses text from the beginning of the given string to produce an object.
Object	parseObject(String source, ParsePosition position)	Parses text from a string to produce an object.
int	setLine(String line)	Parses the specified line.
int	setLine(String line, int lower, int upper)	Parses a substring of the specified line.
void	setValue(int index, Object value)	Sets or adds a value to current line.
void	setValues(Object values)	Sets all values in the current line.
String	toString()	Returns a string representation of current line.

Methods inherited from class Format

format, formatToCharacterIterator

Methods inherited from class Object

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

Constructor Detail

LineFormat

public LineFormat()

Constructs a new line parser for the default locale.

LineFormat

public LineFormat(Locale locale)

Constructs a new line parser for the specified locale. For example Locale.US may be used for reading numbers using the dot as decimal separator.

LineFormat

public LineFormat(Format format)
           throws IllegalArgumentException

Constructs a new line parser using the specified format for every columns.

Parameters:

format - The format to use.

Throws:

IllegalArgumentException - if format is null.

LineFormat

public LineFormat(Format... formats)
           throws IllegalArgumentException

Constructs a new line parser using the specified format objects. For example the first column will be parsed using formats[0]; the second column will be parsed using formats[1], etc. If there is more columns than formats, then the last format object is reused for all remaining columns.

Parameters:

formats - The formats to use for parsing.

Throws:

IllegalArgumentException - if formats is null or an element of format is null.

Method Detail

clear

public void clear()

Clears this parser. Next call to getValueCount() will returns 0.

setLine

public int setLine(String line)
            throws ParseException

Parses the specified line. The content is immediately parsed and values can be obtained using one of the getValues(...) method.

Parameters:

line - The line to parse.

Returns:

The number of elements parsed in the specified line. The same information can be obtained with getValueCount().

Throws:

ParseException - If at least one column can't be parsed.

setLine

public int setLine(String line,
                   int lower,
                   int upper)
            throws ParseException

Parses a substring of the specified line. The content is immediately parsed and values can be obtained using one of the getValues(...) method.

Parameters:

line - The line to parse.

lower - Index of the first character in line to parse.

upper - Index after the last character in line to parse.

Returns:

The number of elements parsed in the specified line. The same information can be obtained with getValueCount().

Throws:

ParseException - If at least one column can't be parsed.

getValueCount

public int getValueCount()

Returns the number of elements found in the last line parsed by setLine(String).

setValues

public void setValues(Object values)
               throws IllegalArgumentException

Sets all values in the current line. The values argument must be an array, which may be of primitive type.

Parameters:

values - The array to set as values.

Throws:

IllegalArgumentException - if values is not an array.

Since:

2.4

setValue

public void setValue(int index,
                     Object value)
              throws ArrayIndexOutOfBoundsException

Sets or adds a value to current line. The index should be in the range 0 to getValueCount() inclusively. If the index is equals to getValueCount(), then value will be appended as a new column after existing data.

Parameters:

index - Index of the value to add or modify.

value - The new value.

Throws:

ArrayIndexOutOfBoundsException - If the index is outside the expected range.

getValue

public Object getValue(int index)
                throws ArrayIndexOutOfBoundsException

Returns the value at the specified index. The index should be in the range 0 inclusively to getValueCount() exclusively.

Parameters:

index - Index of the value to fetch.

Returns:

The value at the specified index.

Throws:

ArrayIndexOutOfBoundsException - If the index is outside the expected range.

getValues

public double[] getValues(double[] array)
                   throws ParseException

Copies all values to the specified array. This method is typically invoked after setLine(String) for fetching the values just parsed. If array is null, this method creates and returns a new array with a length equals to number of elements parsed. If array is not null, then this method will thrown an exception if the array length is not exactly equals to the number of elements parsed.

Parameters:

array - The array to copy values into.

Returns:

array if it was not null, or a new array otherwise.

Throws:

ParseException - If array was not null and its length is not equals to the number of elements parsed, or if at least one element can't be parsed.

getValues

public float[] getValues(float[] array)
                  throws ParseException

Copies all values to the specified array. This method is typically invoked after setLine(String) for fetching the values just parsed. If array is null, this method creates and returns a new array with a length equals to number of elements parsed. If array is not null, then this method will thrown an exception if the array length is not exactly equals to the number of elements parsed.

Parameters:

array - The array to copy values into.

Returns:

array if it was not null, or a new array otherwise.

Throws:

ParseException - If array was not null and its length is not equals to the number of elements parsed, or if at least one element can't be parsed.

getValues

public long[] getValues(long[] array)
                 throws ParseException

Copies all values to the specified array. This method is typically invoked after setLine(String) for fetching the values just parsed. If array is null, this method creates and returns a new array with a length equals to number of elements parsed. If array is not null, then this method will thrown an exception if the array length is not exactly equals to the number of elements parsed.

Parameters:

array - The array to copy values into.

Returns:

array if it was not null, or a new array otherwise.

Throws:

ParseException - If array was not null and its length is not equals to the number of elements parsed, or if at least one element can't be parsed.

getValues

public int[] getValues(int[] array)
                throws ParseException

Copies all values to the specified array. This method is typically invoked after setLine(String) for fetching the values just parsed. If array is null, this method creates and returns a new array with a length equals to number of elements parsed. If array is not null, then this method will thrown an exception if the array length is not exactly equals to the number of elements parsed.

Parameters:

array - The array to copy values into.

Returns:

array if it was not null, or a new array otherwise.

Throws:

ParseException - If array was not null and its length is not equals to the number of elements parsed, or if at least one element can't be parsed.

getValues

public short[] getValues(short[] array)
                  throws ParseException

Copies all values to the specified array. This method is typically invoked after setLine(String) for fetching the values just parsed. If array is null, this method creates and returns a new array with a length equals to number of elements parsed. If array is not null, then this method will thrown an exception if the array length is not exactly equals to the number of elements parsed.

Parameters:

array - The array to copy values into.

Returns:

array if it was not null, or a new array otherwise.

Throws:

ParseException - If array was not null and its length is not equals to the number of elements parsed, or if at least one element can't be parsed.

getValues

public byte[] getValues(byte[] array)
                 throws ParseException

Copies all values to the specified array. This method is typically invoked after setLine(String) for fetching the values just parsed. If array is null, this method creates and returns a new array with a length equals to number of elements parsed. If array is not null, then this method will thrown an exception if the array length is not exactly equals to the number of elements parsed.

Parameters:

array - The array to copy values into.

Returns:

array if it was not null, or a new array otherwise.

Throws:

ParseException - If array was not null and its length is not equals to the number of elements parsed, or if at least one element can't be parsed.

toString

public String toString()

Returns a string representation of current line. All columns are formatted using the Format object specified at construction time. Columns are separated by tabulation.

Overrides:

toString in class Object

format

public StringBuffer format(Object values,
                           StringBuffer toAppendTo,
                           FieldPosition position)

Formats an object and appends the resulting text to a given string buffer. This method invokes setValues(values), then formats all columns using the Format object specified at construction time. Columns are separated by tabulation.

Specified by:

format in class Format

Since:

2.4

parseObject

public Object parseObject(String source,
                          ParsePosition position)

Parses text from a string to produce an object.

Specified by:

parseObject in class Format

Since:

2.4

parseObject

public Object parseObject(String source)
                   throws ParseException

Parses text from the beginning of the given string to produce an object.

Overrides:

parseObject in class Format

Throws:

ParseException

Since:

2.4

clone

public LineFormat clone()

Returns a clone of this parser. In current implementation, this clone is not for usage in concurrent thread.

Overrides:

clone in class Format