org.joda.time.format
Interface DateTimeFormatter

All Superinterfaces:

DateTimeParser, DateTimePrinter

public interface DateTimeFormatter

extends DateTimePrinter, DateTimeParser

Combined interface for printing and parsing.

Author:

Brian S O'Neill

Method Summary

int	estimateParsedLength() Returns the expected maximum number of characters consumed.
int	estimatePrintedLength() Returns the expected maximum number of characters produced.
Chronology	getChronology() Returns the Chronology being used by the formatter, or null if none.
DateTime	parseDateTime(java.lang.String text) Parses a datetime from the given text, returning a new DateTime.
int	parseInto(DateTimeParserBucket bucket, java.lang.String text, int position) Parse an element from the given text, saving any fields into the given DateTimeParserBucket.
int	parseInto(ReadWritableInstant instant, java.lang.String text, int position) Parses a datetime from the given text, at the given position, saving the result into the fields of the given ReadWritableInstant.
long	parseMillis(java.lang.String text) Parses a datetime from the given text, returning the number of milliseconds since the epoch, 1970-01-01T00:00:00Z.
long	parseMillis(java.lang.String text, long millis) Parses a datetime from the given text, at the given position, returning the number of milliseconds since the epoch, 1970-01-01T00:00:00Z.
MutableDateTime	parseMutableDateTime(java.lang.String text) Parses a datetime from the given text, returning a new MutableDateTime.
java.lang.String	print(long millisUTC) Prints an instant from milliseconds since 1970-01-01T00:00:00Z, using the formatter's DateTimeZone.
java.lang.String	print(long millisUTC, DateTimeZone zone) Prints an instant from milliseconds since 1970-01-01T00:00:00Z, attempting to use the given DateTimeZone.
java.lang.String	print(long millisUTC, DateTimeZone zone, long millisLocal) Prints an instant from milliseconds since 1970-01-01T00:00:00Z, attempting to use the given DateTimeZone.
java.lang.String	print(ReadableInstant instant) Prints a ReadableInstant to a new String, attempting to use the DateTimeZone supplied by the instant.
void	printTo(java.lang.StringBuffer buf, long millisUTC) Prints an instant from milliseconds since 1970-01-01T00:00:00Z, using the formatter's DateTimeZone.
void	printTo(java.lang.StringBuffer buf, long millisUTC, DateTimeZone zone) Prints an instant from milliseconds since 1970-01-01T00:00:00Z, attempting to use the given DateTimeZone.
void	printTo(java.lang.StringBuffer buf, long millisUTC, DateTimeZone zone, long millisLocal) Prints an instant from milliseconds since 1970-01-01T00:00:00Z, attempting to use the given DateTimeZone.
void	printTo(java.lang.StringBuffer buf, ReadableInstant instant) Prints a ReadableInstant, attempting to use the DateTimeZone supplied by the instant.
void	printTo(java.io.Writer out, long millisUTC) Prints an instant from milliseconds since 1970-01-01T00:00:00Z, using the formatter's DateTimeZone.
void	printTo(java.io.Writer out, long millisUTC, DateTimeZone zone) Prints an instant from milliseconds since 1970-01-01T00:00:00Z, attempting to use the given DateTimeZone.
void	printTo(java.io.Writer out, long millisUTC, DateTimeZone zone, long millisLocal) Prints an instant from milliseconds since 1970-01-01T00:00:00Z, attempting to use the given DateTimeZone.
void	printTo(java.io.Writer out, ReadableInstant instant) Prints a ReadableInstant, attempting to use the DateTimeZone supplied by the instant.

Method Detail

getChronology

public Chronology getChronology()

Returns the Chronology being used by the formatter, or null if none.

Specified by:

getChronology in interface DateTimePrinter

estimatePrintedLength

public int estimatePrintedLength()

Returns the expected maximum number of characters produced. The actual amount should rarely exceed this estimate.

Specified by:

estimatePrintedLength in interface DateTimePrinter

printTo

public void printTo(java.lang.StringBuffer buf,
                    ReadableInstant instant)

Prints a ReadableInstant, attempting to use the DateTimeZone supplied by the instant.

Specified by:

printTo in interface DateTimePrinter

Parameters:

buf - formatted instant is appended to this buffer

instant - instant to format

printTo

public void printTo(java.io.Writer out,
                    ReadableInstant instant)
             throws java.io.IOException

Prints a ReadableInstant, attempting to use the DateTimeZone supplied by the instant.

Specified by:

printTo in interface DateTimePrinter

Parameters:

out - formatted instant is written out

instant - instant to format

java.io.IOException

printTo

public void printTo(java.lang.StringBuffer buf,
                    long millisUTC)

Prints an instant from milliseconds since 1970-01-01T00:00:00Z, using the formatter's DateTimeZone.

Specified by:

printTo in interface DateTimePrinter

Parameters:

buf - formatted instant is appended to this buffer

millisUTC - millis since 1970-01-01T00:00:00Z

printTo

public void printTo(java.io.Writer out,
                    long millisUTC)
             throws java.io.IOException

Prints an instant from milliseconds since 1970-01-01T00:00:00Z, using the formatter's DateTimeZone.

Specified by:

printTo in interface DateTimePrinter

Parameters:

out - formatted instant is written out

millisUTC - millis since 1970-01-01T00:00:00Z

java.io.IOException

printTo

public void printTo(java.lang.StringBuffer buf,
                    long millisUTC,
                    DateTimeZone zone)

Prints an instant from milliseconds since 1970-01-01T00:00:00Z, attempting to use the given DateTimeZone.

Specified by:

printTo in interface DateTimePrinter

Parameters:

buf - formatted instant is appended to this buffer

millisUTC - millis since 1970-01-01T00:00:00Z

zone - DateTimeZone to use, overriding the formatter's own zone if not null

printTo

public void printTo(java.io.Writer out,
                    long millisUTC,
                    DateTimeZone zone)
             throws java.io.IOException

Prints an instant from milliseconds since 1970-01-01T00:00:00Z, attempting to use the given DateTimeZone.

Specified by:

printTo in interface DateTimePrinter

Parameters:

out - formatted instant is written out

millisUTC - millis since 1970-01-01T00:00:00Z

zone - DateTimeZone to use, overriding the formatter's own zone if not null

java.io.IOException

printTo

public void printTo(java.lang.StringBuffer buf,
                    long millisUTC,
                    DateTimeZone zone,
                    long millisLocal)

Prints an instant from milliseconds since 1970-01-01T00:00:00Z, attempting to use the given DateTimeZone.

Specified by:

printTo in interface DateTimePrinter

Parameters:

buf - formatted instant is appended to this buffer

millisUTC - millis since 1970-01-01T00:00:00Z, used by time zone printers

zone - DateTimeZone to use, overriding the formatter's own zone if not null

millisLocal - pre-calculated millis since 1970-01-01T00:00:00, local time

printTo

public void printTo(java.io.Writer out,
                    long millisUTC,
                    DateTimeZone zone,
                    long millisLocal)
             throws java.io.IOException

Prints an instant from milliseconds since 1970-01-01T00:00:00Z, attempting to use the given DateTimeZone.

Specified by:

printTo in interface DateTimePrinter

Parameters:

out - formatted instant is written out

millisUTC - millis since 1970-01-01T00:00:00Z, used by time zone printers

zone - DateTimeZone to use, overriding the formatter's own zone if not null

millisLocal - pre-calculated millis since 1970-01-01T00:00:00, local time

java.io.IOException

print

public java.lang.String print(ReadableInstant instant)

Prints a ReadableInstant to a new String, attempting to use the DateTimeZone supplied by the instant.

Specified by:

print in interface DateTimePrinter

Parameters:

instant - instant to format

Returns:

the printed result

print

public java.lang.String print(long millisUTC)

Prints an instant from milliseconds since 1970-01-01T00:00:00Z, using the formatter's DateTimeZone.

Specified by:

print in interface DateTimePrinter

Parameters:

millisUTC - millis since 1970-01-01T00:00:00Z

Returns:

the printed result

print

public java.lang.String print(long millisUTC,
                              DateTimeZone zone)

Prints an instant from milliseconds since 1970-01-01T00:00:00Z, attempting to use the given DateTimeZone.

Specified by:

print in interface DateTimePrinter

Parameters:

millisUTC - millis since 1970-01-01T00:00:00Z

zone - DateTimeZone to use, overriding the formatter's own zone if not null

Returns:

the printed result

print

public java.lang.String print(long millisUTC,
                              DateTimeZone zone,
                              long millisLocal)

Prints an instant from milliseconds since 1970-01-01T00:00:00Z, attempting to use the given DateTimeZone.

Specified by:

print in interface DateTimePrinter

Parameters:

millisUTC - millis since 1970-01-01T00:00:00Z

zone - DateTimeZone to use, overriding the formatter's own zone if not null

millisLocal - pre-calculated millis since 1970-01-01T00:00:00, local time

Returns:

the printed result

estimateParsedLength

public int estimateParsedLength()

Returns the expected maximum number of characters consumed. The actual amount should rarely exceed this estimate.

Specified by:

estimateParsedLength in interface DateTimeParser

parseInto

public int parseInto(DateTimeParserBucket bucket,
                     java.lang.String text,
                     int position)

Parse an element from the given text, saving any fields into the given DateTimeParserBucket. If the parse succeeds, the return value is the new text position. Note that the parse may succeed without fully reading the text.

If it fails, the return value is negative. To determine the position where the parse failed, apply the one's complement operator (~) on the return value.

Specified by:

parseInto in interface DateTimeParser

Parameters:

bucket - field are saved into this

text - the text to parse

position - position to start parsing from

Returns:

new position, if negative, parse failed. Apply complement operator (~) to get position of failure

Throws:

java.lang.IllegalArgumentException - if any field is out of range

parseInto

public int parseInto(ReadWritableInstant instant,
                     java.lang.String text,
                     int position)

Parses a datetime from the given text, at the given position, saving the result into the fields of the given ReadWritableInstant. If the parse succeeds, the return value is the new text position. Note that the parse may succeed without fully reading the text.

If it fails, the return value is negative, but the instant may still be modified. To determine the position where the parse failed, apply the one's complement operator (~) on the return value.

Specified by:

parseInto in interface DateTimeParser

Parameters:

instant - an instant that will be modified

text - text to parse

position - position to start parsing from

Returns:

new position, if negative, parse failed. Apply complement operator (~) to get position of failure

Throws:

java.lang.IllegalArgumentException - if any field is out of range

parseMillis

public long parseMillis(java.lang.String text)
                 throws java.text.ParseException

Parses a datetime from the given text, returning the number of milliseconds since the epoch, 1970-01-01T00:00:00Z.

Specified by:

parseMillis in interface DateTimeParser

Parameters:

text - text to parse

Returns:

parsed value expressed in milliseconds since the epoch

Throws:

java.text.ParseException - if any field is out of range

parseMillis

public long parseMillis(java.lang.String text,
                        long millis)
                 throws java.text.ParseException

Parses a datetime from the given text, at the given position, returning the number of milliseconds since the epoch, 1970-01-01T00:00:00Z. An initial millisecond value is passed in, which is relative to the epoch, local time.

Specified by:

parseMillis in interface DateTimeParser

Parameters:

text - text to parse

millis - initial value of millis, relative to the epoch, local time

Returns:

parsed value expressed in milliseconds since the epoch, UTC

Throws:

java.text.ParseException - if any field is out of range

parseDateTime

public DateTime parseDateTime(java.lang.String text)
                       throws java.text.ParseException

Parses a datetime from the given text, returning a new DateTime.

Specified by:

parseDateTime in interface DateTimeParser

Parameters:

text - text to parse

Returns:

parsed value in a DateTime object

Throws:

java.text.ParseException - if any field is out of range

parseMutableDateTime

public MutableDateTime parseMutableDateTime(java.lang.String text)
                                     throws java.text.ParseException

Parses a datetime from the given text, returning a new MutableDateTime.

Specified by:

parseMutableDateTime in interface DateTimeParser

Parameters:

text - text to parse

Returns:

parsed value in a MutabkeDateTime object

Throws:

java.text.ParseException - if any field is out of range