javolution.text
Class TextFormat<T>

Object
  extended by TextFormat<T>

public abstract class TextFormat<T>
extends 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
protected TextFormat(Class<T> forClass)
          Defines the static format bound to the specified 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  Appendable format(T obj, 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).
 String formatToString(T obj)
          Convenience methods equivalent to but faster than format(obj).toString())
static
<T> TextFormat<T>
getDefault(Class<? extends T> forClass)
           Returns the default format for instances of the specified class.
static
<T> TextFormat<T>
getInstance(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(CharSequence csq)
          Parses a whole character sequence from the beginning to produce an object (convenience method).
abstract  T parse(CharSequence csq, Cursor cursor)
          Parses a portion of the specified CharSequence from the specified position to produce an object.
static
<T> void
setInstance(Class<? extends T> forClass, TextFormat<T> format)
          Overrides the default format for the specified class (local setting).
 
Methods inherited from class Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

TextFormat

protected TextFormat(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:
IllegalArgumentException - if the specified class is already bound to another format.
Method Detail

getDefault

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

Returns the default format for instances of the specified class.

A default format exist for the following predefined types:

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(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(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:
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 Appendable format(T obj,
                                  Appendable dest)
                           throws IOException
Formats the specified object into an Appendable

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

parse

public abstract T parse(CharSequence csq,
                        Cursor cursor)
                 throws 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:
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 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(CharSequence csq)
              throws 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:
IllegalArgumentException - if the specified character sequence cannot be fully parsed (e.g. extraneous characters).


Copyright © 2005-2012 Javolution. All Rights Reserved.