org.joda.time.format.DateTimeFormatter
|
|||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||||
java.lang.Object
Controls the printing and parsing of a datetime to and from a string.
This class is the main API for printing and parsing used by most applications. Instances of this class are created via one of three factory classes:
DateTimeFormat - formats by pattern and styleISODateTimeFormat - ISO8601 formatsDateTimeFormatterBuilder - complex formats created via method calls
An instance of this class holds a reference internally to one printer and
one parser. It is possible that one of these may be null, in which case the
formatter cannot print/parse. This can be checked via the isPrinter()
and isParser() methods.
The underlying printer/parser can be altered to behave exactly as required by using one of the decorator modifiers:
withLocale(Locale) - returns a new formatter that uses the specified localewithZone(DateTimeZone) - returns a new formatter that uses the specified time zonewithChronology(Chronology) - returns a new formatter that uses the specified chronologywithOffsetParsed() - returns a new formatter that returns the parsed time zone offset
The main methods of the class are the printXxx and
parseXxx methods. These are used as follows:
// print using the defaults (default locale, chronology/zone of the datetime)
String dateStr = formatter.print(dt);
// print using the French locale
String dateStr = formatter.withLocale(Locale.FRENCH).print(dt);
// print using the UTC zone
String dateStr = formatter.withZone(DateTimeZone.UTC).print(dt);
// parse using the Paris zone
DateTime date = formatter.withZone(DateTimeZone.forID("Europe/Paris")).parseDateTime(str);
| Constructor Summary | |
DateTimeFormatter(DateTimePrinter printer,
DateTimeParser parser)
Creates a new formatter, however you will normally use the factory or the builder. |
|
| Method Summary | |
Chronology |
getChronolgy()
Gets the chronology to use as an override. |
Locale |
getLocale()
Gets the locale that will be used for printing and parsing. |
DateTimeParser |
getParser()
Gets the internal parser object that performs the real parsing work. |
Integer |
getPivotYear()
Gets the pivot year to use as an override. |
DateTimePrinter |
getPrinter()
Gets the internal printer object that performs the real printing work. |
DateTimeZone |
getZone()
Gets the zone to use as an override. |
boolean |
isOffsetParsed()
Checks whether the offset from the string is used as the zone of the parsed datetime. |
boolean |
isParser()
Is this formatter capable of parsing. |
boolean |
isPrinter()
Is this formatter capable of printing. |
DateTime |
parseDateTime(String text)
Parses a datetime from the given text, returning a new DateTime. |
int |
parseInto(ReadWritableInstant instant,
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(String text)
Parses a datetime from the given text, returning the number of milliseconds since the epoch, 1970-01-01T00:00:00Z. |
MutableDateTime |
parseMutableDateTime(String text)
Parses a datetime from the given text, returning a new MutableDateTime. |
String |
print(long instant)
Prints a millisecond instant to a String. |
String |
print(ReadableInstant instant)
Prints a ReadableInstant to a String. |
String |
print(ReadablePartial partial)
Prints a ReadablePartial to a new String. |
void |
printTo(StringBuffer buf,
long instant)
Prints an instant from milliseconds since 1970-01-01T00:00:00Z, using ISO chronology in the default DateTimeZone. |
void |
printTo(StringBuffer buf,
ReadableInstant instant)
Prints a ReadableInstant, using the chronology supplied by the instant. |
void |
printTo(StringBuffer buf,
ReadablePartial partial)
Prints a ReadablePartial. |
void |
printTo(Writer out,
long instant)
Prints an instant from milliseconds since 1970-01-01T00:00:00Z, using ISO chronology in the default DateTimeZone. |
void |
printTo(Writer out,
ReadableInstant instant)
Prints a ReadableInstant, using the chronology supplied by the instant. |
void |
printTo(Writer out,
ReadablePartial partial)
Prints a ReadablePartial. |
DateTimeFormatter |
withChronology(Chronology chrono)
Returns a new formatter that will use the specified chronology in preference to that of the printed object, or ISO on a parse. |
DateTimeFormatter |
withLocale(Locale locale)
Returns a new formatter with a different locale that will be used for printing and parsing. |
DateTimeFormatter |
withOffsetParsed()
Returns a new formatter that will create a datetime with a time zone equal to that of the offset of the parsed string. |
DateTimeFormatter |
withPivotYear(int pivotYear)
Returns a new formatter that will use the specified pivot year for two digit year parsing in preference to that stored in the parser. |
DateTimeFormatter |
withPivotYear(Integer pivotYear)
Returns a new formatter that will use the specified pivot year for two digit year parsing in preference to that stored in the parser. |
DateTimeFormatter |
withZone(DateTimeZone zone)
Returns a new formatter that will use the specified zone in preference to the zone of the printed object, or default zone on a parse. |
| Methods inherited from class java.lang.Object |
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
| Constructor Detail |
public DateTimeFormatter(DateTimePrinter printer,
DateTimeParser parser)
printer - the internal printer, null if cannot printparser - the internal parser, null if cannot parse| Method Detail |
public boolean isPrinter()
public DateTimePrinter getPrinter()
public boolean isParser()
public DateTimeParser getParser()
public DateTimeFormatter withLocale(Locale locale)
A DateTimeFormatter is immutable, so a new instance is returned, and the original is unaltered and still usable.
locale - the locale to use; if null, formatter uses default locale
at invocation time
public Locale getLocale()
public DateTimeFormatter withOffsetParsed()
After calling this method, a string '2004-06-09T10:20:30-08:00' will create a datetime with a zone of -08:00 (a fixed zone, with no daylight savings rules). If the parsed string represents a local time (no zone offset) the parsed datetime will be in the default zone.
Calling this method sets the override zone to null. Calling the override zone method sets this flag off.
public boolean isOffsetParsed()
public DateTimeFormatter withChronology(Chronology chrono)
When printing, this chronolgy will be used in preference to the chronology from the datetime that would otherwise be used.
When parsing, this chronology will be set on the parsed datetime.
A null chronology means no-override. If both an override chronology and an override zone are set, the override zone will take precedence over the zone in the chronology.
chrono - the chronology to use as an override
public Chronology getChronolgy()
public DateTimeFormatter withZone(DateTimeZone zone)
When printing, this zone will be used in preference to the zone from the datetime that would otherwise be used.
When parsing, this zone will be set on the parsed datetime.
A null zone means of no-override. If both an override chronology and an override zone are set, the override zone will take precedence over the zone in the chronology.
zone - the zone to use as an override
public DateTimeZone getZone()
public DateTimeFormatter withPivotYear(Integer pivotYear)
This setting is useful for changing the pivot year of formats built
using a pattern - DateTimeFormat.forPattern(String).
When parsing, this pivot year is used. Null means no-override. There is no effect when printing.
The pivot year enables a two digit year to be converted to a four
digit year. The pivot represents the year in the middle of the
supported range of years. Thus the full range of years that will
be built is (pivot - 50) .. (pivot + 49).
pivot supported range 00 is 20 is 40 is 60 is 80 is --------------------------------------------------------------- 1950 1900..1999 1900 1920 1940 1960 1980 1975 1925..2024 2000 2020 1940 1960 1980 2000 1950..2049 2000 2020 2040 1960 1980 2025 1975..2074 2000 2020 2040 2060 1980 2050 2000..2099 2000 2020 2040 2060 2080
pivotYear - the pivot year to use as an override when parsing
public DateTimeFormatter withPivotYear(int pivotYear)
This setting is useful for changing the pivot year of formats built
using a pattern - DateTimeFormat.forPattern(String).
When parsing, this pivot year is used. There is no effect when printing.
The pivot year enables a two digit year to be converted to a four
digit year. The pivot represents the year in the middle of the
supported range of years. Thus the full range of years that will
be built is (pivot - 50) .. (pivot + 49).
pivot supported range 00 is 20 is 40 is 60 is 80 is --------------------------------------------------------------- 1950 1900..1999 1900 1920 1940 1960 1980 1975 1925..2024 2000 2020 1940 1960 1980 2000 1950..2049 2000 2020 2040 1960 1980 2025 1975..2074 2000 2020 2040 2060 1980 2050 2000..2099 2000 2020 2040 2060 2080
pivotYear - the pivot year to use as an override when parsing
public Integer getPivotYear()
public void printTo(StringBuffer buf,
ReadableInstant instant)
buf - formatted instant is appended to this bufferinstant - instant to format, null means now
public void printTo(Writer out,
ReadableInstant instant)
throws IOException
out - formatted instant is written outinstant - instant to format, null means now
IOException
public void printTo(StringBuffer buf,
long instant)
buf - formatted instant is appended to this bufferinstant - millis since 1970-01-01T00:00:00Z
public void printTo(Writer out,
long instant)
throws IOException
out - formatted instant is written outinstant - millis since 1970-01-01T00:00:00Z
IOException
public void printTo(StringBuffer buf,
ReadablePartial partial)
Neither the override chronology nor the override zone are used by this method.
buf - formatted partial is appended to this bufferpartial - partial to format
public void printTo(Writer out,
ReadablePartial partial)
throws IOException
Neither the override chronology nor the override zone are used by this method.
out - formatted partial is written outpartial - partial to format
IOExceptionpublic String print(ReadableInstant instant)
This method will use the override zone and the override chronololgy if they are set. Otherwise it will use the chronology and zone of the instant.
instant - instant to format, null means now
public String print(long instant)
This method will use the override zone and the override chronololgy if they are set. Otherwise it will use the ISO chronology and default zone.
instant - millis since 1970-01-01T00:00:00Z
public String print(ReadablePartial partial)
Neither the override chronology nor the override zone are used by this method.
partial - partial to format
public int parseInto(ReadWritableInstant instant,
String text,
int position)
Only those fields present in the string will be changed in the specified
instant. All other fields will remain unaltered. Thus if the string only
contains a year and a month, then the day and time will be retained from
the input instant. If this is not the behaviour you want, then reset the
fields before calling this method, or use parseDateTime(String)
or parseMutableDateTime(String).
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.
The parse will use the chronology of the instant.
instant - an instant that will be modified, not nulltext - the text to parseposition - position to start parsing from
UnsupportedOperationException - if parsing is not supported
IllegalArgumentException - if the instant is null
IllegalArgumentException - if any field is out of rangepublic long parseMillis(String text)
The parse will use the ISO chronology, and the default time zone. If the text contains a time zone string then that will be taken into account.
text - text to parse
UnsupportedOperationException - if parsing is not supported
IllegalArgumentException - if the text to parse is invalidpublic DateTime parseDateTime(String text)
The parse will use the zone and chronology specified on this formatter.
If the text contains a time zone string then that will be taken into
account in adjusting the time of day as follows.
If the withOffsetParsed() has been called, then the resulting
DateTime will have a fixed offset based on the parsed time zone.
Otherwise the resulting DateTime will have the zone of this formatter,
but the parsed zone may have caused the time to be adjusted.
text - the text to parse
UnsupportedOperationException - if parsing is not supported
IllegalArgumentException - if the text to parse is invalidpublic MutableDateTime parseMutableDateTime(String text)
The parse will use the zone and chronology specified on this formatter.
If the text contains a time zone string then that will be taken into
account in adjusting the time of day as follows.
If the withOffsetParsed() has been called, then the resulting
DateTime will have a fixed offset based on the parsed time zone.
Otherwise the resulting DateTime will have the zone of this formatter,
but the parsed zone may have caused the time to be adjusted.
text - the text to parse
UnsupportedOperationException - if parsing is not supported
IllegalArgumentException - if the text to parse is invalid
|
|||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||||