| java.lang.Object
 org.joda.time.format.DateTimeFormatter
| DateTimeFormatter | | public class DateTimeFormatter (Code) | | 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:
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
DateTimeFormatter.isPrinter() and
DateTimeFormatter.isParser() methods.
The underlying printer/parser can be altered to behave exactly as required
by using one of the decorator modifiers:
Each of these returns a new formatter (instances of this class are immutable).
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);
author:
Brian S O'Neill
author:
Stephen Colebourne
author:
Fredrik Borgh
since:
1.0 |
| Method Summary | |
| public Chronology | getChronolgy()
Gets the chronology to use as an override. | | public Locale | getLocale()
Gets the locale that will be used for printing and parsing. | | public DateTimeParser | getParser()
Gets the internal parser object that performs the real parsing work. | | public Integer | getPivotYear()
Gets the pivot year to use as an override. | | public DateTimePrinter | getPrinter()
Gets the internal printer object that performs the real printing work. | | public DateTimeZone | getZone()
Gets the zone to use as an override. | | public boolean | isOffsetParsed()
Checks whether the offset from the string is used as the zone of
the parsed datetime. | | public boolean | isParser()
Is this formatter capable of parsing. | | public boolean | isPrinter()
Is this formatter capable of printing. | | public DateTime | parseDateTime(String text)
Parses a datetime from the given text, returning a new DateTime. | | public 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. | | public long | parseMillis(String text)
Parses a datetime from the given text, returning the number of
milliseconds since the epoch, 1970-01-01T00:00:00Z. | | public MutableDateTime | parseMutableDateTime(String text)
Parses a datetime from the given text, returning a new MutableDateTime. | | public String | print(ReadableInstant instant)
Prints a ReadableInstant to a String.
This method will use the override zone and the override chronololgy if
they are set. | | public String | print(long instant)
Prints a millisecond instant to a String.
This method will use the override zone and the override chronololgy if
they are set. | | public String | print(ReadablePartial partial)
Prints a ReadablePartial to a new String. | | public void | printTo(StringBuffer buf, ReadableInstant instant)
Prints a ReadableInstant, using the chronology supplied by the instant. | | public void | printTo(Writer out, ReadableInstant instant)
Prints a ReadableInstant, using the chronology supplied by the instant. | | public void | printTo(StringBuffer buf, long instant)
Prints an instant from milliseconds since 1970-01-01T00:00:00Z,
using ISO chronology in the default DateTimeZone. | | public void | printTo(Writer out, long instant)
Prints an instant from milliseconds since 1970-01-01T00:00:00Z,
using ISO chronology in the default DateTimeZone. | | public void | printTo(StringBuffer buf, ReadablePartial partial)
Prints a ReadablePartial. | | public void | printTo(Writer out, ReadablePartial partial)
Prints a ReadablePartial. | | public 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. | | public DateTimeFormatter | withLocale(Locale locale)
Returns a new formatter with a different locale that will be used
for printing and parsing. | | public 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.
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). | | public 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.
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. | | public 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.
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. | | public 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. |
| DateTimeFormatter | | public DateTimeFormatter(DateTimePrinter printer, DateTimeParser parser)(Code) | | Creates a new formatter, however you will normally use the factory
or the builder.
Parameters:
printer - the internal printer, null if cannot print
Parameters:
parser - the internal parser, null if cannot parse |
| getChronolgy | | public Chronology getChronolgy()(Code) | | Gets the chronology to use as an override.
the chronology to use as an override |
| getLocale | | public Locale getLocale()(Code) | | Gets the locale that will be used for printing and parsing.
the locale to use; if null, formatter uses default locale atinvocation time |
| getParser | | public DateTimeParser getParser()(Code) | | Gets the internal parser object that performs the real parsing work.
the internal parser; is null if parsing not supported |
| getPivotYear | | public Integer getPivotYear()(Code) | | Gets the pivot year to use as an override.
the pivot year to use as an override
since:
1.1 |
| getPrinter | | public DateTimePrinter getPrinter()(Code) | | Gets the internal printer object that performs the real printing work.
the internal printer; is null if printing not supported |
| getZone | | public DateTimeZone getZone()(Code) | | Gets the zone to use as an override.
the zone to use as an override |
| isOffsetParsed | | public boolean isOffsetParsed()(Code) | | Checks whether the offset from the string is used as the zone of
the parsed datetime.
true if the offset from the string is used as the zone |
| isParser | | public boolean isParser()(Code) | | Is this formatter capable of parsing.
true if this is a parser |
| isPrinter | | public boolean isPrinter()(Code) | | Is this formatter capable of printing.
true if this is a printer |
| parseDateTime | | public DateTime parseDateTime(String text)(Code) | | Parses a datetime from the given text, returning a new DateTime.
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
DateTimeFormatter.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.
Parameters:
text - the text to parse parsed value in a DateTime object
throws:
UnsupportedOperationException - if parsing is not supported
throws:
IllegalArgumentException - if the text to parse is invalid |
| parseInto | | public int parseInto(ReadWritableInstant instant, String text, int position)(Code) | | 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 and in this case those fields
that were read will be set.
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
DateTimeFormatter.parseDateTime(String) or
DateTimeFormatter.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.
Parameters:
instant - an instant that will be modified, not null
Parameters:
text - the text to parse
Parameters:
position - position to start parsing from new position, negative value means parse failed -apply complement operator (~) to get position of failure
throws:
UnsupportedOperationException - if parsing is not supported
throws:
IllegalArgumentException - if the instant is null
throws:
IllegalArgumentException - if any field is out of range |
| parseMillis | | public long parseMillis(String text)(Code) | | Parses a datetime from the given text, returning the number of
milliseconds since the epoch, 1970-01-01T00:00:00Z.
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.
Parameters:
text - text to parse parsed value expressed in milliseconds since the epoch
throws:
UnsupportedOperationException - if parsing is not supported
throws:
IllegalArgumentException - if the text to parse is invalid |
| parseMutableDateTime | | public MutableDateTime parseMutableDateTime(String text)(Code) | | Parses a datetime from the given text, returning a new MutableDateTime.
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
DateTimeFormatter.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.
Parameters:
text - the text to parse parsed value in a MutableDateTime object
throws:
UnsupportedOperationException - if parsing is not supported
throws:
IllegalArgumentException - if the text to parse is invalid |
| print | | public String print(ReadableInstant instant)(Code) | | Prints a ReadableInstant to a String.
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.
Parameters:
instant - instant to format, null means now the printed result |
| print | | public String print(long instant)(Code) | | Prints a millisecond instant to a String.
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.
Parameters:
instant - millis since 1970-01-01T00:00:00Z the printed result |
| print | | public String print(ReadablePartial partial)(Code) | | Prints a ReadablePartial to a new String.
Neither the override chronology nor the override zone are used
by this method.
Parameters:
partial - partial to format the printed result |
| printTo | | public void printTo(StringBuffer buf, ReadableInstant instant)(Code) | | Prints a ReadableInstant, using the chronology supplied by the instant.
Parameters:
buf - formatted instant is appended to this buffer
Parameters:
instant - instant to format, null means now |
| printTo | | public void printTo(Writer out, ReadableInstant instant) throws IOException(Code) | | Prints a ReadableInstant, using the chronology supplied by the instant.
Parameters:
out - formatted instant is written out
Parameters:
instant - instant to format, null means now |
| printTo | | public void printTo(StringBuffer buf, long instant)(Code) | | Prints an instant from milliseconds since 1970-01-01T00:00:00Z,
using ISO chronology in the default DateTimeZone.
Parameters:
buf - formatted instant is appended to this buffer
Parameters:
instant - millis since 1970-01-01T00:00:00Z |
| printTo | | public void printTo(Writer out, long instant) throws IOException(Code) | | Prints an instant from milliseconds since 1970-01-01T00:00:00Z,
using ISO chronology in the default DateTimeZone.
Parameters:
out - formatted instant is written out
Parameters:
instant - millis since 1970-01-01T00:00:00Z |
| printTo | | public void printTo(StringBuffer buf, ReadablePartial partial)(Code) | | Prints a ReadablePartial.
Neither the override chronology nor the override zone are used
by this method.
Parameters:
buf - formatted partial is appended to this buffer
Parameters:
partial - partial to format |
| printTo | | public void printTo(Writer out, ReadablePartial partial) throws IOException(Code) | | Prints a ReadablePartial.
Neither the override chronology nor the override zone are used
by this method.
Parameters:
out - formatted partial is written out
Parameters:
partial - partial to format |
| withChronology | | public DateTimeFormatter withChronology(Chronology chrono)(Code) | | Returns a new formatter that will use the specified chronology in
preference to that of the printed object, or ISO on a parse.
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.
Parameters:
chrono - the chronology to use as an override the new formatter |
| withLocale | | public DateTimeFormatter withLocale(Locale locale)(Code) | | Returns a new formatter with a different locale that will be used
for printing and parsing.
A DateTimeFormatter is immutable, so a new instance is returned,
and the original is unaltered and still usable.
Parameters:
locale - the locale to use; if null, formatter uses default localeat invocation time the new formatter |
| withOffsetParsed | | public DateTimeFormatter withOffsetParsed()(Code) | | Returns a new formatter that will create a datetime with a time zone
equal to that of the offset of the parsed string.
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.
the new formatter |
| withPivotYear | | public DateTimeFormatter withPivotYear(Integer pivotYear)(Code) | | Returns a new formatter that will use the specified pivot year for two
digit year parsing in preference to that stored in the parser.
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
Parameters:
pivotYear - the pivot year to use as an override when parsing the new formatter
since:
1.1 |
| withPivotYear | | public DateTimeFormatter withPivotYear(int pivotYear)(Code) | | Returns a new formatter that will use the specified pivot year for two
digit year parsing in preference to that stored in the parser.
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
Parameters:
pivotYear - the pivot year to use as an override when parsing the new formatter
since:
1.1 |
| withZone | | public DateTimeFormatter withZone(DateTimeZone zone)(Code) | | 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.
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.
Parameters:
zone - the zone to use as an override the new formatter |
|
|