1/* Licensed to the Apache Software Foundation (ASF) under one or more
2 * contributor license agreements.  See the NOTICE file distributed with
3 * this work for additional information regarding copyright ownership.
4 * The ASF licenses this file to You under the Apache License, Version 2.0
5 * (the "License"); you may not use this file except in compliance with
6 * the License.  You may obtain a copy of the License at
7 *
8 *     http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17package java.util;
18
19/**
20 * Classes that handle custom formatting for the 's' specifier of {@code Formatter}
21 * should implement the {@code Formattable} interface. It gives basic control over
22 * formatting objects.
23 *
24 * @see Formatter
25 */
26
27public interface Formattable {
28
29    /**
30     * Formats the object using the specified {@code Formatter}.
31     *
32     * @param formatter
33     *            the {@code Formatter} to use.
34     * @param flags
35     *            the flags applied to the output format, which is a bitmask
36     *            that is any combination of {@code FormattableFlags.LEFT_JUSTIFY},
37     *            {@code FormattableFlags.UPPERCASE}, and {@code FormattableFlags.ALTERNATE}. If
38     *            no such flag is set, the output is formatted by the default
39     *            formatting of the implementation.
40     * @param width
41     *            the minimum number of characters that should be written to the
42     *            output. If the length of the converted value is less than {@code width}
43     *            Additional space characters (' ') are added to the output if the
44     *            as needed to make up the difference. These spaces are added at the
45     *            beginning by default unless the flag
46     *            FormattableFlags.LEFT_JUSTIFY is set, which denotes that
47     *            padding should be added at the end. If width is -1, then
48     *            minimum length is not enforced.
49     * @param precision
50     *            the maximum number of characters that can be written to the
51     *            output. The length of the output is trimmed down to this size
52     *            before the width padding is applied. If the precision
53     *            is -1, then maximum length is not enforced.
54     * @throws IllegalFormatException
55     *             if any of the parameters is not supported.
56     */
57    void formatTo(Formatter formatter, int flags, int width, int precision)
58            throws IllegalFormatException;
59}
60