org.joda.time.format
Class DateTimeFormatterBuilder

java.lang.Object
  org.joda.time.format.DateTimeFormatterBuilder

public class DateTimeFormatterBuilder
extends Object

Factory that creates complex instances of DateTimeFormatter via method calls.

Datetime formatting is performed by the DateTimeFormatter class. Three classes provide factory methods to create formatters, and this is one. The others are DateTimeFormat and ISODateTimeFormat.

DateTimeFormatterBuilder is used for constructing formatters which are then used to print or parse. The formatters are built by appending specific fields or other formatters to an instance of this builder.

For example, a formatter that prints month and year, like "January 1970", can be constructed as follows:

 DateTimeFormatter monthAndYear = new DateTimeFormatterBuilder()
     .appendMonthOfYearText()
     .appendLiteral(' ')
     .appendYear(4, 4)
     .toFormatter();
 

DateTimeFormatterBuilder itself is mutable and not thread-safe, but the formatters that it builds are thread-safe and immutable.

Since:

1.0

Author:

Brian S O'Neill, Stephen Colebourne, Fredrik Borgh

See Also:

DateTimeFormat, ISODateTimeFormat

Constructor Summary

DateTimeFormatterBuilder()
Creates a DateTimeFormatterBuilder.

Method Summary

DateTimeFormatterBuilder	append(DateTimeFormatter formatter) Appends another formatter.
DateTimeFormatterBuilder	append(DateTimeParser parser) Appends just a parser.
DateTimeFormatterBuilder	append(DateTimePrinter printer) Appends just a printer.
DateTimeFormatterBuilder	append(DateTimePrinter printer, DateTimeParser parser) Appends a printer/parser pair.
DateTimeFormatterBuilder	append(DateTimePrinter printer, DateTimeParser[] parsers) Appends a printer and a set of matching parsers.
DateTimeFormatterBuilder	appendCenturyOfEra(int minDigits, int maxDigits) Instructs the printer to emit a numeric century of era field.
DateTimeFormatterBuilder	appendClockhourOfDay(int minDigits) Instructs the printer to emit a numeric clockhourOfDay field.
DateTimeFormatterBuilder	appendClockhourOfHalfday(int minDigits) Instructs the printer to emit a numeric clockhourOfHalfday field.
DateTimeFormatterBuilder	appendDayOfMonth(int minDigits) Instructs the printer to emit a numeric dayOfMonth field.
DateTimeFormatterBuilder	appendDayOfWeek(int minDigits) Instructs the printer to emit a numeric dayOfWeek field.
DateTimeFormatterBuilder	appendDayOfWeekShortText() Instructs the printer to emit a short locale-specific dayOfWeek text.
DateTimeFormatterBuilder	appendDayOfWeekText() Instructs the printer to emit a locale-specific dayOfWeek text.
DateTimeFormatterBuilder	appendDayOfYear(int minDigits) Instructs the printer to emit a numeric dayOfYear field.
DateTimeFormatterBuilder	appendDecimal(DateTimeFieldType fieldType, int minDigits, int maxDigits) Instructs the printer to emit a field value as a decimal number, and the parser to expect an unsigned decimal number.
DateTimeFormatterBuilder	appendEraText() Instructs the printer to emit a locale-specific era text (BC/AD), and the parser to expect it.
DateTimeFormatterBuilder	appendFixedDecimal(DateTimeFieldType fieldType, int numDigits) Instructs the printer to emit a field value as a fixed-width decimal number (smaller numbers will be left-padded with zeros), and the parser to expect an unsigned decimal number with the same fixed width.
DateTimeFormatterBuilder	appendFixedSignedDecimal(DateTimeFieldType fieldType, int numDigits) Instructs the printer to emit a field value as a fixed-width decimal number (smaller numbers will be left-padded with zeros), and the parser to expect an signed decimal number with the same fixed width.
DateTimeFormatterBuilder	appendFraction(DateTimeFieldType fieldType, int minDigits, int maxDigits) Instructs the printer to emit a remainder of time as a decimal fraction, without decimal point.
DateTimeFormatterBuilder	appendFractionOfDay(int minDigits, int maxDigits) Appends the print/parse of a fractional day.
DateTimeFormatterBuilder	appendFractionOfHour(int minDigits, int maxDigits) Appends the print/parse of a fractional hour.
DateTimeFormatterBuilder	appendFractionOfMinute(int minDigits, int maxDigits) Appends the print/parse of a fractional minute.
DateTimeFormatterBuilder	appendFractionOfSecond(int minDigits, int maxDigits) Appends the print/parse of a fractional second.
DateTimeFormatterBuilder	appendHalfdayOfDayText() Instructs the printer to emit a locale-specific AM/PM text, and the parser to expect it.
DateTimeFormatterBuilder	appendHourOfDay(int minDigits) Instructs the printer to emit a numeric hourOfDay field.
DateTimeFormatterBuilder	appendHourOfHalfday(int minDigits) Instructs the printer to emit a numeric hourOfHalfday field.
DateTimeFormatterBuilder	appendLiteral(char c) Instructs the printer to emit a specific character, and the parser to expect it.
DateTimeFormatterBuilder	appendLiteral(String text) Instructs the printer to emit specific text, and the parser to expect it.
DateTimeFormatterBuilder	appendMillisOfDay(int minDigits) Instructs the printer to emit a numeric millisOfDay field.
DateTimeFormatterBuilder	appendMillisOfSecond(int minDigits) Instructs the printer to emit a numeric millisOfSecond field.
DateTimeFormatterBuilder	appendMinuteOfDay(int minDigits) Instructs the printer to emit a numeric minuteOfDay field.
DateTimeFormatterBuilder	appendMinuteOfHour(int minDigits) Instructs the printer to emit a numeric minuteOfHour field.
DateTimeFormatterBuilder	appendMonthOfYear(int minDigits) Instructs the printer to emit a numeric monthOfYear field.
DateTimeFormatterBuilder	appendMonthOfYearShortText() Instructs the printer to emit a locale-specific monthOfYear text.
DateTimeFormatterBuilder	appendMonthOfYearText() Instructs the printer to emit a short locale-specific monthOfYear text.
DateTimeFormatterBuilder	appendOptional(DateTimeParser parser) Appends just a parser element which is optional.
DateTimeFormatterBuilder	appendPattern(String pattern) Calls upon DateTimeFormat to parse the pattern and append the results into this builder.
DateTimeFormatterBuilder	appendSecondOfDay(int minDigits) Instructs the printer to emit a numeric secondOfDay field.
DateTimeFormatterBuilder	appendSecondOfMinute(int minDigits) Instructs the printer to emit a numeric secondOfMinute field.
DateTimeFormatterBuilder	appendShortText(DateTimeFieldType fieldType) Instructs the printer to emit a field value as short text, and the parser to expect text.
DateTimeFormatterBuilder	appendSignedDecimal(DateTimeFieldType fieldType, int minDigits, int maxDigits) Instructs the printer to emit a field value as a decimal number, and the parser to expect a signed decimal number.
DateTimeFormatterBuilder	appendText(DateTimeFieldType fieldType) Instructs the printer to emit a field value as text, and the parser to expect text.
DateTimeFormatterBuilder	appendTimeZoneId() Instructs the printer to emit the identifier of the time zone.
DateTimeFormatterBuilder	appendTimeZoneName() Instructs the printer to emit a locale-specific time zone name.
DateTimeFormatterBuilder	appendTimeZoneName(Map<String,DateTimeZone> parseLookup) Instructs the printer to emit a locale-specific time zone name, providing a lookup for parsing.
DateTimeFormatterBuilder	appendTimeZoneOffset(String zeroOffsetText, boolean showSeparators, int minFields, int maxFields) Instructs the printer to emit text and numbers to display time zone offset from UTC.
DateTimeFormatterBuilder	appendTimeZoneOffset(String zeroOffsetPrintText, String zeroOffsetParseText, boolean showSeparators, int minFields, int maxFields) Instructs the printer to emit text and numbers to display time zone offset from UTC.
DateTimeFormatterBuilder	appendTimeZoneShortName() Instructs the printer to emit a short locale-specific time zone name.
DateTimeFormatterBuilder	appendTimeZoneShortName(Map<String,DateTimeZone> parseLookup) Instructs the printer to emit a short locale-specific time zone name, providing a lookup for parsing.
DateTimeFormatterBuilder	appendTwoDigitWeekyear(int pivot) Instructs the printer to emit a numeric weekyear field which always prints and parses two digits.
DateTimeFormatterBuilder	appendTwoDigitWeekyear(int pivot, boolean lenientParse) Instructs the printer to emit a numeric weekyear field which always prints two digits.
DateTimeFormatterBuilder	appendTwoDigitYear(int pivot) Instructs the printer to emit a numeric year field which always prints and parses two digits.
DateTimeFormatterBuilder	appendTwoDigitYear(int pivot, boolean lenientParse) Instructs the printer to emit a numeric year field which always prints two digits.
DateTimeFormatterBuilder	appendWeekOfWeekyear(int minDigits) Instructs the printer to emit a numeric weekOfWeekyear field.
DateTimeFormatterBuilder	appendWeekyear(int minDigits, int maxDigits) Instructs the printer to emit a numeric weekyear field.
DateTimeFormatterBuilder	appendYear(int minDigits, int maxDigits) Instructs the printer to emit a numeric year field.
DateTimeFormatterBuilder	appendYearOfCentury(int minDigits, int maxDigits) Instructs the printer to emit a numeric year of century field.
DateTimeFormatterBuilder	appendYearOfEra(int minDigits, int maxDigits) Instructs the printer to emit a numeric yearOfEra field.
boolean	canBuildFormatter() Returns true if toFormatter can be called without throwing an UnsupportedOperationException.
boolean	canBuildParser() Returns true if toParser can be called without throwing an UnsupportedOperationException.
boolean	canBuildPrinter() Returns true if toPrinter can be called without throwing an UnsupportedOperationException.
void	clear() Clears out all the appended elements, allowing this builder to be reused.
DateTimeFormatter	toFormatter() Constructs a DateTimeFormatter using all the appended elements.
DateTimeParser	toParser() Internal method to create a DateTimeParser instance using all the appended elements.
DateTimePrinter	toPrinter() Internal method to create a DateTimePrinter instance using all the appended elements.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

DateTimeFormatterBuilder

public DateTimeFormatterBuilder()

Creates a DateTimeFormatterBuilder.

Method Detail

toFormatter

public DateTimeFormatter toFormatter()

Constructs a DateTimeFormatter using all the appended elements.

This is the main method used by applications at the end of the build process to create a usable formatter.

Subsequent changes to this builder do not affect the returned formatter.

The returned formatter may not support both printing and parsing. The methods DateTimeFormatter.isPrinter() and DateTimeFormatter.isParser() will help you determine the state of the formatter.

Throws:

UnsupportedOperationException - if neither printing nor parsing is supported

toPrinter

public DateTimePrinter toPrinter()

Internal method to create a DateTimePrinter instance using all the appended elements.

Most applications will not use this method. If you want a printer in an application, call toFormatter() and just use the printing API.

Subsequent changes to this builder do not affect the returned printer.

Throws:

UnsupportedOperationException - if printing is not supported

toParser

public DateTimeParser toParser()

Internal method to create a DateTimeParser instance using all the appended elements.

Most applications will not use this method. If you want a parser in an application, call toFormatter() and just use the parsing API.

Subsequent changes to this builder do not affect the returned parser.

Throws:

UnsupportedOperationException - if parsing is not supported

canBuildFormatter

public boolean canBuildFormatter()

Returns true if toFormatter can be called without throwing an UnsupportedOperationException.

Returns:

true if a formatter can be built

canBuildPrinter

public boolean canBuildPrinter()

Returns true if toPrinter can be called without throwing an UnsupportedOperationException.

Returns:

true if a printer can be built

canBuildParser

public boolean canBuildParser()

Returns true if toParser can be called without throwing an UnsupportedOperationException.

Returns:

true if a parser can be built

clear

public void clear()

Clears out all the appended elements, allowing this builder to be reused.

append

public DateTimeFormatterBuilder append(DateTimeFormatter formatter)

Appends another formatter.

This extracts the underlying printer and parser and appends them The printer and parser interfaces are the low-level part of the formatting API. Normally, instances are extracted from another formatter. Note however that any formatter specific information, such as the locale, time-zone, chronology, offset parsing or pivot/default year, will not be extracted by this method.

Parameters:

formatter - the formatter to add

Returns:

this DateTimeFormatterBuilder, for chaining

Throws:

IllegalArgumentException - if formatter is null or of an invalid type

append

public DateTimeFormatterBuilder append(DateTimePrinter printer)

Appends just a printer. With no matching parser, a parser cannot be built from this DateTimeFormatterBuilder.

The printer interface is part of the low-level part of the formatting API. Normally, instances are extracted from another formatter. Note however that any formatter specific information, such as the locale, time-zone, chronology, offset parsing or pivot/default year, will not be extracted by this method.

Parameters:

printer - the printer to add, not null

Returns:

this DateTimeFormatterBuilder, for chaining

Throws:

IllegalArgumentException - if printer is null or of an invalid type

append

public DateTimeFormatterBuilder append(DateTimeParser parser)

Appends just a parser. With no matching printer, a printer cannot be built from this builder.

The parser interface is part of the low-level part of the formatting API. Normally, instances are extracted from another formatter. Note however that any formatter specific information, such as the locale, time-zone, chronology, offset parsing or pivot/default year, will not be extracted by this method.

Parameters:

parser - the parser to add, not null

Returns:

this DateTimeFormatterBuilder, for chaining

Throws:

IllegalArgumentException - if parser is null or of an invalid type

append

public DateTimeFormatterBuilder append(DateTimePrinter printer,
                                       DateTimeParser parser)

Appends a printer/parser pair.

The printer and parser interfaces are the low-level part of the formatting API. Normally, instances are extracted from another formatter. Note however that any formatter specific information, such as the locale, time-zone, chronology, offset parsing or pivot/default year, will not be extracted by this method.

Parameters:

printer - the printer to add, not null

parser - the parser to add, not null

Returns:

this DateTimeFormatterBuilder, for chaining

Throws:

IllegalArgumentException - if printer or parser is null or of an invalid type

append

public DateTimeFormatterBuilder append(DateTimePrinter printer,
                                       DateTimeParser[] parsers)

Appends a printer and a set of matching parsers. When parsing, the first parser in the list is selected for parsing. If it fails, the next is chosen, and so on. If none of these parsers succeeds, then the failed position of the parser that made the greatest progress is returned.

Only the printer is optional. In addition, it is illegal for any but the last of the parser array elements to be null. If the last element is null, this represents the empty parser. The presence of an empty parser indicates that the entire array of parse formats is optional.

The printer and parser interfaces are the low-level part of the formatting API. Normally, instances are extracted from another formatter. Note however that any formatter specific information, such as the locale, time-zone, chronology, offset parsing or pivot/default year, will not be extracted by this method.

Parameters:

printer - the printer to add

parsers - the parsers to add

Returns:

this DateTimeFormatterBuilder, for chaining

Throws:

IllegalArgumentException - if any printer or parser is of an invalid type

IllegalArgumentException - if any parser element but the last is null

appendOptional

public DateTimeFormatterBuilder appendOptional(DateTimeParser parser)

Appends just a parser element which is optional. With no matching printer, a printer cannot be built from this DateTimeFormatterBuilder.

The parser interface is part of the low-level part of the formatting API. Normally, instances are extracted from another formatter. Note however that any formatter specific information, such as the locale, time-zone, chronology, offset parsing or pivot/default year, will not be extracted by this method.

Returns:

this DateTimeFormatterBuilder, for chaining

Throws:

IllegalArgumentException - if parser is null or of an invalid type

appendLiteral

public DateTimeFormatterBuilder appendLiteral(char c)

Instructs the printer to emit a specific character, and the parser to expect it. The parser is case-insensitive.

Returns:

this DateTimeFormatterBuilder, for chaining

appendLiteral

public DateTimeFormatterBuilder appendLiteral(String text)

Instructs the printer to emit specific text, and the parser to expect it. The parser is case-insensitive.

Returns:

this DateTimeFormatterBuilder, for chaining

Throws:

IllegalArgumentException - if text is null

appendDecimal

public DateTimeFormatterBuilder appendDecimal(DateTimeFieldType fieldType,
                                              int minDigits,
                                              int maxDigits)

Instructs the printer to emit a field value as a decimal number, and the parser to expect an unsigned decimal number.

Parameters:

fieldType - type of field to append

minDigits - minimum number of digits to print

maxDigits - maximum number of digits to parse, or the estimated maximum number of digits to print

Returns:

this DateTimeFormatterBuilder, for chaining

Throws:

IllegalArgumentException - if field type is null

appendFixedDecimal

public DateTimeFormatterBuilder appendFixedDecimal(DateTimeFieldType fieldType,
                                                   int numDigits)

Instructs the printer to emit a field value as a fixed-width decimal number (smaller numbers will be left-padded with zeros), and the parser to expect an unsigned decimal number with the same fixed width.

Parameters:

fieldType - type of field to append

numDigits - the exact number of digits to parse or print, except if printed value requires more digits

Returns:

this DateTimeFormatterBuilder, for chaining

Throws:

IllegalArgumentException - if field type is null or if numDigits <= 0

Since:

1.5

appendSignedDecimal

public DateTimeFormatterBuilder appendSignedDecimal(DateTimeFieldType fieldType,
                                                    int minDigits,
                                                    int maxDigits)

Instructs the printer to emit a field value as a decimal number, and the parser to expect a signed decimal number.

Parameters:

fieldType - type of field to append

minDigits - minimum number of digits to print

maxDigits - maximum number of digits to parse, or the estimated maximum number of digits to print

Returns:

this DateTimeFormatterBuilder, for chaining

Throws:

IllegalArgumentException - if field type is null

appendFixedSignedDecimal

public DateTimeFormatterBuilder appendFixedSignedDecimal(DateTimeFieldType fieldType,
                                                         int numDigits)

Instructs the printer to emit a field value as a fixed-width decimal number (smaller numbers will be left-padded with zeros), and the parser to expect an signed decimal number with the same fixed width.

Parameters:

fieldType - type of field to append

numDigits - the exact number of digits to parse or print, except if printed value requires more digits

Returns:

this DateTimeFormatterBuilder, for chaining

Throws:

IllegalArgumentException - if field type is null or if numDigits <= 0

Since:

1.5

appendText

public DateTimeFormatterBuilder appendText(DateTimeFieldType fieldType)

Instructs the printer to emit a field value as text, and the parser to expect text.

Parameters:

fieldType - type of field to append

Returns:

this DateTimeFormatterBuilder, for chaining

Throws:

IllegalArgumentException - if field type is null

appendShortText

public DateTimeFormatterBuilder appendShortText(DateTimeFieldType fieldType)

Instructs the printer to emit a field value as short text, and the parser to expect text.

Parameters:

fieldType - type of field to append

Returns:

this DateTimeFormatterBuilder, for chaining

Throws:

IllegalArgumentException - if field type is null

appendFraction

public DateTimeFormatterBuilder appendFraction(DateTimeFieldType fieldType,
                                               int minDigits,
                                               int maxDigits)

Instructs the printer to emit a remainder of time as a decimal fraction, without decimal point. For example, if the field is specified as minuteOfHour and the time is 12:30:45, the value printed is 75. A decimal point is implied, so the fraction is 0.75, or three-quarters of a minute.

Parameters:

fieldType - type of field to append

minDigits - minimum number of digits to print.

maxDigits - maximum number of digits to print or parse.

Returns:

this DateTimeFormatterBuilder, for chaining

Throws:

IllegalArgumentException - if field type is null

appendFractionOfSecond

public DateTimeFormatterBuilder appendFractionOfSecond(int minDigits,
                                                       int maxDigits)

Appends the print/parse of a fractional second.

This reliably handles the case where fractional digits are being handled beyond a visible decimal point. The digits parsed will always be treated as the most significant (numerically largest) digits. Thus '23' will be parsed as 230 milliseconds. Contrast this behaviour to appendMillisOfSecond(int). This method does not print or parse the decimal point itself.

Parameters:

minDigits - minimum number of digits to print

maxDigits - maximum number of digits to print or parse

Returns:

this DateTimeFormatterBuilder, for chaining

appendFractionOfMinute

public DateTimeFormatterBuilder appendFractionOfMinute(int minDigits,
                                                       int maxDigits)

Appends the print/parse of a fractional minute.

This reliably handles the case where fractional digits are being handled beyond a visible decimal point. The digits parsed will always be treated as the most significant (numerically largest) digits. Thus '23' will be parsed as 0.23 minutes (converted to milliseconds). This method does not print or parse the decimal point itself.

Parameters:

minDigits - minimum number of digits to print

maxDigits - maximum number of digits to print or parse

Returns:

this DateTimeFormatterBuilder, for chaining

appendFractionOfHour

public DateTimeFormatterBuilder appendFractionOfHour(int minDigits,
                                                     int maxDigits)

Appends the print/parse of a fractional hour.

This reliably handles the case where fractional digits are being handled beyond a visible decimal point. The digits parsed will always be treated as the most significant (numerically largest) digits. Thus '23' will be parsed as 0.23 hours (converted to milliseconds). This method does not print or parse the decimal point itself.

Parameters:

minDigits - minimum number of digits to print

maxDigits - maximum number of digits to print or parse

Returns:

this DateTimeFormatterBuilder, for chaining

appendFractionOfDay

public DateTimeFormatterBuilder appendFractionOfDay(int minDigits,
                                                    int maxDigits)

Appends the print/parse of a fractional day.

This reliably handles the case where fractional digits are being handled beyond a visible decimal point. The digits parsed will always be treated as the most significant (numerically largest) digits. Thus '23' will be parsed as 0.23 days (converted to milliseconds). This method does not print or parse the decimal point itself.

Parameters:

minDigits - minimum number of digits to print

maxDigits - maximum number of digits to print or parse

Returns:

this DateTimeFormatterBuilder, for chaining

appendMillisOfSecond

public DateTimeFormatterBuilder appendMillisOfSecond(int minDigits)

Instructs the printer to emit a numeric millisOfSecond field.

This method will append a field that prints a three digit value. During parsing the value that is parsed is assumed to be three digits. If less than three digits are present then they will be counted as the smallest parts of the millisecond. This is probably not what you want if you are using the field as a fraction. Instead, a fractional millisecond should be produced using appendFractionOfSecond(int, int).

Parameters:

minDigits - minimum number of digits to print

Returns:

this DateTimeFormatterBuilder, for chaining

appendMillisOfDay

public DateTimeFormatterBuilder appendMillisOfDay(int minDigits)

Instructs the printer to emit a numeric millisOfDay field.

Parameters:

minDigits - minimum number of digits to print

Returns:

this DateTimeFormatterBuilder, for chaining

appendSecondOfMinute

public DateTimeFormatterBuilder appendSecondOfMinute(int minDigits)

Instructs the printer to emit a numeric secondOfMinute field.

Parameters:

minDigits - minimum number of digits to print

Returns:

this DateTimeFormatterBuilder, for chaining

appendSecondOfDay

public DateTimeFormatterBuilder appendSecondOfDay(int minDigits)

Instructs the printer to emit a numeric secondOfDay field.

Parameters:

minDigits - minimum number of digits to print

Returns:

this DateTimeFormatterBuilder, for chaining

appendMinuteOfHour

public DateTimeFormatterBuilder appendMinuteOfHour(int minDigits)

Instructs the printer to emit a numeric minuteOfHour field.

Parameters:

minDigits - minimum number of digits to print

Returns:

this DateTimeFormatterBuilder, for chaining

appendMinuteOfDay

public DateTimeFormatterBuilder appendMinuteOfDay(int minDigits)

Instructs the printer to emit a numeric minuteOfDay field.

Parameters:

minDigits - minimum number of digits to print

Returns:

this DateTimeFormatterBuilder, for chaining

appendHourOfDay

public DateTimeFormatterBuilder appendHourOfDay(int minDigits)

Instructs the printer to emit a numeric hourOfDay field.

Parameters:

minDigits - minimum number of digits to print

Returns:

this DateTimeFormatterBuilder, for chaining

appendClockhourOfDay

public DateTimeFormatterBuilder appendClockhourOfDay(int minDigits)

Instructs the printer to emit a numeric clockhourOfDay field.

Parameters:

minDigits - minimum number of digits to print

Returns:

this DateTimeFormatterBuilder, for chaining

appendHourOfHalfday

public DateTimeFormatterBuilder appendHourOfHalfday(int minDigits)

Instructs the printer to emit a numeric hourOfHalfday field.

Parameters:

minDigits - minimum number of digits to print

Returns:

this DateTimeFormatterBuilder, for chaining

appendClockhourOfHalfday

public DateTimeFormatterBuilder appendClockhourOfHalfday(int minDigits)

Instructs the printer to emit a numeric clockhourOfHalfday field.

Parameters:

minDigits - minimum number of digits to print

Returns:

this DateTimeFormatterBuilder, for chaining

appendDayOfWeek

public DateTimeFormatterBuilder appendDayOfWeek(int minDigits)

Instructs the printer to emit a numeric dayOfWeek field.

Parameters:

minDigits - minimum number of digits to print

Returns:

this DateTimeFormatterBuilder, for chaining

appendDayOfMonth

public DateTimeFormatterBuilder appendDayOfMonth(int minDigits)

Instructs the printer to emit a numeric dayOfMonth field.

Parameters:

minDigits - minimum number of digits to print

Returns:

this DateTimeFormatterBuilder, for chaining

appendDayOfYear

public DateTimeFormatterBuilder appendDayOfYear(int minDigits)

Instructs the printer to emit a numeric dayOfYear field.

Parameters:

minDigits - minimum number of digits to print

Returns:

this DateTimeFormatterBuilder, for chaining

appendWeekOfWeekyear

public DateTimeFormatterBuilder appendWeekOfWeekyear(int minDigits)

Instructs the printer to emit a numeric weekOfWeekyear field.

Parameters:

minDigits - minimum number of digits to print

Returns:

this DateTimeFormatterBuilder, for chaining

appendWeekyear

public DateTimeFormatterBuilder appendWeekyear(int minDigits,
                                               int maxDigits)

Instructs the printer to emit a numeric weekyear field.

Parameters:

minDigits - minimum number of digits to print

maxDigits - maximum number of digits to parse, or the estimated maximum number of digits to print

Returns:

this DateTimeFormatterBuilder, for chaining

appendMonthOfYear

public DateTimeFormatterBuilder appendMonthOfYear(int minDigits)

Instructs the printer to emit a numeric monthOfYear field.

Parameters:

minDigits - minimum number of digits to print

Returns:

this DateTimeFormatterBuilder, for chaining

appendYear

public DateTimeFormatterBuilder appendYear(int minDigits,
                                           int maxDigits)

Instructs the printer to emit a numeric year field.

Parameters:

minDigits - minimum number of digits to print

maxDigits - maximum number of digits to parse, or the estimated maximum number of digits to print

Returns:

this DateTimeFormatterBuilder, for chaining

appendTwoDigitYear

public DateTimeFormatterBuilder appendTwoDigitYear(int pivot)

Instructs the printer to emit a numeric year field which always prints and parses two digits. A pivot year is used during parsing to determine the range of supported years as (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:

pivot - pivot year to use when parsing

Returns:

this DateTimeFormatterBuilder, for chaining

appendTwoDigitYear

public DateTimeFormatterBuilder appendTwoDigitYear(int pivot,
                                                   boolean lenientParse)

Instructs the printer to emit a numeric year field which always prints two digits. A pivot year is used during parsing to determine the range of supported years as (pivot - 50) .. (pivot + 49). If parse is instructed to be lenient and the digit count is not two, it is treated as an absolute year. With lenient parsing, specifying a positive or negative sign before the year also makes it absolute.

Parameters:

pivot - pivot year to use when parsing

lenientParse - when true, if digit count is not two, it is treated as an absolute year

Returns:

this DateTimeFormatterBuilder, for chaining

Since:

1.1

appendTwoDigitWeekyear

public DateTimeFormatterBuilder appendTwoDigitWeekyear(int pivot)

Instructs the printer to emit a numeric weekyear field which always prints and parses two digits. A pivot year is used during parsing to determine the range of supported years as (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:

pivot - pivot weekyear to use when parsing

Returns:

this DateTimeFormatterBuilder, for chaining

appendTwoDigitWeekyear

public DateTimeFormatterBuilder appendTwoDigitWeekyear(int pivot,
                                                       boolean lenientParse)

Instructs the printer to emit a numeric weekyear field which always prints two digits. A pivot year is used during parsing to determine the range of supported years as (pivot - 50) .. (pivot + 49). If parse is instructed to be lenient and the digit count is not two, it is treated as an absolute weekyear. With lenient parsing, specifying a positive or negative sign before the weekyear also makes it absolute.

Parameters:

pivot - pivot weekyear to use when parsing

lenientParse - when true, if digit count is not two, it is treated as an absolute weekyear

Returns:

this DateTimeFormatterBuilder, for chaining

Since:

1.1

appendYearOfEra

public DateTimeFormatterBuilder appendYearOfEra(int minDigits,
                                                int maxDigits)

Instructs the printer to emit a numeric yearOfEra field.

Parameters:

minDigits - minimum number of digits to print

maxDigits - maximum number of digits to parse, or the estimated maximum number of digits to print

Returns:

this DateTimeFormatterBuilder, for chaining

appendYearOfCentury

public DateTimeFormatterBuilder appendYearOfCentury(int minDigits,
                                                    int maxDigits)

Instructs the printer to emit a numeric year of century field.

Parameters:

minDigits - minimum number of digits to print

maxDigits - maximum number of digits to parse, or the estimated maximum number of digits to print

Returns:

this DateTimeFormatterBuilder, for chaining

appendCenturyOfEra

public DateTimeFormatterBuilder appendCenturyOfEra(int minDigits,
                                                   int maxDigits)

Instructs the printer to emit a numeric century of era field.

Parameters:

minDigits - minimum number of digits to print

maxDigits - maximum number of digits to parse, or the estimated maximum number of digits to print

Returns:

this DateTimeFormatterBuilder, for chaining

appendHalfdayOfDayText

public DateTimeFormatterBuilder appendHalfdayOfDayText()

Instructs the printer to emit a locale-specific AM/PM text, and the parser to expect it. The parser is case-insensitive.

Returns:

this DateTimeFormatterBuilder, for chaining

appendDayOfWeekText

public DateTimeFormatterBuilder appendDayOfWeekText()

Instructs the printer to emit a locale-specific dayOfWeek text. The parser will accept a long or short dayOfWeek text, case-insensitive.

Returns:

this DateTimeFormatterBuilder, for chaining

appendDayOfWeekShortText

public DateTimeFormatterBuilder appendDayOfWeekShortText()

Instructs the printer to emit a short locale-specific dayOfWeek text. The parser will accept a long or short dayOfWeek text, case-insensitive.

Returns:

this DateTimeFormatterBuilder, for chaining

appendMonthOfYearText

public DateTimeFormatterBuilder appendMonthOfYearText()

Instructs the printer to emit a short locale-specific monthOfYear text. The parser will accept a long or short monthOfYear text, case-insensitive.

Returns:

this DateTimeFormatterBuilder, for chaining

appendMonthOfYearShortText

public DateTimeFormatterBuilder appendMonthOfYearShortText()

Instructs the printer to emit a locale-specific monthOfYear text. The parser will accept a long or short monthOfYear text, case-insensitive.

Returns:

this DateTimeFormatterBuilder, for chaining

appendEraText

public DateTimeFormatterBuilder appendEraText()

Instructs the printer to emit a locale-specific era text (BC/AD), and the parser to expect it. The parser is case-insensitive.

Returns:

this DateTimeFormatterBuilder, for chaining

appendTimeZoneName

public DateTimeFormatterBuilder appendTimeZoneName()

Instructs the printer to emit a locale-specific time zone name. Using this method prevents parsing, because time zone names are not unique. See appendTimeZoneName(Map).

Returns:

this DateTimeFormatterBuilder, for chaining

appendTimeZoneName

public DateTimeFormatterBuilder appendTimeZoneName(Map<String,DateTimeZone> parseLookup)

Instructs the printer to emit a locale-specific time zone name, providing a lookup for parsing. Time zone names are not unique, thus the API forces you to supply the lookup. The names are searched in the order of the map, thus it is strongly recommended to use a LinkedHashMap or similar.

Parameters:

parseLookup - the table of names, not null

Returns:

this DateTimeFormatterBuilder, for chaining

appendTimeZoneShortName

public DateTimeFormatterBuilder appendTimeZoneShortName()

Instructs the printer to emit a short locale-specific time zone name. Using this method prevents parsing, because time zone names are not unique. See appendTimeZoneShortName(Map).

Returns:

this DateTimeFormatterBuilder, for chaining

appendTimeZoneShortName

public DateTimeFormatterBuilder appendTimeZoneShortName(Map<String,DateTimeZone> parseLookup)

Instructs the printer to emit a short locale-specific time zone name, providing a lookup for parsing. Time zone names are not unique, thus the API forces you to supply the lookup. The names are searched in the order of the map, thus it is strongly recommended to use a LinkedHashMap or similar.

Parameters:

parseLookup - the table of names, null to use the default names

Returns:

this DateTimeFormatterBuilder, for chaining

appendTimeZoneId

public DateTimeFormatterBuilder appendTimeZoneId()

Instructs the printer to emit the identifier of the time zone. From version 2.0, this field can be parsed.

Returns:

this DateTimeFormatterBuilder, for chaining

appendTimeZoneOffset

public DateTimeFormatterBuilder appendTimeZoneOffset(String zeroOffsetText,
                                                     boolean showSeparators,
                                                     int minFields,
                                                     int maxFields)

Instructs the printer to emit text and numbers to display time zone offset from UTC. A parser will use the parsed time zone offset to adjust the datetime.

If zero offset text is supplied, then it will be printed when the zone is zero. During parsing, either the zero offset text, or the offset will be parsed.

Parameters:

zeroOffsetText - the text to use if time zone offset is zero. If null, offset is always shown.

showSeparators - if true, prints ':' separator before minute and second field and prints '.' separator before fraction field.

minFields - minimum number of fields to print, stopping when no more precision is required. 1=hours, 2=minutes, 3=seconds, 4=fraction

maxFields - maximum number of fields to print

Returns:

this DateTimeFormatterBuilder, for chaining

appendTimeZoneOffset

public DateTimeFormatterBuilder appendTimeZoneOffset(String zeroOffsetPrintText,
                                                     String zeroOffsetParseText,
                                                     boolean showSeparators,
                                                     int minFields,
                                                     int maxFields)

Instructs the printer to emit text and numbers to display time zone offset from UTC. A parser will use the parsed time zone offset to adjust the datetime.

If zero offset print text is supplied, then it will be printed when the zone is zero. If zero offset parse text is supplied, then either it or the offset will be parsed.

Parameters:

zeroOffsetPrintText - the text to print if time zone offset is zero. If null, offset is always shown.

zeroOffsetParseText - the text to optionally parse to indicate that the time zone offset is zero. If null, then always use the offset.

showSeparators - if true, prints ':' separator before minute and second field and prints '.' separator before fraction field.

minFields - minimum number of fields to print, stopping when no more precision is required. 1=hours, 2=minutes, 3=seconds, 4=fraction

maxFields - maximum number of fields to print

Returns:

this DateTimeFormatterBuilder, for chaining

Since:

2.0

appendPattern

public DateTimeFormatterBuilder appendPattern(String pattern)

Calls upon DateTimeFormat to parse the pattern and append the results into this builder.

Parameters:

pattern - pattern specification

Throws:

IllegalArgumentException - if the pattern is invalid

See Also:

DateTimeFormat