J avolution v5.2 (J2SE 1.5+)

javolution.text
Class TextFormat<T>

java.lang.Object
  extended by javolution.text.TextFormat<T>

public abstract class TextFormat<T>
extends java.lang.Object

This class represents the base format for text parsing and formatting; it supports CharSequence and Appendable interfaces for greater flexibility.

It is possible to retrieve the format for any class for which the format has been registered (typically during class initialization). For example:

     public class Complex extends RealtimeObject {
         private static final TextFormat<Complex> CARTESIAN = ...;
         static { // Sets default format to cartesian, users may change it later (e.g. polar).
             TextFormat.setInstance(Complex.class, CARTESIAN);
         }
         public Complex valueOf(CharSequence csq) {
             return TextFormat.getInstance(Complex.class).parse(csq);
         }
         public Text toText() {
             return TextFormat.getInstance(Complex.class).format(this);
         }
     }

For parsing/formatting of primitive types, the TypeFormat utility class is recommended.

Note: The format behavior may depend upon local settings in which case concurrent threads may parse differently!

Version:
5.1, July 4, 2007
Author:
Jean-Marie Dautelle

Nested Class Summary
static class TextFormat.Cursor
          This class represents a parsing cursor over a character sequence (or subsequence).
 
Constructor Summary
protected TextFormat()
          Default constructor.
 
Method Summary
 Text format(T obj)
          Formats the specified object to a Text instance (convenience method).
abstract  java.lang.Appendable format(T obj, java.lang.Appendable dest)
          Formats the specified object into an Appendable
 java.lang.Appendable format(T obj, TextBuilder dest)
          Formats the specified object into a TextBuilder (convenience method which does not raise IOException).
static
<T> TextFormat<T>
getInstance(java.lang.Class<T> cls)
          Returns the text format for instances of specified type (class or interface).
 T parse(java.lang.CharSequence csq)
          Parses a whole character sequence from the beginning to produce an object (convenience method).
abstract  T parse(java.lang.CharSequence csq, TextFormat.Cursor cursor)
          Parses a portion of the specified CharSequence from the specified position to produce an object.
static
<T> void
setInstance(java.lang.Class<T> cls, TextFormat<T> format)
          Associates the specified format to the specified type (class or interface).
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

TextFormat

protected TextFormat()
Default constructor.

Method Detail

getInstance

public static <T> TextFormat<T> getInstance(java.lang.Class<T> cls)
Returns the text format for instances of specified type (class or interface). The following types are always recognized:
  • java.lang.Boolean
  • java.lang.Character
  • java.lang.Byte
  • java.lang.Short
  • java.lang.Integer
  • java.lang.Long
  • java.lang.Float
  • java.lang.Double
  • java.lang.Class
Users may register additional types using the TextFormat.setInstance(Class, TextFormat) static method. For example:
 TextFormat<Font> fontFormat = new TextFormat() {
     public Appendable format(Font font, Appendable dest) throws IOException {
         return dest.append(font.getName());
     }
     public Font parse(CharSequence csq, Cursor cursor) {
         CharSequence fontName = csq.subSequence(cursor.getIndex(), cursor.getEndIndex());
         cursor.increment(fontName.length());
         return Font.decode(fontName.toString());
     }
 });
 TextFormat.setInstance(Font.class, fontFormat); // Registers format for java.awt.Font
 

Parameters:
cls - the class for which the default format is returned.
Returns:
the format for instances of the specified class or null if unkown.

setInstance

public static <T> void setInstance(java.lang.Class<T> cls,
                                   TextFormat<T> format)
Associates the specified format to the specified type (class or interface).

Parameters:
cls - the class for which the default format is returned.
format - the format for instances of the specified calss class.

format

public abstract java.lang.Appendable format(T obj,
                                            java.lang.Appendable dest)
                                     throws java.io.IOException
Formats the specified object into an Appendable

Parameters:
obj - the object to format.
dest - the appendable destination.
Returns:
the specified Appendable.
Throws:
java.io.IOException - if an I/O exception occurs.

parse

public abstract T parse(java.lang.CharSequence csq,
                        TextFormat.Cursor cursor)
Parses a portion of the specified CharSequence from the specified position to produce an object. If parsing succeeds, then the index of the cursor argument is updated to the index after the last character used.

Parameters:
csq - the CharSequence to parse.
cursor - the cursor holding the current parsing index.
Returns:
the object parsed from the specified character sub-sequence.
Throws:
java.lang.RuntimeException - if any problem occurs while parsing the specified character sequence (e.g. illegal syntax).

format

public final java.lang.Appendable format(T obj,
                                         TextBuilder dest)
Formats the specified object into a TextBuilder (convenience method which does not raise IOException).

Parameters:
obj - the object to format.
dest - the text builder destination.
Returns:
the specified text builder.

format

public final Text format(T obj)
Formats the specified object to a Text instance (convenience method).

Parameters:
obj - the object being formated.
Returns:
the text representing the specified object.

parse

public final T parse(java.lang.CharSequence csq)
Parses a whole character sequence from the beginning to produce an object (convenience method).

Parameters:
csq - the whole character sequence to parse.
Returns:
the corresponding object.
Throws:
java.lang.IllegalArgumentException - if the specified character sequence cannot be fully parsed.

J avolution v5.2 (J2SE 1.5+)

Copyright © 2005 - 2007 Javolution.