J avolution v5.4 (J2SE 1.6+)

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 the CharSequence and Appendable interfaces for greater flexibility.

Typically, classes for which textual parsing/formatting is supported have a protected static final TextFormat instance holding the default format for the class. For input/output (e.g. valueOf(CharSequence), toString()), the context-local format (or current format) should be used.

     public class Complex implements ValueType {
         // Defines the default format for Complex (cartesian).
         protected static final TextFormat<Complex> TEXT_FORMAT = new TextFormat<Complex>(Complex.class) {
             ...
         }
         public Complex valueOf(CharSequence csq) {
             // Uses the local format for Complex numbers.
             return TextFormat.getInstance(Complex.class).parse(csq);
         }
         public Text toText() {
             // Uses the local format for Complex numbers.
             return TextFormat.getInstance(Complex.class).format(this);
         }
     }
     

It is possible to retrieve either the default format for any class or the current format which can be locally overriden on a thread basis.

     Complex c = Complex.valueOf(3, 4);
     System.out.println(c); // Display using the default cartesian format (e.g. "2.1 - 3.2i")
     TextFormat<Complex> polarFormat = new TextFormat<Complex>(null) { ... }; // Creates an unbounded format.
     LocalContext.enter();
     try {
         TextFormat.setInstance(polarFormat, Complex.class); // Context-local setting.
         System.out.println(c); // Display using the local polar format.
     } finally {
         LocalContext.exit(); // Reverts to the default cartesian format for complex numbers.
     }
     

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

Version:
5.4, November 2, 2009
Author:
Jean-Marie Dautelle

Constructor Summary
protected TextFormat(java.lang.Class<T> cls)
          Creates a new text format and if a class is specified, makes it the default format for all instances of the class.
 
Method Summary
 Text format(T obj)
          Formats the specified object to a Text instance (convenience method equivalent to format(obj, TextBuilder.newInstance()).toText()).
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).
 java.lang.Class<T> getBoundClass()
          Returns the class/interface statically bound to this format or null if this text format is not the default format for the specified class.
static
<T> TextFormat<T>
getDefault(java.lang.Class<? extends T> forClass)
           Returns the default text format for instances of specified type.
static
<T> TextFormat<T>
getInstance(java.lang.Class<? extends T> forClass)
           Returns the current text format for instances of specified type.
 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, Cursor cursor)
          Parses a portion of the specified CharSequence from the specified position to produce an object.
static
<T> void
setInstance(TextFormat<T> format, java.lang.Class<T> forClass)
          Overrides the current format for the specified class (context-local).
 java.lang.String toString()
          Returns textual information about this format.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

TextFormat

protected TextFormat(java.lang.Class<T> cls)
Creates a new text format and if a class is specified, makes it the default format for all instances of the class. The actual format (local) for a given class can be retrieved through the getInstance(java.lang.Class) static method.

Parameters:
cls - the class for which this format is the default format or null to return an unbounded format.
Throws:
java.lang.IllegalArgumentException - if the specified class has already a default text format associated with (which can only be overriden by local formats, see setInstance(javolution.text.TextFormat, java.lang.Class)
Method Detail

getDefault

public static <T> TextFormat<T> getDefault(java.lang.Class<? extends T> forClass)

Returns the default text format for instances of specified type. If there is no text format for the specified type, a text format for the implementing interfaces is searched. If still none is found a recurcive search is performed on the parent class.

Default format instances are typically defined as protected static final instances in their bound class.

The following predefined types have a default format:

Parameters:
forClass - the class for which the default format is returned.
Returns:
the default format for instances of the specified class or null is none found for the class itself, its parent classes or implementing interfaces.

getInstance

public static <T> TextFormat<T> getInstance(java.lang.Class<? extends T> forClass)

Returns the current text format for instances of specified type. If there is no text format for the specified type, a text format for the implementing interfaces is searched. If still none is found a recurcive search is performed on the parent class.

If the text format has not been overriden then the default is returned.

Parameters:
forClass - the class for which the current format is returned.
Returns:
the current format for instances of the specified class or null if none.
See Also:
LocalMap

setInstance

public static <T> void setInstance(TextFormat<T> format,
                                   java.lang.Class<T> forClass)
Overrides the current format for the specified class (context-local).

Parameters:
format - the format for instances of the specified class.
forClass - the class for which the text format is overriden.
See Also:
getInstance(java.lang.Class), LocalMap

getBoundClass

public final java.lang.Class<T> getBoundClass()
Returns the class/interface statically bound to this format or null if this text format is not the default format for the specified class.

Returns:
the class/interface bound to this format or null

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,
                        Cursor cursor)
                 throws java.lang.IllegalArgumentException
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.IllegalArgumentException - 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 equivalent to format(obj, TextBuilder.newInstance()).toText()).

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

parse

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

Parameters:
csq - the whole character sequence to parse.
Returns:
parse(csq, new Cursor())
Throws:
java.lang.IllegalArgumentException - if the specified character sequence cannot be fully parsed (e.g. extraneous characters).

toString

public java.lang.String toString()
Returns textual information about this format.

Overrides:
toString in class java.lang.Object
Returns:
this format textual information.

J avolution v5.4 (J2SE 1.6+)

Copyright © 2005 - 2009 Javolution.