javolution.text

Class TextFormat<T>

java.lang.Object

javolution.text.TextFormat<T>

Direct Known Subclasses:

FastCollection.Format, Index.Decimal

@Parallelizable
public abstract class TextFormat<T>
extends Object

The service for plain text parsing and formatting; it supports CharSequence and Appendable interfaces for greater flexibility.

Instances of this class are typically retrieved from the current TextContext (OSGi service or not).

 @DefaultTextFormat(Complex.Cartesian.class) 
 public class Complex extends Number {
     public static Complex valueOf(CharSequence csq) {
         return TextContext.getFormat(Complex.class).parse(csq);
     }
     public String toString() {
         return TextContext.getFormat(Complex.class).format(this);
     }
     public static class Cartesian extends javolution.text.TextFormat<Complex> { ... }
     public static class Polar extends javolution.text.TextFormat<Complex> { ... }
 }

Text formats can be locally overridden.

 TextContext ctx = TextContext.enter();
 try {
      ctx.setFormat(Complex.class, Complex.Polar.class); // No impact on others threads.
      System.out.println(complexMatrix); // Displays complex numbers in polar coordinates.
 } finally {
      ctx.exit(); // Reverts to previous cartesian format for complex numbers.
 }

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

Version:

6.0, July 21, 2013

Author:

Jean-Marie Dautelle

Constructor Summary

Constructors

Constructor and Description
TextFormat()

Method Summary

Methods

Modifier and Type	Method and Description
String	format(T obj) Convenience method to format the specified object to a String.
abstract Appendable	format(T obj, Appendable dest) Formats the specified object into an Appendable
TextBuilder	format(T obj, TextBuilder dest) Convenience method to format the specified object to a TextBuilder; unlike the abstract format method, this method does not throw IOException.
T	parse(CharSequence csq) Convenience method to parse the whole character sequence; if there are unread extraneous characters after parsing then an exception is raised.
abstract T	parse(CharSequence csq, Cursor cursor) Reads a portion of the specified CharSequence from the specified cursor position to produce an object.

Methods inherited from class java.lang.Object

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

Constructor Detail

TextFormat

public TextFormat()

Method Detail

parse

public abstract T parse(CharSequence csq,
      Cursor cursor)

Reads a portion of the specified CharSequence from the specified cursor 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 character sequence to parse.

cursor - the cursor holding the current parsing index.

Returns:

the object parsed.

Throws:

IllegalArgumentException - if the syntax of the specified character sequence is incorrect.

UnsupportedOperationException - if parsing is not supported.

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

parse

public T parse(CharSequence csq)
        throws IllegalArgumentException

Convenience method to parse the whole character sequence; if there are unread extraneous characters after parsing then an exception is raised.

Parameters:

csq - the CharSequence to parse from the first character to the last.

Throws:

IllegalArgumentException - if the syntax of the specified character sequence is incorrect or if there are extraneous characters at the end not parsed.

format

public TextBuilder format(T obj,
                 TextBuilder dest)

Convenience method to format the specified object to a TextBuilder; unlike the abstract format method, this method does not throw IOException.

Parameters:

obj - the object to format.

dest - the appendable destination.

Returns:

the specified TextBuilder.

format

public String format(T obj)

Convenience method to format the specified object to a String.

Parameters:

obj - the object to format.

Returns:

the formatting result as a string.