* This allows a {@code DateTimeFormatter} to be created. * All date-time formatters are created ultimately using this builder. *
* The basic elements of date-time can all be added: *
* In addition, any of the elements may be decorated by padding, either with spaces or any other character. *
* Finally, a shorthand pattern, mostly compatible with {@code java.text.SimpleDateFormat SimpleDateFormat} * can be used, see {@link #appendPattern(String)}. * In practice, this simply parses the pattern and calls other methods on the builder. * *
* Parsing can be case sensitive or insensitive - by default it is case sensitive. * This method allows the case sensitivity setting of parsing to be changed. *
* Calling this method changes the state of the builder such that all * subsequent builder method calls will parse text in case sensitive mode. * See {@link #parseCaseInsensitive} for the opposite setting. * The parse case sensitive/insensitive methods may be called at any point * in the builder, thus the parser can swap between case parsing modes * multiple times during the parse. *
* Since the default is case sensitive, this method should only be used after * a previous call to {@code #parseCaseInsensitive}. * * @return this, for chaining, not null */ public DateTimeFormatterBuilder parseCaseSensitive() { appendInternal(SettingsParser.SENSITIVE); return this; } /** * Changes the parse style to be case insensitive for the remainder of the formatter. *
* Parsing can be case sensitive or insensitive - by default it is case sensitive. * This method allows the case sensitivity setting of parsing to be changed. *
* Calling this method changes the state of the builder such that all * subsequent builder method calls will parse text in case insensitive mode. * See {@link #parseCaseSensitive()} for the opposite setting. * The parse case sensitive/insensitive methods may be called at any point * in the builder, thus the parser can swap between case parsing modes * multiple times during the parse. * * @return this, for chaining, not null */ public DateTimeFormatterBuilder parseCaseInsensitive() { appendInternal(SettingsParser.INSENSITIVE); return this; } //----------------------------------------------------------------------- /** * Changes the parse style to be strict for the remainder of the formatter. *
* Parsing can be strict or lenient - by default its strict. * This controls the degree of flexibility in matching the text and sign styles. *
* When used, this method changes the parsing to be strict from this point onwards. * As strict is the default, this is normally only needed after calling {@link #parseLenient()}. * The change will remain in force until the end of the formatter that is eventually * constructed or until {@code parseLenient} is called. * * @return this, for chaining, not null */ public DateTimeFormatterBuilder parseStrict() { appendInternal(SettingsParser.STRICT); return this; } /** * Changes the parse style to be lenient for the remainder of the formatter. * Note that case sensitivity is set separately to this method. *
* Parsing can be strict or lenient - by default its strict. * This controls the degree of flexibility in matching the text and sign styles. * Applications calling this method should typically also call {@link #parseCaseInsensitive()}. *
* When used, this method changes the parsing to be lenient from this point onwards. * The change will remain in force until the end of the formatter that is eventually * constructed or until {@code parseStrict} is called. * * @return this, for chaining, not null */ public DateTimeFormatterBuilder parseLenient() { appendInternal(SettingsParser.LENIENT); return this; } //----------------------------------------------------------------------- /** * Appends the value of a date-time field to the formatter using a normal * output style. *
* The value of the field will be output during a format. * If the value cannot be obtained then an exception will be thrown. *
* The value will be printed as per the normal format of an integer value. * Only negative numbers will be signed. No padding will be added. *
* The parser for a variable width value such as this normally behaves greedily, * requiring one digit, but accepting as many digits as possible. * This behavior can be affected by 'adjacent value parsing'. * See {@link #appendValue(java.time.temporal.TemporalField, int)} for full details. * * @param field the field to append, not null * @return this, for chaining, not null */ public DateTimeFormatterBuilder appendValue(TemporalField field) { Objects.requireNonNull(field, "field"); active.valueParserIndex = appendInternal(new NumberPrinterParser(field, 1, 19, SignStyle.NORMAL)); return this; } /** * Appends the value of a date-time field to the formatter using a fixed * width, zero-padded approach. *
* The value of the field will be output during a format. * If the value cannot be obtained then an exception will be thrown. *
* The value will be zero-padded on the left. If the size of the value * means that it cannot be printed within the width then an exception is thrown. * If the value of the field is negative then an exception is thrown during formatting. *
* This method supports a special technique of parsing known as 'adjacent value parsing'. * This technique solves the problem where a variable length value is followed by one or more * fixed length values. The standard parser is greedy, and thus it would normally * steal the digits that are needed by the fixed width value parsers that follow the * variable width one. *
* No action is required to initiate 'adjacent value parsing'. * When a call to {@code appendValue} with a variable width is made, the builder * enters adjacent value parsing setup mode. If the immediately subsequent method * call or calls on the same builder are to this method, then the parser will reserve * space so that the fixed width values can be parsed. *
* For example, consider {@code builder.appendValue(YEAR).appendValue(MONTH_OF_YEAR, 2);} * The year is a variable width parse of between 1 and 19 digits. * The month is a fixed width parse of 2 digits. * Because these were appended to the same builder immediately after one another, * the year parser will reserve two digits for the month to parse. * Thus, the text '201106' will correctly parse to a year of 2011 and a month of 6. * Without adjacent value parsing, the year would greedily parse all six digits and leave * nothing for the month. *
* Adjacent value parsing applies to each set of fixed width not-negative values in the parser * that immediately follow any kind of variable width value. * Calling any other append method will end the setup of adjacent value parsing. * Thus, in the unlikely event that you need to avoid adjacent value parsing behavior, * simply add the {@code appendValue} to another {@code DateTimeFormatterBuilder} * and add that to this builder. *
* If adjacent parsing is active, then parsing must match exactly the specified * number of digits in both strict and lenient modes. * In addition, no positive or negative sign is permitted. * * @param field the field to append, not null * @param width the width of the printed field, from 1 to 19 * @return this, for chaining, not null * @throws IllegalArgumentException if the width is invalid */ public DateTimeFormatterBuilder appendValue(TemporalField field, int width) { Objects.requireNonNull(field, "field"); if (width < 1 || width > 19) { throw new IllegalArgumentException("The width must be from 1 to 19 inclusive but was " + width); } NumberPrinterParser pp = new NumberPrinterParser(field, width, width, SignStyle.NOT_NEGATIVE); return appendFixedWidth(width, pp); } /** * Appends the value of a date-time field to the formatter providing full * control over formatting. *
* The value of the field will be output during a format. * If the value cannot be obtained then an exception will be thrown. *
* This method provides full control of the numeric formatting, including * zero-padding and the positive/negative sign. *
* The parser for a variable width value such as this normally behaves greedily, * accepting as many digits as possible. * This behavior can be affected by 'adjacent value parsing'. * See {@link #appendValue(java.time.temporal.TemporalField, int)} for full details. *
* In strict parsing mode, the minimum number of parsed digits is {@code minWidth}. * In lenient parsing mode, the minimum number of parsed digits is one. *
* If this method is invoked with equal minimum and maximum widths and a sign style of * {@code NOT_NEGATIVE} then it delegates to {@code appendValue(TemporalField,int)}. * In this scenario, the formatting and parsing behavior described there occur. * * @param field the field to append, not null * @param minWidth the minimum field width of the printed field, from 1 to 19 * @param maxWidth the maximum field width of the printed field, from 1 to 19 * @param signStyle the positive/negative output style, not null * @return this, for chaining, not null * @throws IllegalArgumentException if the widths are invalid */ public DateTimeFormatterBuilder appendValue( TemporalField field, int minWidth, int maxWidth, SignStyle signStyle) { if (minWidth == maxWidth && signStyle == SignStyle.NOT_NEGATIVE) { return appendValue(field, maxWidth); } Objects.requireNonNull(field, "field"); Objects.requireNonNull(signStyle, "signStyle"); if (minWidth < 1 || minWidth > 19) { throw new IllegalArgumentException("The minimum width must be from 1 to 19 inclusive but was " + minWidth); } if (maxWidth < 1 || maxWidth > 19) { throw new IllegalArgumentException("The maximum width must be from 1 to 19 inclusive but was " + maxWidth); } if (maxWidth < minWidth) { throw new IllegalArgumentException("The maximum width must exceed or equal the minimum width but " + maxWidth + " < " + minWidth); } NumberPrinterParser pp = new NumberPrinterParser(field, minWidth, maxWidth, signStyle); if (minWidth == maxWidth) { appendInternal(pp); } else { active.valueParserIndex = appendInternal(pp); } return this; } //----------------------------------------------------------------------- /** * Appends the reduced value of a date-time field to the formatter. *
* This is typically used for formatting and parsing a two digit year. * The {@code width} is the printed and parsed width. * The {@code baseValue} is used during parsing to determine the valid range. *
* For formatting, the width is used to determine the number of characters to format. * The rightmost characters are output to match the width, left padding with zero. *
* For parsing, exactly the number of characters specified by the width are parsed. * This is incomplete information however, so the base value is used to complete the parse. * The base value is the first valid value in a range of ten to the power of width. *
* For example, a base value of {@code 1980} and a width of {@code 2} will have * valid values from {@code 1980} to {@code 2079}. * During parsing, the text {@code "12"} will result in the value {@code 2012} as that * is the value within the range where the last two digits are "12". *
* This is a fixed width parser operating using 'adjacent value parsing'. * See {@link #appendValue(java.time.temporal.TemporalField, int)} for full details. * * @param field the field to append, not null * @param width the width of the printed and parsed field, from 1 to 18 * @param baseValue the base value of the range of valid values * @return this, for chaining, not null * @throws IllegalArgumentException if the width or base value is invalid */ public DateTimeFormatterBuilder appendValueReduced( TemporalField field, int width, int baseValue) { Objects.requireNonNull(field, "field"); ReducedPrinterParser pp = new ReducedPrinterParser(field, width, baseValue); appendFixedWidth(width, pp); return this; } /** * Appends a fixed width printer-parser. * * @param width the width * @param pp the printer-parser, not null * @return this, for chaining, not null */ private DateTimeFormatterBuilder appendFixedWidth(int width, NumberPrinterParser pp) { if (active.valueParserIndex >= 0) { // adjacent parsing mode, update setting in previous parsers NumberPrinterParser basePP = (NumberPrinterParser) active.printerParsers.get(active.valueParserIndex); basePP = basePP.withSubsequentWidth(width); int activeValueParser = active.valueParserIndex; active.printerParsers.set(active.valueParserIndex, basePP); appendInternal(pp.withFixedWidth()); active.valueParserIndex = activeValueParser; } else { // not adjacent parsing appendInternal(pp); } return this; } //----------------------------------------------------------------------- /** * Appends the fractional value of a date-time field to the formatter. *
* The fractional value of the field will be output including the * preceding decimal point. The preceding value is not output. * For example, the second-of-minute value of 15 would be output as {@code .25}. *
* The width of the printed fraction can be controlled. Setting the * minimum width to zero will cause no output to be generated. * The printed fraction will have the minimum width necessary between * the minimum and maximum widths - trailing zeroes are omitted. * No rounding occurs due to the maximum width - digits are simply dropped. *
* When parsing in strict mode, the number of parsed digits must be between * the minimum and maximum width. When parsing in lenient mode, the minimum * width is considered to be zero and the maximum is nine. *
* If the value cannot be obtained then an exception will be thrown. * If the value is negative an exception will be thrown. * If the field does not have a fixed set of valid values then an * exception will be thrown. * If the field value in the date-time to be printed is invalid it * cannot be printed and an exception will be thrown. * * @param field the field to append, not null * @param minWidth the minimum width of the field excluding the decimal point, from 0 to 9 * @param maxWidth the maximum width of the field excluding the decimal point, from 1 to 9 * @param decimalPoint whether to output the localized decimal point symbol * @return this, for chaining, not null * @throws IllegalArgumentException if the field has a variable set of valid values or * either width is invalid */ public DateTimeFormatterBuilder appendFraction( TemporalField field, int minWidth, int maxWidth, boolean decimalPoint) { appendInternal(new FractionPrinterParser(field, minWidth, maxWidth, decimalPoint)); return this; } //----------------------------------------------------------------------- /** * Appends the text of a date-time field to the formatter using the full * text style. *
* The text of the field will be output during a format. * The value must be within the valid range of the field. * If the value cannot be obtained then an exception will be thrown. * If the field has no textual representation, then the numeric value will be used. *
* The value will be printed as per the normal format of an integer value. * Only negative numbers will be signed. No padding will be added. * * @param field the field to append, not null * @return this, for chaining, not null */ public DateTimeFormatterBuilder appendText(TemporalField field) { return appendText(field, TextStyle.FULL); } /** * Appends the text of a date-time field to the formatter. *
* The text of the field will be output during a format. * The value must be within the valid range of the field. * If the value cannot be obtained then an exception will be thrown. * If the field has no textual representation, then the numeric value will be used. *
* The value will be printed as per the normal format of an integer value. * Only negative numbers will be signed. No padding will be added. * * @param field the field to append, not null * @param textStyle the text style to use, not null * @return this, for chaining, not null */ public DateTimeFormatterBuilder appendText(TemporalField field, TextStyle textStyle) { Objects.requireNonNull(field, "field"); Objects.requireNonNull(textStyle, "textStyle"); appendInternal(new TextPrinterParser(field, textStyle, DateTimeTextProvider.getInstance())); return this; } /** * Appends the text of a date-time field to the formatter using the specified * map to supply the text. *
* The standard text outputting methods use the localized text in the JDK. * This method allows that text to be specified directly. * The supplied map is not validated by the builder to ensure that formatting or * parsing is possible, thus an invalid map may throw an error during later use. *
* Supplying the map of text provides considerable flexibility in formatting and parsing. * For example, a legacy application might require or supply the months of the * year as "JNY", "FBY", "MCH" etc. These do not match the standard set of text * for localized month names. Using this method, a map can be created which * defines the connection between each value and the text: *
* Map<Long, String> map = new HashMap<>();
* map.put(1, "JNY");
* map.put(2, "FBY");
* map.put(3, "MCH");
* ...
* builder.appendText(MONTH_OF_YEAR, map);
*
* * Other uses might be to output the value with a suffix, such as "1st", "2nd", "3rd", * or as Roman numerals "I", "II", "III", "IV". *
* During formatting, the value is obtained and checked that it is in the valid range.
* If text is not available for the value then it is output as a number.
* During parsing, the parser will match against the map of text and numeric values.
*
* @param field the field to append, not null
* @param textLookup the map from the value to the text
* @return this, for chaining, not null
*/
public DateTimeFormatterBuilder appendText(TemporalField field, Map
* Instants have a fixed output format.
* They are converted to a date-time with a zone-offset of UTC and printed
* using the standard ISO-8601 format.
*
* An alternative to this method is to format/parse the instant as a single
* epoch-seconds value. That is achieved using {@code appendValue(INSTANT_SECONDS)}.
*
* @return this, for chaining, not null
*/
public DateTimeFormatterBuilder appendInstant() {
appendInternal(new InstantPrinterParser());
return this;
}
/**
* Appends the zone offset, such as '+01:00', to the formatter.
*
* This appends an instruction to format/parse the offset ID to the builder.
* This is equivalent to calling {@code appendOffset("HH:MM:ss", "Z")}.
*
* @return this, for chaining, not null
*/
public DateTimeFormatterBuilder appendOffsetId() {
appendInternal(OffsetIdPrinterParser.INSTANCE_ID_Z);
return this;
}
/**
* Appends the zone offset, such as '+01:00', to the formatter.
*
* This appends an instruction to format/parse the offset ID to the builder.
*
* During formatting, the offset is obtained using a mechanism equivalent
* to querying the temporal with {@link Queries#offset()}.
* It will be printed using the format defined below.
* If the offset cannot be obtained then an exception is thrown unless the
* section of the formatter is optional.
*
* During parsing, the offset is parsed using the format defined below.
* If the offset cannot be parsed then an exception is thrown unless the
* section of the formatter is optional.
*
* The format of the offset is controlled by a pattern which must be one
* of the following:
*
* The "no offset" text controls what text is printed when the total amount of
* the offset fields to be output is zero.
* Example values would be 'Z', '+00:00', 'UTC' or 'GMT'.
* Three formats are accepted for parsing UTC - the "no offset" text, and the
* plus and minus versions of zero defined by the pattern.
*
* @param pattern the pattern to use, not null
* @param noOffsetText the text to use when the offset is zero, not null
* @return this, for chaining, not null
*/
public DateTimeFormatterBuilder appendOffset(String pattern, String noOffsetText) {
appendInternal(new OffsetIdPrinterParser(pattern, noOffsetText));
return this;
}
//-----------------------------------------------------------------------
/**
* Appends the time-zone ID, such as 'Europe/Paris' or '+02:00', to the formatter.
*
* This appends an instruction to format/parse the zone ID to the builder.
* The zone ID is obtained in a strict manner suitable for {@code ZonedDateTime}.
* By contrast, {@code OffsetDateTime} does not have a zone ID suitable
* for use with this method, see {@link #appendZoneOrOffsetId()}.
*
* During formatting, the zone is obtained using a mechanism equivalent
* to querying the temporal with {@link Queries#zoneId()}.
* It will be printed using the result of {@link ZoneId#getId()}.
* If the zone cannot be obtained then an exception is thrown unless the
* section of the formatter is optional.
*
* During parsing, the text must match a known zone or offset.
* There are two types of zone ID, offset-based, such as '+01:30' and
* region-based, such as 'Europe/London'. These are parsed differently.
* If the parse starts with '+', '-', 'UT', 'UTC' or 'GMT', then the parser
* expects an offset-based zone and will not match region-based zones.
* The offset ID, such as '+02:30', may be at the start of the parse,
* or prefixed by 'UT', 'UTC' or 'GMT'. The offset ID parsing is
* equivalent to using {@link #appendOffset(String, String)} using the
* arguments 'HH:MM:ss' and the no offset string '0'.
* If the parse starts with 'UT', 'UTC' or 'GMT', and the parser cannot
* match a following offset ID, then {@link ZoneOffset#UTC} is selected.
* In all other cases, the list of known region-based zones is used to
* find the longest available match. If no match is found, and the parse
* starts with 'Z', then {@code ZoneOffset.UTC} is selected.
* The parser uses the {@linkplain #parseCaseInsensitive() case sensitive} setting.
*
* For example, the following will parse:
*
* This appends an instruction to format/parse the zone ID to the builder
* only if it is a region-based ID.
*
* During formatting, the zone is obtained using a mechanism equivalent
* to querying the temporal with {@link Queries#zoneId()}.
* If the zone is a {@code ZoneOffset} or it cannot be obtained then
* an exception is thrown unless the section of the formatter is optional.
* If the zone is not an offset, then the zone will be printed using
* the zone ID from {@link ZoneId#getId()}.
*
* During parsing, the text must match a known zone or offset.
* There are two types of zone ID, offset-based, such as '+01:30' and
* region-based, such as 'Europe/London'. These are parsed differently.
* If the parse starts with '+', '-', 'UT', 'UTC' or 'GMT', then the parser
* expects an offset-based zone and will not match region-based zones.
* The offset ID, such as '+02:30', may be at the start of the parse,
* or prefixed by 'UT', 'UTC' or 'GMT'. The offset ID parsing is
* equivalent to using {@link #appendOffset(String, String)} using the
* arguments 'HH:MM:ss' and the no offset string '0'.
* If the parse starts with 'UT', 'UTC' or 'GMT', and the parser cannot
* match a following offset ID, then {@link ZoneOffset#UTC} is selected.
* In all other cases, the list of known region-based zones is used to
* find the longest available match. If no match is found, and the parse
* starts with 'Z', then {@code ZoneOffset.UTC} is selected.
* The parser uses the {@linkplain #parseCaseInsensitive() case sensitive} setting.
*
* For example, the following will parse:
*
* Note that this method is is identical to {@code appendZoneId()} except
* in the mechanism used to obtain the zone.
* Note also that parsing accepts offsets, whereas formatting will never
* produce one.
*
* @return this, for chaining, not null
* @see #appendZoneId()
*/
public DateTimeFormatterBuilder appendZoneRegionId() {
appendInternal(new ZoneIdPrinterParser(QUERY_REGION_ONLY, "ZoneRegionId()"));
return this;
}
/**
* Appends the time-zone ID, such as 'Europe/Paris' or '+02:00', to
* the formatter, using the best available zone ID.
*
* This appends an instruction to format/parse the best available
* zone or offset ID to the builder.
* The zone ID is obtained in a lenient manner that first attempts to
* find a true zone ID, such as that on {@code ZonedDateTime}, and
* then attempts to find an offset, such as that on {@code OffsetDateTime}.
*
* During formatting, the zone is obtained using a mechanism equivalent
* to querying the temporal with {@link Queries#zone()}.
* It will be printed using the result of {@link ZoneId#getId()}.
* If the zone cannot be obtained then an exception is thrown unless the
* section of the formatter is optional.
*
* During parsing, the text must match a known zone or offset.
* There are two types of zone ID, offset-based, such as '+01:30' and
* region-based, such as 'Europe/London'. These are parsed differently.
* If the parse starts with '+', '-', 'UT', 'UTC' or 'GMT', then the parser
* expects an offset-based zone and will not match region-based zones.
* The offset ID, such as '+02:30', may be at the start of the parse,
* or prefixed by 'UT', 'UTC' or 'GMT'. The offset ID parsing is
* equivalent to using {@link #appendOffset(String, String)} using the
* arguments 'HH:MM:ss' and the no offset string '0'.
* If the parse starts with 'UT', 'UTC' or 'GMT', and the parser cannot
* match a following offset ID, then {@link ZoneOffset#UTC} is selected.
* In all other cases, the list of known region-based zones is used to
* find the longest available match. If no match is found, and the parse
* starts with 'Z', then {@code ZoneOffset.UTC} is selected.
* The parser uses the {@linkplain #parseCaseInsensitive() case sensitive} setting.
*
* For example, the following will parse:
*
* Note that this method is is identical to {@code appendZoneId()} except
* in the mechanism used to obtain the zone.
*
* @return this, for chaining, not null
* @see #appendZoneId()
*/
public DateTimeFormatterBuilder appendZoneOrOffsetId() {
appendInternal(new ZoneIdPrinterParser(Queries.zone(), "ZoneOrOffsetId()"));
return this;
}
/**
* Appends the time-zone name, such as 'British Summer Time', to the formatter.
*
* This appends an instruction to format/parse the textual name of the zone to
* the builder.
*
* During formatting, the zone is obtained using a mechanism equivalent
* to querying the temporal with {@link Queries#zoneId()}.
* If the zone is a {@code ZoneOffset} it will be printed using the
* result of {@link ZoneOffset#getId()}.
* If the zone is not an offset, the textual name will be looked up
* for the locale set in the {@link DateTimeFormatter}.
* If the temporal object being printed represents an instant, then the text
* will be the summer or winter time text as appropriate.
* If the lookup for text does not find any suitable reuslt, then the
* {@link ZoneId#getId() ID} will be printed instead.
* If the zone cannot be obtained then an exception is thrown unless the
* section of the formatter is optional.
*
* During parsing, either the textual zone name, the zone ID or the offset
* is accepted. Many textual zone names are not unique, such as CST can be
* for both "Central Standard Time" and "China Standard Time". In this
* situation, the zone id will be determined by the region information from
* formatter's {@link DateTimeFormatter#getLocale() locale} and the standard
* zone id for that area, for example, America/New_York for the America Eastern
* zone. The {@link #appendZoneText(TextStyle, Set)} may be used
* to specify a set of preferred {@link ZoneId} in this situation.
*
* @param textStyle the text style to use, not null
* @return this, for chaining, not null
*/
public DateTimeFormatterBuilder appendZoneText(TextStyle textStyle) {
appendInternal(new ZoneTextPrinterParser(textStyle, null));
return this;
}
/**
* Appends the time-zone name, such as 'British Summer Time', to the formatter.
*
* This appends an instruction to format/parse the textual name of the zone to
* the builder.
*
* During formatting, the zone is obtained using a mechanism equivalent
* to querying the temporal with {@link Queries#zoneId()}.
* If the zone is a {@code ZoneOffset} it will be printed using the
* result of {@link ZoneOffset#getId()}.
* If the zone is not an offset, the textual name will be looked up
* for the locale set in the {@link DateTimeFormatter}.
* If the temporal object being printed represents an instant, then the text
* will be the summer or winter time text as appropriate.
* If the lookup for text does not find any suitable reuslt, then the
* {@link ZoneId#getId() ID} will be printed instead.
* If the zone cannot be obtained then an exception is thrown unless the
* section of the formatter is optional.
*
* During parsing, either the textual zone name, the zone ID or the offset
* is accepted. Many textual zone names are not unique, such as CST can be
* for both "Central Standard Time" and "China Standard Time". In this
* situation, the zone id will be determined by the region information from
* formatter's {@link DateTimeFormatter#getLocale() locale} and the standard
* zone id for that area, for example, America/New_York for the America Eastern
* zone. This method also allows a set of preferred {@link ZoneId} to be
* specified for parsing. The matched preferred zone id will be used if the
* textural zone name being parsed is not unique.
*
* If the zone cannot be parsed then an exception is thrown unless the
* section of the formatter is optional.
*
* @param textStyle the text style to use, not null
* @param preferredZones the set of preferred zone ids, not null
* @return this, for chaining, not null
*/
public DateTimeFormatterBuilder appendZoneText(TextStyle textStyle,
Set
* This appends an instruction to format/parse the chronology ID to the builder.
*
* During formatting, the chronology is obtained using a mechanism equivalent
* to querying the temporal with {@link Queries#chronology()}.
* It will be printed using the result of {@link Chronology#getId()}.
* If the chronology cannot be obtained then an exception is thrown unless the
* section of the formatter is optional.
*
* During parsing, the chronology is parsed and must match one of the chronologies
* in {@link Chronology#getAvailableChronologies()}.
* If the chronology cannot be parsed then an exception is thrown unless the
* section of the formatter is optional.
* The parser uses the {@linkplain #parseCaseInsensitive() case sensitive} setting.
*
* @return this, for chaining, not null
*/
public DateTimeFormatterBuilder appendChronologyId() {
appendInternal(new ChronoPrinterParser(null));
return this;
}
/**
* Appends the chronology name to the formatter.
*
* The calendar system name will be output during a format.
* If the chronology cannot be obtained then an exception will be thrown.
* The calendar system name is obtained from the formatting symbols.
*
* @param textStyle the text style to use, not null
* @return this, for chaining, not null
*/
public DateTimeFormatterBuilder appendChronologyText(TextStyle textStyle) {
Objects.requireNonNull(textStyle, "textStyle");
appendInternal(new ChronoPrinterParser(textStyle));
return this;
}
//-----------------------------------------------------------------------
/**
* Appends a localized date-time pattern to the formatter.
*
* This appends a localized section to the builder, suitable for outputting
* a date, time or date-time combination. The format of the localized
* section is lazily looked up based on four items:
*
* During formatting, the chronology is obtained from the temporal object
* being formatted, which may have been overridden by
* {@link DateTimeFormatter#withChronology(Chronology)}.
*
* During parsing, if a chronology has already been parsed, then it is used.
* Otherwise the default from {@code DateTimeFormatter.withChronology(Chronology)}
* is used, with {@code IsoChronology} as the fallback.
*
* Note that this method provides similar functionality to methods on
* {@code DateFormat} such as {@link DateFormat#getDateTimeInstance(int, int)}.
*
* @param dateStyle the date style to use, null means no date required
* @param timeStyle the time style to use, null means no time required
* @return this, for chaining, not null
* @throws IllegalArgumentException if both the date and time styles are null
*/
public DateTimeFormatterBuilder appendLocalized(FormatStyle dateStyle, FormatStyle timeStyle) {
if (dateStyle == null && timeStyle == null) {
throw new IllegalArgumentException("Either the date or time style must be non-null");
}
appendInternal(new LocalizedPrinterParser(dateStyle, timeStyle));
return this;
}
//-----------------------------------------------------------------------
/**
* Appends a character literal to the formatter.
*
* This character will be output during a format.
*
* @param literal the literal to append, not null
* @return this, for chaining, not null
*/
public DateTimeFormatterBuilder appendLiteral(char literal) {
appendInternal(new CharLiteralPrinterParser(literal));
return this;
}
/**
* Appends a string literal to the formatter.
*
* This string will be output during a format.
*
* If the literal is empty, nothing is added to the formatter.
*
* @param literal the literal to append, not null
* @return this, for chaining, not null
*/
public DateTimeFormatterBuilder appendLiteral(String literal) {
Objects.requireNonNull(literal, "literal");
if (literal.length() > 0) {
if (literal.length() == 1) {
appendInternal(new CharLiteralPrinterParser(literal.charAt(0)));
} else {
appendInternal(new StringLiteralPrinterParser(literal));
}
}
return this;
}
//-----------------------------------------------------------------------
/**
* Appends all the elements of a formatter to the builder.
*
* This method has the same effect as appending each of the constituent
* parts of the formatter directly to this builder.
*
* @param formatter the formatter to add, not null
* @return this, for chaining, not null
*/
public DateTimeFormatterBuilder append(DateTimeFormatter formatter) {
Objects.requireNonNull(formatter, "formatter");
appendInternal(formatter.toPrinterParser(false));
return this;
}
/**
* Appends a formatter to the builder which will optionally format/parse.
*
* This method has the same effect as appending each of the constituent
* parts directly to this builder surrounded by an {@link #optionalStart()} and
* {@link #optionalEnd()}.
*
* The formatter will format if data is available for all the fields contained within it.
* The formatter will parse if the string matches, otherwise no error is returned.
*
* @param formatter the formatter to add, not null
* @return this, for chaining, not null
*/
public DateTimeFormatterBuilder appendOptional(DateTimeFormatter formatter) {
Objects.requireNonNull(formatter, "formatter");
appendInternal(formatter.toPrinterParser(true));
return this;
}
//-----------------------------------------------------------------------
/**
* Appends the elements defined by the specified pattern to the builder.
*
* All letters 'A' to 'Z' and 'a' to 'z' are reserved as pattern letters.
* The characters '{' and '}' are reserved for future use.
* The characters '[' and ']' indicate optional patterns.
* The following pattern letters are defined:
*
* The count of pattern letters determine the format.
*
* Text: The text style is determined based on the number of pattern letters used.
* Less than 4 pattern letters will use the {@link TextStyle#SHORT short form}.
* Exactly 4 pattern letters will use the {@link TextStyle#FULL full form}.
* Exactly 5 pattern letters will use the {@link TextStyle#NARROW narrow form}.
*
* Number: If the count of letters is one, then the value is printed using the minimum number
* of digits and without padding as per {@link #appendValue(java.time.temporal.TemporalField)}. Otherwise, the
* count of digits is used as the width of the output field as per {@link #appendValue(java.time.temporal.TemporalField, int)}.
*
* Number/Text: If the count of pattern letters is 3 or greater, use the Text rules above.
* Otherwise use the Number rules above.
*
* Fraction: Outputs the nano-of-second field as a fraction-of-second.
* The nano-of-second value has nine digits, thus the count of pattern letters is from 1 to 9.
* If it is less than 9, then the nano-of-second value is truncated, with only the most
* significant digits being output.
* When parsing in strict mode, the number of parsed digits must match the count of pattern letters.
* When parsing in lenient mode, the number of parsed digits must be at least the count of pattern
* letters, up to 9 digits.
*
* Year: The count of letters determines the minimum field width below which padding is used.
* If the count of letters is two, then a {@link #appendValueReduced reduced} two digit form is used.
* For formatting, this outputs the rightmost two digits. For parsing, this will parse using the
* base value of 2000, resulting in a year within the range 2000 to 2099 inclusive.
* If the count of letters is less than four (but not two), then the sign is only output for negative
* years as per {@link SignStyle#NORMAL}.
* Otherwise, the sign is output if the pad width is exceeded, as per {@link SignStyle#EXCEEDS_PAD}
*
* ZoneId: This outputs the time-zone ID, such as 'Europe/Paris'.
* If the count of letters is two, then the time-zone ID is output.
* Any other count of letters throws {@code IllegalArgumentException}.
*
* Zone names: This outputs the display name of the time-zone ID.
* If the count of letters is one, two or three, then the short name is output.
* If the count of letters is four, then the full name is output.
* Five or more letters throws {@code IllegalArgumentException}.
*
* Offset X and x: This formats the offset based on the number of pattern letters.
* One letter outputs just the hour', such as '+01', unless the minute is non-zero
* in which case the minute is also output, such as '+0130'.
* Two letters outputs the hour and minute, without a colon, such as '+0130'.
* Three letters outputs the hour and minute, with a colon, such as '+01:30'.
* Four letters outputs the hour and minute and optional second, without a colon, such as '+013015'.
* Five letters outputs the hour and minute and optional second, with a colon, such as '+01:30:15'.
* Six or more letters throws {@code IllegalArgumentException}.
* Pattern letter 'X' (upper case) will output 'Z' when the offset to be output would be zero,
* whereas pattern letter 'x' (lower case) will output '+00', '+0000', or '+00:00'.
*
* Offset Z: This formats the offset based on the number of pattern letters.
* One, two or three letters outputs the hour and minute, without a colon, such as '+0130'.
* Four or more letters throws {@code IllegalArgumentException}.
* The output will be '+0000' when the offset is zero.
*
* Optional section: The optional section markers work exactly like calling {@link #optionalStart()}
* and {@link #optionalEnd()}.
*
* Pad modifier: Modifies the pattern that immediately follows to be padded with spaces.
* The pad width is determined by the number of pattern letters.
* This is the same as calling {@link #padNext(int)}.
*
* For example, 'ppH' outputs the hour-of-day padded on the left with spaces to a width of 2.
*
* Any unrecognized letter is an error.
* Any non-letter character, other than '[', ']', '{', '}' and the single quote will be output directly.
* Despite this, it is recommended to use single quotes around all characters that you want to
* output directly to ensure that future changes do not break your application.
*
* Note that the pattern string is similar, but not identical, to
* {@link java.text.SimpleDateFormat SimpleDateFormat}.
* The pattern string is also similar, but not identical, to that defined by the
* Unicode Common Locale Data Repository (CLDR/LDML).
* Pattern letters 'E' and 'u' are merged, which changes the meaning of "E" and "EE" to be numeric.
* Pattern letters 'X' is aligned with Unicode CLDR/LDML, which affects pattern 'X'.
* Pattern letter 'y' and 'Y' parse years of two digits and more than 4 digits differently.
* Pattern letters 'n', 'A', 'N', 'I' and 'p' are added.
* Number types will reject large numbers.
*
* @param pattern the pattern to add, not null
* @return this, for chaining, not null
* @throws IllegalArgumentException if the pattern is invalid
*/
public DateTimeFormatterBuilder appendPattern(String pattern) {
Objects.requireNonNull(pattern, "pattern");
parsePattern(pattern);
return this;
}
private void parsePattern(String pattern) {
for (int pos = 0; pos < pattern.length(); pos++) {
char cur = pattern.charAt(pos);
if ((cur >= 'A' && cur <= 'Z') || (cur >= 'a' && cur <= 'z')) {
int start = pos++;
for ( ; pos < pattern.length() && pattern.charAt(pos) == cur; pos++); // short loop
int count = pos - start;
// padding
if (cur == 'p') {
int pad = 0;
if (pos < pattern.length()) {
cur = pattern.charAt(pos);
if ((cur >= 'A' && cur <= 'Z') || (cur >= 'a' && cur <= 'z')) {
pad = count;
start = pos++;
for ( ; pos < pattern.length() && pattern.charAt(pos) == cur; pos++); // short loop
count = pos - start;
}
}
if (pad == 0) {
throw new IllegalArgumentException(
"Pad letter 'p' must be followed by valid pad pattern: " + pattern);
}
padNext(pad); // pad and continue parsing
}
// main rules
TemporalField field = FIELD_MAP.get(cur);
if (field != null) {
parseField(cur, count, field);
} else if (cur == 'z') {
if (count > 4) {
throw new IllegalArgumentException("Too many pattern letters: " + cur);
} else if (count == 4) {
appendZoneText(TextStyle.FULL);
} else {
appendZoneText(TextStyle.SHORT);
}
} else if (cur == 'V') {
if (count != 2) {
throw new IllegalArgumentException("Pattern letter count must be 2: " + cur);
}
appendZoneId();
} else if (cur == 'Z') {
if (count > 3) {
throw new IllegalArgumentException("Too many pattern letters: " + cur);
}
appendOffset("+HHMM", "+0000");
} else if (cur == 'X') {
if (count > 5) {
throw new IllegalArgumentException("Too many pattern letters: " + cur);
}
appendOffset(OffsetIdPrinterParser.PATTERNS[count + (count == 1 ? 0 : 1)], "Z");
} else if (cur == 'x') {
if (count > 5) {
throw new IllegalArgumentException("Too many pattern letters: " + cur);
}
String zero = (count == 1 ? "+00" : (count % 2 == 0 ? "+0000" : "+00:00"));
appendOffset(OffsetIdPrinterParser.PATTERNS[count + (count == 1 ? 0 : 1)], zero);
} else if (cur == 'w' || cur == 'e') {
// Fields defined by Locale
if (count > 1) {
throw new IllegalArgumentException("Too many pattern letters: " + cur);
}
appendInternal(new WeekBasedFieldPrinterParser(cur, count));
} else if (cur == 'W') {
// Fields defined by Locale
if (count > 2) {
throw new IllegalArgumentException("Too many pattern letters: " + cur);
}
appendInternal(new WeekBasedFieldPrinterParser(cur, count));
} else {
throw new IllegalArgumentException("Unknown pattern letter: " + cur);
}
pos--;
} else if (cur == '\'') {
// parse literals
int start = pos++;
for ( ; pos < pattern.length(); pos++) {
if (pattern.charAt(pos) == '\'') {
if (pos + 1 < pattern.length() && pattern.charAt(pos + 1) == '\'') {
pos++;
} else {
break; // end of literal
}
}
}
if (pos >= pattern.length()) {
throw new IllegalArgumentException("Pattern ends with an incomplete string literal: " + pattern);
}
String str = pattern.substring(start + 1, pos);
if (str.length() == 0) {
appendLiteral('\'');
} else {
appendLiteral(str.replace("''", "'"));
}
} else if (cur == '[') {
optionalStart();
} else if (cur == ']') {
if (active.parent == null) {
throw new IllegalArgumentException("Pattern invalid as it contains ] without previous [");
}
optionalEnd();
} else if (cur == '{' || cur == '}') {
throw new IllegalArgumentException("Pattern includes reserved character: '" + cur + "'");
} else {
appendLiteral(cur);
}
}
}
private void parseField(char cur, int count, TemporalField field) {
switch (cur) {
case 'y':
case 'Y':
if (count == 2) {
appendValueReduced(field, 2, 2000);
} else if (count < 4) {
appendValue(field, count, 19, SignStyle.NORMAL);
} else {
appendValue(field, count, 19, SignStyle.EXCEEDS_PAD);
}
break;
case 'M':
case 'Q':
case 'E':
switch (count) {
case 1:
appendValue(field);
break;
case 2:
appendValue(field, 2);
break;
case 3:
appendText(field, TextStyle.SHORT);
break;
case 4:
appendText(field, TextStyle.FULL);
break;
case 5:
appendText(field, TextStyle.NARROW);
break;
default:
throw new IllegalArgumentException("Too many pattern letters: " + cur);
}
break;
case 'G':
case 'a':
switch (count) {
case 1:
case 2:
case 3:
appendText(field, TextStyle.SHORT);
break;
case 4:
appendText(field, TextStyle.FULL);
break;
case 5:
appendText(field, TextStyle.NARROW);
break;
default:
throw new IllegalArgumentException("Too many pattern letters: " + cur);
}
break;
case 'S':
appendFraction(NANO_OF_SECOND, count, count, false);
break;
default:
if (count == 1) {
appendValue(field);
} else {
appendValue(field, count);
}
break;
}
}
/** Map of letters to fields. */
private static final Map
* This padding will pad to a fixed width using spaces.
*
* During formatting, the decorated element will be output and then padded
* to the specified width. An exception will be thrown during formatting if
* the pad width is exceeded.
*
* During parsing, the padding and decorated element are parsed.
* If parsing is lenient, then the pad width is treated as a maximum.
* If parsing is case insensitive, then the pad character is matched ignoring case.
* The padding is parsed greedily. Thus, if the decorated element starts with
* the pad character, it will not be parsed.
*
* @param padWidth the pad width, 1 or greater
* @return this, for chaining, not null
* @throws IllegalArgumentException if pad width is too small
*/
public DateTimeFormatterBuilder padNext(int padWidth) {
return padNext(padWidth, ' ');
}
/**
* Causes the next added printer/parser to pad to a fixed width.
*
* This padding is intended for padding other than zero-padding.
* Zero-padding should be achieved using the appendValue methods.
*
* During formatting, the decorated element will be output and then padded
* to the specified width. An exception will be thrown during formatting if
* the pad width is exceeded.
*
* During parsing, the padding and decorated element are parsed.
* If parsing is lenient, then the pad width is treated as a maximum.
* If parsing is case insensitive, then the pad character is matched ignoring case.
* The padding is parsed greedily. Thus, if the decorated element starts with
* the pad character, it will not be parsed.
*
* @param padWidth the pad width, 1 or greater
* @param padChar the pad character
* @return this, for chaining, not null
* @throws IllegalArgumentException if pad width is too small
*/
public DateTimeFormatterBuilder padNext(int padWidth, char padChar) {
if (padWidth < 1) {
throw new IllegalArgumentException("The pad width must be at least one but was " + padWidth);
}
active.padNextWidth = padWidth;
active.padNextChar = padChar;
active.valueParserIndex = -1;
return this;
}
//-----------------------------------------------------------------------
/**
* Mark the start of an optional section.
*
* The output of formatting can include optional sections, which may be nested.
* An optional section is started by calling this method and ended by calling
* {@link #optionalEnd()} or by ending the build process.
*
* All elements in the optional section are treated as optional.
* During formatting, the section is only output if data is available in the
* {@code TemporalAccessor} for all the elements in the section.
* During parsing, the whole section may be missing from the parsed string.
*
* For example, consider a builder setup as
* {@code builder.appendValue(HOUR_OF_DAY,2).optionalStart().appendValue(MINUTE_OF_HOUR,2)}.
* The optional section ends automatically at the end of the builder.
* During formatting, the minute will only be output if its value can be obtained from the date-time.
* During parsing, the input will be successfully parsed whether the minute is present or not.
*
* @return this, for chaining, not null
*/
public DateTimeFormatterBuilder optionalStart() {
active.valueParserIndex = -1;
active = new DateTimeFormatterBuilder(active, true);
return this;
}
/**
* Ends an optional section.
*
* The output of formatting can include optional sections, which may be nested.
* An optional section is started by calling {@link #optionalStart()} and ended
* using this method (or at the end of the builder).
*
* Calling this method without having previously called {@code optionalStart}
* will throw an exception.
* Calling this method immediately after calling {@code optionalStart} has no effect
* on the formatter other than ending the (empty) optional section.
*
* All elements in the optional section are treated as optional.
* During formatting, the section is only output if data is available in the
* {@code TemporalAccessor} for all the elements in the section.
* During parsing, the whole section may be missing from the parsed string.
*
* For example, consider a builder setup as
* {@code builder.appendValue(HOUR_OF_DAY,2).optionalStart().appendValue(MINUTE_OF_HOUR,2).optionalEnd()}.
* During formatting, the minute will only be output if its value can be obtained from the date-time.
* During parsing, the input will be successfully parsed whether the minute is present or not.
*
* @return this, for chaining, not null
* @throws IllegalStateException if there was no previous call to {@code optionalStart}
*/
public DateTimeFormatterBuilder optionalEnd() {
if (active.parent == null) {
throw new IllegalStateException("Cannot call optionalEnd() as there was no previous call to optionalStart()");
}
if (active.printerParsers.size() > 0) {
CompositePrinterParser cpp = new CompositePrinterParser(active.printerParsers, active.optional);
active = active.parent;
appendInternal(cpp);
} else {
active = active.parent;
}
return this;
}
//-----------------------------------------------------------------------
/**
* Appends a printer and/or parser to the internal list handling padding.
*
* @param pp the printer-parser to add, not null
* @return the index into the active parsers list
*/
private int appendInternal(DateTimePrinterParser pp) {
Objects.requireNonNull(pp, "pp");
if (active.padNextWidth > 0) {
if (pp != null) {
pp = new PadPrinterParserDecorator(pp, active.padNextWidth, active.padNextChar);
}
active.padNextWidth = 0;
active.padNextChar = 0;
}
active.printerParsers.add(pp);
active.valueParserIndex = -1;
return active.printerParsers.size() - 1;
}
//-----------------------------------------------------------------------
/**
* Completes this builder by creating the DateTimeFormatter using the default locale.
*
* This will create a formatter with the {@link Locale#getDefault(Locale.Category) default FORMAT locale}.
* Numbers will be printed and parsed using the standard non-localized set of symbols.
*
* Calling this method will end any open optional sections by repeatedly
* calling {@link #optionalEnd()} before creating the formatter.
*
* This builder can still be used after creating the formatter if desired,
* although the state may have been changed by calls to {@code optionalEnd}.
*
* @return the created formatter, not null
*/
public DateTimeFormatter toFormatter() {
return toFormatter(Locale.getDefault(Locale.Category.FORMAT));
}
/**
* Completes this builder by creating the DateTimeFormatter using the specified locale.
*
* This will create a formatter with the specified locale.
* Numbers will be printed and parsed using the standard non-localized set of symbols.
*
* Calling this method will end any open optional sections by repeatedly
* calling {@link #optionalEnd()} before creating the formatter.
*
* This builder can still be used after creating the formatter if desired,
* although the state may have been changed by calls to {@code optionalEnd}.
*
* @param locale the locale to use for formatting, not null
* @return the created formatter, not null
*/
public DateTimeFormatter toFormatter(Locale locale) {
Objects.requireNonNull(locale, "locale");
while (active.parent != null) {
optionalEnd();
}
CompositePrinterParser pp = new CompositePrinterParser(printerParsers, false);
return new DateTimeFormatter(pp, locale, DateTimeFormatSymbols.STANDARD, null, null);
}
//-----------------------------------------------------------------------
/**
* Strategy for formatting/parsing date-time information.
*
* The printer may format any part, or the whole, of the input date-time object.
* Typically, a complete format is constructed from a number of smaller
* units, each outputting a single field.
*
* The parser may parse any piece of text from the input, storing the result
* in the context. Typically, each individual parser will just parse one
* field, such as the day-of-month, storing the value in the context.
* Once the parse is complete, the caller will then resolve the parsed values
* to create the desired object, such as a {@code LocalDate}.
*
* The parse position will be updated during the parse. Parsing will start at
* the specified index and the return value specifies the new parse position
* for the next parser. If an error occurs, the returned index will be negative
* and will have the error position encoded using the complement operator.
*
*
* The context is not a thread-safe object and a new instance will be created
* for each format that occurs. The context must not be stored in an instance
* variable or shared with any other threads.
*/
interface DateTimePrinterParser {
/**
* Prints the date-time object to the buffer.
*
* The context holds information to use during the format.
* It also contains the date-time information to be printed.
*
* The buffer must not be mutated beyond the content controlled by the implementation.
*
* @param context the context to format using, not null
* @param buf the buffer to append to, not null
* @return false if unable to query the value from the date-time, true otherwise
* @throws DateTimeException if the date-time cannot be printed successfully
*/
boolean format(DateTimePrintContext context, StringBuilder buf);
/**
* Parses text into date-time information.
*
* The context holds information to use during the parse.
* It is also used to store the parsed date-time information.
*
* @param context the context to use and parse into, not null
* @param text the input text to parse, not null
* @param position the position to start parsing at, from 0 to the text length
* @return the new parse position, where negative means an error with the
* error position encoded using the complement ~ operator
* @throws NullPointerException if the context or text is null
* @throws IndexOutOfBoundsException if the position is invalid
*/
int parse(DateTimeParseContext context, CharSequence text, int position);
}
//-----------------------------------------------------------------------
/**
* Composite printer and parser.
*/
static final class CompositePrinterParser implements DateTimePrinterParser {
private final DateTimePrinterParser[] printerParsers;
private final boolean optional;
CompositePrinterParser(List
* The fractional value is between 0 (inclusive) and 1 (exclusive).
* It can only be returned if the {@link java.time.temporal.TemporalField#range() value range} is fixed.
* The fraction is obtained by calculation from the field range using 9 decimal
* places and a rounding mode of {@link RoundingMode#FLOOR FLOOR}.
* The calculation is inaccurate if the values do not run continuously from smallest to largest.
*
* For example, the second-of-minute value of 15 would be returned as 0.25,
* assuming the standard definition of 60 seconds in a minute.
*
* @param value the value to convert, must be valid for this rule
* @return the value as a fraction within the range, from 0 to 1, not null
* @throws DateTimeException if the value cannot be converted to a fraction
*/
private BigDecimal convertToFraction(long value) {
ValueRange range = field.range();
range.checkValidValue(value, field);
BigDecimal minBD = BigDecimal.valueOf(range.getMinimum());
BigDecimal rangeBD = BigDecimal.valueOf(range.getMaximum()).subtract(minBD).add(BigDecimal.ONE);
BigDecimal valueBD = BigDecimal.valueOf(value).subtract(minBD);
BigDecimal fraction = valueBD.divide(rangeBD, 9, RoundingMode.FLOOR);
// stripTrailingZeros bug
return fraction.compareTo(BigDecimal.ZERO) == 0 ? BigDecimal.ZERO : fraction.stripTrailingZeros();
}
/**
* Converts a fraction from 0 to 1 for this field to a value.
*
* The fractional value must be between 0 (inclusive) and 1 (exclusive).
* It can only be returned if the {@link java.time.temporal.TemporalField#range() value range} is fixed.
* The value is obtained by calculation from the field range and a rounding
* mode of {@link RoundingMode#FLOOR FLOOR}.
* The calculation is inaccurate if the values do not run continuously from smallest to largest.
*
* For example, the fractional second-of-minute of 0.25 would be converted to 15,
* assuming the standard definition of 60 seconds in a minute.
*
* @param fraction the fraction to convert, not null
* @return the value of the field, valid for this rule
* @throws DateTimeException if the value cannot be converted
*/
private long convertFromFraction(BigDecimal fraction) {
ValueRange range = field.range();
BigDecimal minBD = BigDecimal.valueOf(range.getMinimum());
BigDecimal rangeBD = BigDecimal.valueOf(range.getMaximum()).subtract(minBD).add(BigDecimal.ONE);
BigDecimal valueBD = fraction.multiply(rangeBD).setScale(0, RoundingMode.FLOOR).add(minBD);
return valueBD.longValueExact();
}
@Override
public String toString() {
String decimal = (decimalPoint ? ",DecimalPoint" : "");
return "Fraction(" + field.getName() + "," + minWidth + "," + maxWidth + decimal + ")";
}
}
//-----------------------------------------------------------------------
/**
* Prints or parses field text.
*/
static final class TextPrinterParser implements DateTimePrinterParser {
private final TemporalField field;
private final TextStyle textStyle;
private final DateTimeTextProvider provider;
/**
* The cached number printer parser.
* Immutable and volatile, so no synchronization needed.
*/
private volatile NumberPrinterParser numberPrinterParser;
/**
* Constructor.
*
* @param field the field to output, not null
* @param textStyle the text style, not null
* @param provider the text provider, not null
*/
TextPrinterParser(TemporalField field, TextStyle textStyle, DateTimeTextProvider provider) {
// validated by caller
this.field = field;
this.textStyle = textStyle;
this.provider = provider;
}
@Override
public boolean format(DateTimePrintContext context, StringBuilder buf) {
Long value = context.getValue(field);
if (value == null) {
return false;
}
String text;
Chronology chrono = context.getTemporal().query(Queries.chronology());
if (chrono == null || chrono == IsoChronology.INSTANCE) {
text = provider.getText(field, value, textStyle, context.getLocale());
} else {
text = provider.getText(chrono, field, value, textStyle, context.getLocale());
}
if (text == null) {
return numberPrinterParser().format(context, buf);
}
buf.append(text);
return true;
}
@Override
public int parse(DateTimeParseContext context, CharSequence parseText, int position) {
int length = parseText.length();
if (position < 0 || position > length) {
throw new IndexOutOfBoundsException();
}
TextStyle style = (context.isStrict() ? textStyle : null);
Chronology chrono = context.getEffectiveChronology();
Iterator
*
* "Europe/London" -> ZoneId.of("Europe/London")
* "Z" -> ZoneOffset.UTC
* "UT" -> ZoneOffset.UTC
* "UTC" -> ZoneOffset.UTC
* "GMT" -> ZoneOffset.UTC
* "UT0" -> ZoneOffset.UTC
* "UTC0" -> ZoneOffset.UTC
* "GMT0" -> ZoneOffset.UTC
* "+01:30" -> ZoneOffset.of("+01:30")
* "UT+01:30" -> ZoneOffset.of("+01:30")
* "UTC+01:30" -> ZoneOffset.of("+01:30")
* "GMT+01:30" -> ZoneOffset.of("+01:30")
*
*
* @return this, for chaining, not null
* @see #appendZoneRegionId()
*/
public DateTimeFormatterBuilder appendZoneId() {
appendInternal(new ZoneIdPrinterParser(Queries.zoneId(), "ZoneId()"));
return this;
}
/**
* Appends the time-zone region ID, such as 'Europe/Paris', to the formatter,
* rejecting the zone ID if it is a {@code ZoneOffset}.
*
* "Europe/London" -> ZoneId.of("Europe/London")
* "Z" -> ZoneOffset.UTC
* "UT" -> ZoneOffset.UTC
* "UTC" -> ZoneOffset.UTC
* "GMT" -> ZoneOffset.UTC
* "UT0" -> ZoneOffset.UTC
* "UTC0" -> ZoneOffset.UTC
* "GMT0" -> ZoneOffset.UTC
* "+01:30" -> ZoneOffset.of("+01:30")
* "UT+01:30" -> ZoneOffset.of("+01:30")
* "UTC+01:30" -> ZoneOffset.of("+01:30")
* "GMT+01:30" -> ZoneOffset.of("+01:30")
*
*
* "Europe/London" -> ZoneId.of("Europe/London")
* "Z" -> ZoneOffset.UTC
* "UT" -> ZoneOffset.UTC
* "UTC" -> ZoneOffset.UTC
* "GMT" -> ZoneOffset.UTC
* "UT0" -> ZoneOffset.UTC
* "UTC0" -> ZoneOffset.UTC
* "GMT0" -> ZoneOffset.UTC
* "+01:30" -> ZoneOffset.of("+01:30")
* "UT+01:30" -> ZoneOffset.of("+01:30")
* "UTC+01:30" -> ZoneOffset.of("+01:30")
* "GMT+01:30" -> ZoneOffset.of("+01:30")
*
*
*
* Symbol Meaning Presentation Examples
* ------ ------- ------------ -------
* G era text A; AD; Anno Domini
* y year year 2004; 04
* D day-of-year number 189
* M month-of-year number/text 7; 07; Jul; July; J
* d day-of-month number 10
*
* Q quarter-of-year number/text 3; 03; Q3
* Y week-based-year year 1996; 96
* w week-of-year number 27
* W week-of-month number 27
* e localized day-of-week number 2; Tue; Tuesday; T
* E day-of-week number/text 2; Tue; Tuesday; T
* F week-of-month number 3
*
* a am-pm-of-day text PM
* h clock-hour-of-am-pm (1-12) number 12
* K hour-of-am-pm (0-11) number 0
* k clock-hour-of-am-pm (1-24) number 0
*
* H hour-of-day (0-23) number 0
* m minute-of-hour number 30
* s second-of-minute number 55
* S fraction-of-second fraction 978
* A milli-of-day number 1234
* n nano-of-second number 987654321
* N nano-of-day number 1234000000
*
* V time-zone ID zone-id America/Los_Angeles; Z; -08:30
* z time-zone name zone-name Pacific Standard Time; PST
* X zone-offset 'Z' for zero offset-X Z; -08; -0830; -08:30; -083015; -08:30:15;
* x zone-offset offset-x +0000; -08; -0830; -08:30; -083015; -08:30:15;
* Z zone-offset offset-Z +0000; -0800; -08:00;
*
* p pad next pad modifier 1
*
* ' escape for text delimiter
* '' single quote literal '
* [ optional section start
* ] optional section end
* {} reserved for future use
*
*
* Pattern Equivalent builder methods
* VV appendZoneId()
*
*
* Pattern Equivalent builder methods
* z appendZoneText(TextStyle.SHORT)
* zz appendZoneText(TextStyle.SHORT)
* zzz appendZoneText(TextStyle.SHORT)
* zzzz appendZoneText(TextStyle.FULL)
*
*
* Pattern Equivalent builder methods
* X appendOffset("+HHmm","Z")
* XX appendOffset("+HHMM","Z")
* XXX appendOffset("+HH:MM","Z")
* XXXX appendOffset("+HHMMss","Z")
* XXXXX appendOffset("+HH:MM:ss","Z")
* x appendOffset("+HHmm","+00")
* xx appendOffset("+HHMM","+0000")
* xxx appendOffset("+HH:MM","+00:00")
* xxxx appendOffset("+HHMMss","+0000")
* xxxxx appendOffset("+HH:MM:ss","+00:00")
*
*
* Pattern Equivalent builder methods
* Z appendOffset("+HHMM","+0000")
* ZZ appendOffset("+HHMM","+0000")
* ZZZ appendOffset("+HHMM","+0000")
*
* Specification for implementors
* This interface must be implemented with care to ensure other classes operate correctly.
* All implementations that can be instantiated must be final, immutable and thread-safe.
*