import {DateTimeFormatterBuilder} from 'js-joda/src/format/DateTimeFormatterBuilder.js'DateTimeFormatterBuilder
Constructor Summary
| Public Constructor | ||
| public |
constructor(parent: DateTimeFormatterBuilder, optional: boolean) Constructs a new instance of the builder. |
|
Method Summary
| Public Methods | ||
| public |
append(formatter: DateTimeFormatter): DateTimeFormatterBuilder Appends all the elements of a formatter to the builder. |
|
| public |
appendFraction(field: TemporalField, minWidth: Number, maxWidth: Number, decimalPoint: boolean): DateTimeFormatterBuilder Appends the fractional value of a date-time field to the formatter. |
|
| public |
appendInstant(fractionalDigits: number): DateTimeFormatterBuilder Appends an instant using ISO-8601 to the formatter with control over the number of fractional digits. |
|
| public |
appendLiteral(literal: *): DateTimeFormatterBuilder Appends a string literal to the formatter. |
|
| public |
Appends the zone offset, such as '+01:00', to the formatter. |
|
| public |
appendValue(): * appendValue function overloading |
|
| public |
Appends the time-zone ID, such as 'Europe/Paris' or '+02:00', to the formatter. |
|
| public |
Ends an optional section. |
|
| public |
Mark the start of an optional section. |
|
| public |
Changes the parse style to be case insensitive for the remainder of the formatter. |
|
| public |
Changes the parse style to be case sensitive for the remainder of the formatter. |
|
| public |
Changes the parse style to be lenient for the remainder of the formatter. |
|
| public |
Changes the parse style to be strict for the remainder of the formatter. |
|
| public |
toFormatter(resolverStyle: *): * Completes this builder by creating the DateTimeFormatter. |
|
Public Constructors
public constructor(parent: DateTimeFormatterBuilder, optional: boolean) source
Constructs a new instance of the builder.
Params:
| Name | Type | Attribute | Description |
| parent | DateTimeFormatterBuilder | the parent builder, not null |
|
| optional | boolean | whether the formatter is optional, not null |
Public Methods
public append(formatter: DateTimeFormatter): DateTimeFormatterBuilder source
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.
Params:
| Name | Type | Attribute | Description |
| formatter | DateTimeFormatter | the formatter to add, not null |
public appendFraction(field: TemporalField, minWidth: Number, maxWidth: Number, decimalPoint: boolean): DateTimeFormatterBuilder source
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.
Params:
| Name | Type | Attribute | Description |
| field | TemporalField | the field to append, not null |
|
| minWidth | Number | the minimum width of the field excluding the decimal point, from 0 to 9 |
|
| maxWidth | Number | the maximum width of the field excluding the decimal point, from 1 to 9 |
|
| decimalPoint | boolean | whether to output the localized decimal point symbol |
Throw:
* |
IllegalArgumentException if the field has a variable set of valid values or either width is invalid |
public appendInstant(fractionalDigits: number): DateTimeFormatterBuilder source
Appends an instant using ISO-8601 to the formatter with control over the number of fractional digits.
Instants have a fixed output format, although this method provides some control over the fractional digits. They are converted to a date-time with a zone-offset of UTC and printed using the standard ISO-8601 format. The localized decimal style is not used.
The {@code this.fractionalDigits} parameter allows the output of the fractional second to be controlled. Specifying zero will cause no fractional digits to be output. From 1 to 9 will output an increasing number of digits, using zero right-padding if necessary. The special value -1 is used to output as many digits as necessary to avoid any trailing zeroes.
When parsing in strict mode, the number of parsed digits must match the fractional digits. When parsing in lenient mode, any number of fractional digits from zero to nine are accepted.
The instant is obtained using {@link ChronoField#INSTANT_SECONDS INSTANT_SECONDS} and optionally (@code NANO_OF_SECOND). The value of {@code INSTANT_SECONDS} may be outside the maximum range of {@code LocalDateTime}.
The {@linkplain ResolverStyle resolver style} has no effect on instant parsing. The end-of-day time of '24:00' is handled as midnight at the start of the following day. The leap-second time of '23:59:59' is handled to some degree, see {@link DateTimeFormatter#parsedLeapSecond()} for full details.
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)}.
Params:
| Name | Type | Attribute | Description |
| fractionalDigits | number |
|
the number of fractional second digits to format with, from 0 to 9, or -1 to use as many digits as necessary |
public appendLiteral(literal: *): DateTimeFormatterBuilder source
Appends a string literal to the formatter.
This string will be output during a print.
If the literal is empty, nothing is added to the formatter.
Params:
| Name | Type | Attribute | Description |
| literal | * | the literal to append, not null |
public appendOffsetId(): DateTimeFormatterBuilder source
Appends the zone offset, such as '+01:00', to the formatter.
This appends an instruction to print/parse the offset ID to the builder. This is equivalent to calling {@code appendOffset("HH:MM:ss", "Z")}.
public appendZoneId(): DateTimeFormatterBuilder source
Appends the time-zone ID, such as 'Europe/Paris' or '+02:00', to the formatter.
This appends an instruction to print/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 printing, the zone is obtained using a mechanism equivalent to querying the temporal with {@link TemporalQueries#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 zone is parsed and must match a known zone or offset. If the zone cannot be parsed then an exception is thrown unless the section of the formatter is optional.
public optionalEnd(): DateTimeFormatterBuilder source
Ends an optional section.
The output of printing 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 printing, 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 printing, 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.
Throw:
* |
IllegalStateException if there was no previous call to {@code optionalStart} |
public optionalStart(): DateTimeFormatterBuilder source
Mark the start of an optional section.
The output of printing 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 printing, 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 printing, 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.
public parseCaseInsensitive(): DateTimeFormatterBuilder source
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 sensitive 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.
public parseCaseSensitive(): DateTimeFormatterBuilder source
Changes the parse style to be case sensitive 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 sensitive mode. See #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}.
public parseLenient(): DateTimeFormatterBuilder source
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 strict 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.
public parseStrict(): DateTimeFormatterBuilder source
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.
public toFormatter(resolverStyle: *): * source
Completes this builder by creating the DateTimeFormatter.
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}.
Params:
| Name | Type | Attribute | Description |
| resolverStyle | * | the new resolver style |
Return:
| * | the created formatter, not null |