Class 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

      All Methods Instance Methods Concrete Methods 
      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