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:

  • Constructor Details

    • 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 formats is null.

  • Method Details

    • 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