org.joda.time.format
Interface DateTimeParser

All Known Subinterfaces:

DateTimeFormatter

public interface DateTimeParser

Converts sequences of human-readable characters into datetimes.

Author:

Brian S O'Neill

See Also:

DateTimeFormatter, DateTimeFormatterBuilder, DateTimeFormat

Method Summary

int	estimateParsedLength() Returns the expected maximum number of characters consumed.
Chronology	getChronology() Returns the Chronology being used by the parser, 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.

Method Detail

getChronology

public Chronology getChronology()

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

estimateParsedLength

public int estimateParsedLength()

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

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.

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.

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.

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.

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.

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.

Parameters:

text - text to parse

Returns:

parsed value in a MutabkeDateTime object

Throws:

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