< prev index next >

src/java.base/share/classes/java/time/format/DateTimeFormatterBuilder.java

Print this page




1261      * If the zone is a {@code ZoneOffset} it will be printed using the
1262      * result of {@link ZoneOffset#getId()}.
1263      * If the zone is not an offset, the textual name will be looked up
1264      * for the locale set in the {@link DateTimeFormatter}.
1265      * If the lookup for text does not find any suitable result, then the
1266      * {@link ZoneId#getId() ID} will be printed.
1267      * If the zone cannot be obtained then an exception is thrown unless the
1268      * section of the formatter is optional.
1269      * <p>
1270      * During parsing, either the textual zone name, the zone ID or the offset
1271      * is accepted. Many textual zone names are not unique, such as CST can be
1272      * for both "Central Standard Time" and "China Standard Time". In this
1273      * situation, the zone id will be determined by the region information from
1274      * formatter's  {@link DateTimeFormatter#getLocale() locale} and the standard
1275      * zone id for that area, for example, America/New_York for the America Eastern zone.
1276      * The {@link #appendGenericZoneText(TextStyle, Set)} may be used
1277      * to specify a set of preferred {@link ZoneId} in this situation.
1278      *
1279      * @param textStyle  the text style to use, not null
1280      * @return this, for chaining, not null

1281      */
1282     public DateTimeFormatterBuilder appendGenericZoneText(TextStyle textStyle) {
1283         appendInternal(new ZoneTextPrinterParser(textStyle, null, true));
1284         return this;
1285     }
1286 
1287     /**
1288      * Appends the generic time-zone name, such as 'Pacific Time', to the formatter.
1289      * <p>
1290      * This appends an instruction to format/parse the generic textual
1291      * name of the zone to the builder. The generic name is the same throughout the whole
1292      * year, ignoring any daylight saving changes. For example, 'Pacific Time' is the
1293      * generic name, whereas 'Pacific Standard Time' and 'Pacific Daylight Time' are the
1294      * specific names, see {@link #appendZoneText(TextStyle)}.
1295      * <p>
1296      * This method also allows a set of preferred {@link ZoneId} to be
1297      * specified for parsing. The matched preferred zone id will be used if the
1298      * textural zone name being parsed is not unique.
1299      * <p>
1300      * See {@link #appendGenericZoneText(TextStyle)} for details about
1301      * formatting and parsing.
1302      *
1303      * @param textStyle  the text style to use, not null
1304      * @param preferredZones  the set of preferred zone ids, not null
1305      * @return this, for chaining, not null

1306      */
1307     public DateTimeFormatterBuilder appendGenericZoneText(TextStyle textStyle,
1308                                                           Set<ZoneId> preferredZones) {
1309         appendInternal(new ZoneTextPrinterParser(textStyle, preferredZones, true));
1310         return this;
1311     }
1312 
1313     //-----------------------------------------------------------------------
1314     /**
1315      * Appends the chronology ID, such as 'ISO' or 'ThaiBuddhist', to the formatter.
1316      * <p>
1317      * This appends an instruction to format/parse the chronology ID to the builder.
1318      * <p>
1319      * During formatting, the chronology is obtained using a mechanism equivalent
1320      * to querying the temporal with {@link TemporalQueries#chronology()}.
1321      * It will be printed using the result of {@link Chronology#getId()}.
1322      * If the chronology cannot be obtained then an exception is thrown unless the
1323      * section of the formatter is optional.
1324      * <p>
1325      * During parsing, the chronology is parsed and must match one of the chronologies




1261      * If the zone is a {@code ZoneOffset} it will be printed using the
1262      * result of {@link ZoneOffset#getId()}.
1263      * If the zone is not an offset, the textual name will be looked up
1264      * for the locale set in the {@link DateTimeFormatter}.
1265      * If the lookup for text does not find any suitable result, then the
1266      * {@link ZoneId#getId() ID} will be printed.
1267      * If the zone cannot be obtained then an exception is thrown unless the
1268      * section of the formatter is optional.
1269      * <p>
1270      * During parsing, either the textual zone name, the zone ID or the offset
1271      * is accepted. Many textual zone names are not unique, such as CST can be
1272      * for both "Central Standard Time" and "China Standard Time". In this
1273      * situation, the zone id will be determined by the region information from
1274      * formatter's  {@link DateTimeFormatter#getLocale() locale} and the standard
1275      * zone id for that area, for example, America/New_York for the America Eastern zone.
1276      * The {@link #appendGenericZoneText(TextStyle, Set)} may be used
1277      * to specify a set of preferred {@link ZoneId} in this situation.
1278      *
1279      * @param textStyle  the text style to use, not null
1280      * @return this, for chaining, not null
1281      * @since 9
1282      */
1283     public DateTimeFormatterBuilder appendGenericZoneText(TextStyle textStyle) {
1284         appendInternal(new ZoneTextPrinterParser(textStyle, null, true));
1285         return this;
1286     }
1287 
1288     /**
1289      * Appends the generic time-zone name, such as 'Pacific Time', to the formatter.
1290      * <p>
1291      * This appends an instruction to format/parse the generic textual
1292      * name of the zone to the builder. The generic name is the same throughout the whole
1293      * year, ignoring any daylight saving changes. For example, 'Pacific Time' is the
1294      * generic name, whereas 'Pacific Standard Time' and 'Pacific Daylight Time' are the
1295      * specific names, see {@link #appendZoneText(TextStyle)}.
1296      * <p>
1297      * This method also allows a set of preferred {@link ZoneId} to be
1298      * specified for parsing. The matched preferred zone id will be used if the
1299      * textural zone name being parsed is not unique.
1300      * <p>
1301      * See {@link #appendGenericZoneText(TextStyle)} for details about
1302      * formatting and parsing.
1303      *
1304      * @param textStyle  the text style to use, not null
1305      * @param preferredZones  the set of preferred zone ids, not null
1306      * @return this, for chaining, not null
1307      * @since 9
1308      */
1309     public DateTimeFormatterBuilder appendGenericZoneText(TextStyle textStyle,
1310                                                           Set<ZoneId> preferredZones) {
1311         appendInternal(new ZoneTextPrinterParser(textStyle, preferredZones, true));
1312         return this;
1313     }
1314 
1315     //-----------------------------------------------------------------------
1316     /**
1317      * Appends the chronology ID, such as 'ISO' or 'ThaiBuddhist', to the formatter.
1318      * <p>
1319      * This appends an instruction to format/parse the chronology ID to the builder.
1320      * <p>
1321      * During formatting, the chronology is obtained using a mechanism equivalent
1322      * to querying the temporal with {@link TemporalQueries#chronology()}.
1323      * It will be printed using the result of {@link Chronology#getId()}.
1324      * If the chronology cannot be obtained then an exception is thrown unless the
1325      * section of the formatter is optional.
1326      * <p>
1327      * During parsing, the chronology is parsed and must match one of the chronologies


< prev index next >