javolution.text

Class TextFormat<T>

java.lang.Object

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.

Instances of this class are typically used as static member of a class to define the default textual representation of its instances.

     public class Complex extends Number {

         // Defines the default format for complex numbers (Cartesian form)
         protected static TextFormat<Complex> TEXT_FORMAT = new TextFormat<Complex> (Complex.class) { ... }

         public static Complex valueOf(CharSequence csq) {
             return TEXT_FORMAT.parse(csq);
         }

     }

The format associated to any given class/object can be dynamically retrieved.

     public abstract class Number implements ValueType {

         public final Text toText() {
             return TextFormat.getInstance(this.getClass()).format(this);
         }

         public final String toString() {
             return TextFormat.getInstance(this.getClass()).formatToString(this);
         }
     }

The default format can be locally overriden.

     LocalContext.enter();
     try {
          TextFormat<Complex> polarFormat = new TextFormat<Complex>(null) {...} // Unbound format.
          TextFormat.setInstance(Complex.class, polarFormat); // Local setting (no impact on others thread).
          System.out.println(complex); // Displays complex in polar coordinates.
     } finally {
          LocalContext.exit(); // Reverts to previous cartesian setting.
     }

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

Version:

5.5, March 20, 2010

Author:

Jean-Marie Dautelle

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	TextFormat(java.lang.Class<T> forClass) Defines the static format bound to the specified class.

Method Summary

Modifier and Type	Method and Description
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
TextBuilder	format(T obj, TextBuilder dest) Formats the specified object into a TextBuilder (convenience method which does not raise IOException).
java.lang.String	formatToString(T obj) Convenience methods equivalent to but faster than format(obj).toString())
static <T> TextFormat<T>	getDefault(java.lang.Class<? extends T> forClass) Returns the default format for instances of the specified class.
static <T> TextFormat<T>	getInstance(java.lang.Class<? extends T> forClass) Returns the current format for instances of the specified class.
boolean	isParsingSupported() Indicates if this format supports parsing (default true).
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(java.lang.Class<? extends T> forClass, TextFormat<T> format) Overrides the default format for the specified class (local setting).

Methods inherited from class java.lang.Object

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

Constructor Detail

TextFormat

protected TextFormat(java.lang.Class<T> forClass)

Defines the static format bound to the specified class.

Parameters:

forClass - the class to which the format is bound or null if the format is not bound to any class.

Throws:

java.lang.IllegalArgumentException - if the specified class is already bound to another format.

Method Detail

getDefault

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

Returns the default format for instances of the specified class.

A default format exist for the following predefined types:

• java.lang.Object (formatting only, e.g. "org.acmes.Foo#123")
• java.lang.String
• 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
• javolution.util.Index
• javolution.text.Text

If there is no format found for the specified class, the default format for java.lang.Object is returned.

Parameters:

forClass - the class for which a compatible format is returned.

Returns:

the most specialized format compatible with the specified class.

getInstance

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

Returns the current format for instances of the specified class.

Parameters:

forClass - the class to which a format has been bound.

Returns:

the most specialized format compatible with the specified class.

setInstance

public static <T> void setInstance(java.lang.Class<? extends T> forClass,
                                   TextFormat<T> format)

Overrides the default format for the specified class (local setting).

Parameters:

forClass - the class for which the format is locally overriden.

format - the new format (typically unbound).

Throws:

java.lang.IllegalArgumentException - if the speficied class has not default format defined.

isParsingSupported

public boolean isParsingSupported()

Indicates if this format supports parsing (default true).

Returns:

false if any of the parse method throws UnsupportedOperationException

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 TextBuilder 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.

formatToString

public final java.lang.String formatToString(T obj)

Convenience methods equivalent to but faster than format(obj).toString())

Parameters:

obj - the object being formated.

Returns:

the string 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).