package org.joda.time.format;
Factory that creates instances of DateTimeFormatter for the ISO8601 standard.
Datetime formatting is performed by the DateTimeFormatterDateTimeFormatDateTimeFormatterBuilder
ISO8601 is the international standard for data interchange. It defines a
framework, rather than an absolute standard. As a result this provider has a
number of methods that represent common uses of the framework. The most common
formats are date, time, and dateTime.
For example, to format a date time in ISO format:
DateTime dt = new DateTime();
DateTimeFormatter fmt = ISODateTimeFormat.dateTime();
String str = fmt.print(dt);
It is important to understand that these formatters are not linked to
the ISOChronology. These formatters may be used with any
chronology, however there may be certain side effects with more unusual
chronologies. For example, the ISO formatters rely on dayOfWeek being
single digit, dayOfMonth being two digit and dayOfYear being three digit.
A chronology with a ten day week would thus cause issues. However, in
general, it is safe to use these formatters with other chronologies.
ISODateTimeFormat is thread-safe and immutable, and the formatters it
returns are as well.
Constructor.
- Since:
- 1.1 (previously private)
Returns a formatter that outputs only those fields specified.
This method examines the fields provided and returns an ISO-style
formatter that best fits. This can be useful for outputting
less-common ISO styles, such as YearMonth (YYYY-MM) or MonthDay (--MM-DD).
The list provided may have overlapping fields, such as dayOfWeek and
dayOfMonth. In this case, the style is chosen based on the following
list, thus in the example, the calendar style is chosen as dayOfMonth
is higher in priority than dayOfWeek:
- monthOfYear - calendar date style
- dayOfYear - ordinal date style
- weekOfWeekYear - week date style
- dayOfMonth - calendar date style
- dayOfWeek - week date style
- year
- weekyear
The supported formats are:
Extended Basic Fields
2005-03-25 20050325 year/monthOfYear/dayOfMonth
2005-03 2005-03 year/monthOfYear
2005--25 2005--25 year/dayOfMonth *
2005 2005 year
--03-25 --0325 monthOfYear/dayOfMonth
--03 --03 monthOfYear
---03 ---03 dayOfMonth
2005-084 2005084 year/dayOfYear
-084 -084 dayOfYear
2005-W12-5 2005W125 weekyear/weekOfWeekyear/dayOfWeek
2005-W-5 2005W-5 weekyear/dayOfWeek *
2005-W12 2005W12 weekyear/weekOfWeekyear
-W12-5 -W125 weekOfWeekyear/dayOfWeek
-W12 -W12 weekOfWeekyear
-W-5 -W-5 dayOfWeek
10:20:30.040 102030.040 hour/minute/second/milli
10:20:30 102030 hour/minute/second
10:20 1020 hour/minute
10 10 hour
-20:30.040 -2030.040 minute/second/milli
-20:30 -2030 minute/second
-20 -20 minute
--30.040 --30.040 second/milli
--30 --30 second
---.040 ---.040 milli *
10-30.040 10-30.040 hour/second/milli *
10:20-.040 1020-.040 hour/minute/milli *
10-30 10-30 hour/second *
10--.040 10--.040 hour/milli *
-20-.040 -20-.040 minute/milli *
plus datetime formats like {date}T{time}
* indiates that this is not an official ISO format and can be excluded
by passing in
strictISO as
true.
This method can side effect the input collection of fields.
If the input collection is modifiable, then each field that was added to
the formatter will be removed from the collection, including any duplicates.
If the input collection is unmodifiable then no side effect occurs.
This side effect processing is useful if you need to know whether all
the fields were converted into the formatter or not. To achieve this,
pass in a modifiable list, and check that it is empty on exit.
- Parameters:
fields the fields to get a formatter for, not null,
updated by the method call unless unmodifiable,
removing those fields built in the formatterextended true to use the extended format (with separators)strictISO true to stick exactly to ISO8601, false to include additional formats- Returns:
- a suitable formatter
- Throws:
java.lang.IllegalArgumentException if there is no format for the fields- Since:
- 1.1
if (fields == null || fields.size() == 0) { int inputSize = workingFields.size();
boolean reducedPrec = false;
reducedPrec = dateByMonth(bld, workingFields, extended, strictISO);
reducedPrec = dateByOrdinal(bld, workingFields, extended, strictISO);
reducedPrec = dateByWeek(bld, workingFields, extended, strictISO);
reducedPrec = dateByMonth(bld, workingFields, extended, strictISO);
reducedPrec = dateByWeek(bld, workingFields, extended, strictISO);
} else if (workingFields.remove(DateTimeFieldType.year())) { boolean datePresent = (workingFields.size() < inputSize);
time(bld, workingFields, extended, strictISO, reducedPrec, datePresent);
Creates a date using the calendar date format.
Specification reference: 5.2.1.
- Parameters:
bld the builderfields the fieldsextended true to use extended formatstrictISO true to only allow ISO formats- Returns:
- true if reduced precision
- Since:
- 1.1
boolean reducedPrec = false;
Creates a date using the ordinal date format.
Specification reference: 5.2.2.
- Parameters:
bld the builderfields the fieldsextended true to use extended formatstrictISO true to only allow ISO formats- Since:
- 1.1
boolean reducedPrec = false;
Creates a date using the calendar date format.
Specification reference: 5.2.3.
- Parameters:
bld the builderfields the fieldsextended true to use extended formatstrictISO true to only allow ISO formats- Since:
- 1.1
boolean reducedPrec = false;
Adds the time fields to the builder.
Specification reference: 5.3.1.
- Parameters:
bld the builderfields the fieldsextended whether to use the extended formatstrictISO whether to be strictreducedPrec whether the date was reduced precisiondatePresent whether there was a date- Since:
- 1.1
private static void time(
if (!hour && !minute && !second && !milli) { if (hour || minute || second || milli) { if (strictISO && reducedPrec) { if (hour && minute && second || (hour && !second && !milli)) { if (strictISO && datePresent) { if (!hour && (minute && second || (minute && !milli) || second)) { } else if (minute || second || milli) { if (extended && hour && minute) { } else if (second || milli) { if (extended && minute && second) { Checks that the iso only flag is not set, throwing an exception if it is.
- Parameters:
fields the fieldsstrictISO true if only ISO formats allowed- Since:
- 1.1
Appends the separator if necessary.
- Parameters:
bld the builderextended whether to append the separatorsep the separator- Since:
- 1.1
Returns a generic ISO date parser for parsing dates with a possible zone.
It accepts formats described by the following syntax:
date = date-element ['T' offset]
date-element = std-date-element | ord-date-element | week-date-element
std-date-element = yyyy ['-' MM ['-' dd]]
ord-date-element = yyyy ['-' DDD]
week-date-element = xxxx '-W' ww ['-' e]
offset = 'Z' | (('+' | '-') HH [':' mm [':' ss [('.' | ',') SSS]]])
Returns a generic ISO date parser for parsing local dates.
This parser is initialised with the local (UTC) time zone.
It accepts formats described by the following syntax:
date-element = std-date-element | ord-date-element | week-date-element
std-date-element = yyyy ['-' MM ['-' dd]]
ord-date-element = yyyy ['-' DDD]
week-date-element = xxxx '-W' ww ['-' e]
Returns a generic ISO date parser for parsing dates.
It accepts formats described by the following syntax:
date-element = std-date-element | ord-date-element | week-date-element
std-date-element = yyyy ['-' MM ['-' dd]]
ord-date-element = yyyy ['-' DDD]
week-date-element = xxxx '-W' ww ['-' e]
Returns a generic ISO time parser for parsing times with a possible zone.
The parser is strict by default, thus time string
24:00 cannot be parsed.
It accepts formats described by the following syntax:
time = ['T'] time-element [offset]
time-element = HH [minute-element] | [fraction]
minute-element = ':' mm [second-element] | [fraction]
second-element = ':' ss [fraction]
fraction = ('.' | ',') digit+
offset = 'Z' | (('+' | '-') HH [':' mm [':' ss [('.' | ',') SSS]]])
Returns a generic ISO time parser for parsing local times.
This parser is initialised with the local (UTC) time zone.
The parser is strict by default, thus time string
24:00 cannot be parsed.
It accepts formats described by the following syntax:
time = ['T'] time-element
time-element = HH [minute-element] | [fraction]
minute-element = ':' mm [second-element] | [fraction]
second-element = ':' ss [fraction]
fraction = ('.' | ',') digit+
Returns a generic ISO time parser.
The parser is strict by default, thus time string
24:00 cannot be parsed.
It accepts formats described by the following syntax:
time-element = HH [minute-element] | [fraction]
minute-element = ':' mm [second-element] | [fraction]
second-element = ':' ss [fraction]
fraction = ('.' | ',') digit+
Returns a generic ISO datetime parser which parses either a date or
a time or both. The parser is strict by default, thus time string
24:00 cannot be parsed.
It accepts formats described by the following syntax:
datetime = time | date-opt-time
time = 'T' time-element [offset]
date-opt-time = date-element ['T' [time-element] [offset]]
date-element = std-date-element | ord-date-element | week-date-element
std-date-element = yyyy ['-' MM ['-' dd]]
ord-date-element = yyyy ['-' DDD]
week-date-element = xxxx '-W' ww ['-' e]
time-element = HH [minute-element] | [fraction]
minute-element = ':' mm [second-element] | [fraction]
second-element = ':' ss [fraction]
fraction = ('.' | ',') digit+
offset = 'Z' | (('+' | '-') HH [':' mm [':' ss [('.' | ',') SSS]]])
Returns a generic ISO datetime parser where the date is mandatory and
the time is optional. This parser can parse zoned datetimes.
The parser is strict by default, thus time string
24:00 cannot be parsed.
It accepts formats described by the following syntax:
date-opt-time = date-element ['T' [time-element] [offset]]
date-element = std-date-element | ord-date-element | week-date-element
std-date-element = yyyy ['-' MM ['-' dd]]
ord-date-element = yyyy ['-' DDD]
week-date-element = xxxx '-W' ww ['-' e]
time-element = HH [minute-element] | [fraction]
minute-element = ':' mm [second-element] | [fraction]
second-element = ':' ss [fraction]
fraction = ('.' | ',') digit+
Returns a generic ISO datetime parser where the date is mandatory and
the time is optional. This parser only parses local datetimes.
This parser is initialised with the local (UTC) time zone.
The parser is strict by default, thus time string
24:00 cannot be parsed.
It accepts formats described by the following syntax:
datetime = date-element ['T' time-element]
date-element = std-date-element | ord-date-element | week-date-element
std-date-element = yyyy ['-' MM ['-' dd]]
ord-date-element = yyyy ['-' DDD]
week-date-element = xxxx '-W' ww ['-' e]
time-element = HH [minute-element] | [fraction]
minute-element = ':' mm [second-element] | [fraction]
second-element = ':' ss [fraction]
fraction = ('.' | ',') digit+
Returns a formatter for a full date as four digit year, two digit month
of year, and two digit day of month (yyyy-MM-dd).
- Returns:
- a formatter for yyyy-MM-dd
Returns a formatter for a two digit hour of day, two digit minute of
hour, two digit second of minute, three digit fraction of second, and
time zone offset (HH:mm:ss.SSSZZ).
The time zone offset is 'Z' for zero, and of the form '\u00b1HH:mm' for non-zero.
The parser is strict by default, thus time string
24:00 cannot be parsed.
- Returns:
- a formatter for HH:mm:ss.SSSZZ
Returns a formatter for a two digit hour of day, two digit minute of
hour, two digit second of minute, and time zone offset (HH:mm:ssZZ).
The time zone offset is 'Z' for zero, and of the form '\u00b1HH:mm' for non-zero.
The parser is strict by default, thus time string
24:00 cannot be parsed.
- Returns:
- a formatter for HH:mm:ssZZ
Returns a formatter for a two digit hour of day, two digit minute of
hour, two digit second of minute, three digit fraction of second, and
time zone offset prefixed by 'T' ('T'HH:mm:ss.SSSZZ).
The time zone offset is 'Z' for zero, and of the form '\u00b1HH:mm' for non-zero.
The parser is strict by default, thus time string
24:00 cannot be parsed.
- Returns:
- a formatter for 'T'HH:mm:ss.SSSZZ
Returns a formatter for a two digit hour of day, two digit minute of
hour, two digit second of minute, and time zone offset prefixed
by 'T' ('T'HH:mm:ssZZ).
The time zone offset is 'Z' for zero, and of the form '\u00b1HH:mm' for non-zero.
The parser is strict by default, thus time string
24:00 cannot be parsed.
- Returns:
- a formatter for 'T'HH:mm:ssZZ
Returns a formatter that combines a full date and time, separated by a 'T'
(yyyy-MM-dd'T'HH:mm:ss.SSSZZ).
The time zone offset is 'Z' for zero, and of the form '\u00b1HH:mm' for non-zero.
The parser is strict by default, thus time string
24:00 cannot be parsed.
- Returns:
- a formatter for yyyy-MM-dd'T'HH:mm:ss.SSSZZ
Returns a formatter that combines a full date and time without millis,
separated by a 'T' (yyyy-MM-dd'T'HH:mm:ssZZ).
The time zone offset is 'Z' for zero, and of the form '\u00b1HH:mm' for non-zero.
The parser is strict by default, thus time string
24:00 cannot be parsed.
- Returns:
- a formatter for yyyy-MM-dd'T'HH:mm:ssZZ
Returns a formatter for a full ordinal date, using a four
digit year and three digit dayOfYear (yyyy-DDD).
- Returns:
- a formatter for yyyy-DDD
- Since:
- 1.1
Returns a formatter for a full ordinal date and time, using a four
digit year and three digit dayOfYear (yyyy-DDD'T'HH:mm:ss.SSSZZ).
The time zone offset is 'Z' for zero, and of the form '\u00b1HH:mm' for non-zero.
The parser is strict by default, thus time string
24:00 cannot be parsed.
- Returns:
- a formatter for yyyy-DDD'T'HH:mm:ss.SSSZZ
- Since:
- 1.1
Returns a formatter for a full ordinal date and time without millis,
using a four digit year and three digit dayOfYear (yyyy-DDD'T'HH:mm:ssZZ).
The time zone offset is 'Z' for zero, and of the form '\u00b1HH:mm' for non-zero.
The parser is strict by default, thus time string
24:00 cannot be parsed.
- Returns:
- a formatter for yyyy-DDD'T'HH:mm:ssZZ
- Since:
- 1.1
Returns a formatter for a full date as four digit weekyear, two digit
week of weekyear, and one digit day of week (xxxx-'W'ww-e).
- Returns:
- a formatter for xxxx-'W'ww-e
Returns a formatter that combines a full weekyear date and time,
separated by a 'T' (xxxx-'W'ww-e'T'HH:mm:ss.SSSZZ).
The time zone offset is 'Z' for zero, and of the form '\u00b1HH:mm' for non-zero.
The parser is strict by default, thus time string
24:00 cannot be parsed.
- Returns:
- a formatter for xxxx-'W'ww-e'T'HH:mm:ss.SSSZZ
Returns a formatter that combines a full weekyear date and time without millis,
separated by a 'T' (xxxx-'W'ww-e'T'HH:mm:ssZZ).
The time zone offset is 'Z' for zero, and of the form '\u00b1HH:mm' for non-zero.
The parser is strict by default, thus time string
24:00 cannot be parsed.
- Returns:
- a formatter for xxxx-'W'ww-e'T'HH:mm:ssZZ
Returns a basic formatter for a full date as four digit year, two digit
month of year, and two digit day of month (yyyyMMdd).
- Returns:
- a formatter for yyyyMMdd
Returns a basic formatter for a two digit hour of day, two digit minute
of hour, two digit second of minute, three digit millis, and time zone
offset (HHmmss.SSSZ).
The time zone offset is 'Z' for zero, and of the form '\u00b1HHmm' for non-zero.
The parser is strict by default, thus time string
24:00 cannot be parsed.
- Returns:
- a formatter for HHmmss.SSSZ
Returns a basic formatter for a two digit hour of day, two digit minute
of hour, two digit second of minute, and time zone offset (HHmmssZ).
The time zone offset is 'Z' for zero, and of the form '\u00b1HHmm' for non-zero.
The parser is strict by default, thus time string
24:00 cannot be parsed.
- Returns:
- a formatter for HHmmssZ
Returns a basic formatter for a two digit hour of day, two digit minute
of hour, two digit second of minute, three digit millis, and time zone
offset prefixed by 'T' ('T'HHmmss.SSSZ).
The time zone offset is 'Z' for zero, and of the form '\u00b1HHmm' for non-zero.
The parser is strict by default, thus time string
24:00 cannot be parsed.
- Returns:
- a formatter for 'T'HHmmss.SSSZ
Returns a basic formatter for a two digit hour of day, two digit minute
of hour, two digit second of minute, and time zone offset prefixed by 'T'
('T'HHmmssZ).
The time zone offset is 'Z' for zero, and of the form '\u00b1HHmm' for non-zero.
The parser is strict by default, thus time string
24:00 cannot be parsed.
- Returns:
- a formatter for 'T'HHmmssZ
Returns a basic formatter that combines a basic date and time, separated
by a 'T' (yyyyMMdd'T'HHmmss.SSSZ).
The time zone offset is 'Z' for zero, and of the form '\u00b1HHmm' for non-zero.
The parser is strict by default, thus time string
24:00 cannot be parsed.
- Returns:
- a formatter for yyyyMMdd'T'HHmmss.SSSZ
Returns a basic formatter that combines a basic date and time without millis,
separated by a 'T' (yyyyMMdd'T'HHmmssZ).
The time zone offset is 'Z' for zero, and of the form '\u00b1HHmm' for non-zero.
The parser is strict by default, thus time string
24:00 cannot be parsed.
- Returns:
- a formatter for yyyyMMdd'T'HHmmssZ
Returns a formatter for a full ordinal date, using a four
digit year and three digit dayOfYear (yyyyDDD).
- Returns:
- a formatter for yyyyDDD
- Since:
- 1.1
Returns a formatter for a full ordinal date and time, using a four
digit year and three digit dayOfYear (yyyyDDD'T'HHmmss.SSSZ).
The time zone offset is 'Z' for zero, and of the form '\u00b1HHmm' for non-zero.
The parser is strict by default, thus time string
24:00 cannot be parsed.
- Returns:
- a formatter for yyyyDDD'T'HHmmss.SSSZ
- Since:
- 1.1
Returns a formatter for a full ordinal date and time without millis,
using a four digit year and three digit dayOfYear (yyyyDDD'T'HHmmssZ).
The time zone offset is 'Z' for zero, and of the form '\u00b1HHmm' for non-zero.
The parser is strict by default, thus time string
24:00 cannot be parsed.
- Returns:
- a formatter for yyyyDDD'T'HHmmssZ
- Since:
- 1.1
Returns a basic formatter for a full date as four digit weekyear, two
digit week of weekyear, and one digit day of week (xxxx'W'wwe).
- Returns:
- a formatter for xxxx'W'wwe
Returns a basic formatter that combines a basic weekyear date and time,
separated by a 'T' (xxxx'W'wwe'T'HHmmss.SSSZ).
The time zone offset is 'Z' for zero, and of the form '\u00b1HHmm' for non-zero.
The parser is strict by default, thus time string
24:00 cannot be parsed.
- Returns:
- a formatter for xxxx'W'wwe'T'HHmmss.SSSZ
Returns a basic formatter that combines a basic weekyear date and time
without millis, separated by a 'T' (xxxx'W'wwe'T'HHmmssZ).
The time zone offset is 'Z' for zero, and of the form '\u00b1HHmm' for non-zero.
The parser is strict by default, thus time string
24:00 cannot be parsed.
- Returns:
- a formatter for xxxx'W'wwe'T'HHmmssZ
Returns a formatter for a four digit year. (yyyy)
- Returns:
- a formatter for yyyy
Returns a formatter for a four digit year and two digit month of
year. (yyyy-MM)
- Returns:
- a formatter for yyyy-MM
Returns a formatter for a four digit year, two digit month of year, and
two digit day of month. (yyyy-MM-dd)
- Returns:
- a formatter for yyyy-MM-dd
Returns a formatter for a four digit weekyear. (xxxx)
- Returns:
- a formatter for xxxx
Returns a formatter for a four digit weekyear and two digit week of
weekyear. (xxxx-'W'ww)
- Returns:
- a formatter for xxxx-'W'ww
Returns a formatter for a four digit weekyear, two digit week of
weekyear, and one digit day of week. (xxxx-'W'ww-e)
- Returns:
- a formatter for xxxx-'W'ww-e
Returns a formatter for a two digit hour of day. (HH)
- Returns:
- a formatter for HH
Returns a formatter for a two digit hour of day and two digit minute of
hour. (HH:mm)
- Returns:
- a formatter for HH:mm
Returns a formatter for a two digit hour of day, two digit minute of
hour, and two digit second of minute. (HH:mm:ss)
- Returns:
- a formatter for HH:mm:ss
Returns a formatter for a two digit hour of day, two digit minute of
hour, two digit second of minute, and three digit fraction of
second (HH:mm:ss.SSS). Parsing will parse up to 3 fractional second
digits.
- Returns:
- a formatter for HH:mm:ss.SSS
Returns a formatter for a two digit hour of day, two digit minute of
hour, two digit second of minute, and three digit fraction of
second (HH:mm:ss.SSS). Parsing will parse up to 9 fractional second
digits, throwing away all except the first three.
- Returns:
- a formatter for HH:mm:ss.SSS
Returns a formatter that combines a full date and two digit hour of
day. (yyyy-MM-dd'T'HH)
- Returns:
- a formatter for yyyy-MM-dd'T'HH
Returns a formatter that combines a full date, two digit hour of day,
and two digit minute of hour. (yyyy-MM-dd'T'HH:mm)
- Returns:
- a formatter for yyyy-MM-dd'T'HH:mm
Returns a formatter that combines a full date, two digit hour of day,
two digit minute of hour, and two digit second of
minute. (yyyy-MM-dd'T'HH:mm:ss)
- Returns:
- a formatter for yyyy-MM-dd'T'HH:mm:ss
Returns a formatter that combines a full date, two digit hour of day,
two digit minute of hour, two digit second of minute, and three digit
fraction of second (yyyy-MM-dd'T'HH:mm:ss.SSS). Parsing will parse up
to 3 fractional second digits.
- Returns:
- a formatter for yyyy-MM-dd'T'HH:mm:ss.SSS
Returns a formatter that combines a full date, two digit hour of day,
two digit minute of hour, two digit second of minute, and three digit
fraction of second (yyyy-MM-dd'T'HH:mm:ss.SSS). Parsing will parse up
to 9 fractional second digits, throwing away all except the first three.
- Returns:
- a formatter for yyyy-MM-dd'T'HH:mm:ss.SSS
0.2.1
