    001    /*
    002     * Licensed to the Apache Software Foundation (ASF) under one or more
    003     * contributor license agreements.  See the NOTICE file distributed with
    004     * this work for additional information regarding copyright ownership.
    005     * The ASF licenses this file to You under the Apache License, Version 2.0
    006     * (the "License"); you may not use this file except in compliance with
    007     * the License.  You may obtain a copy of the License at
    008     *
    009     *      http://www.apache.org/licenses/LICENSE-2.0
    010     *
    011     * Unless required by applicable law or agreed to in writing, software
    012     * distributed under the License is distributed on an "AS IS" BASIS,
    013     * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    014     * See the License for the specific language governing permissions and
    015     * limitations under the License.
    016     */
    017    package org.apache.commons.lang3.text;
    018
    019    import static java.util.FormattableFlags.LEFT_JUSTIFY;
    020
    021    import java.util.Formattable;
    022    import java.util.Formatter;
    023
    024    import org.apache.commons.lang3.ObjectUtils;
    025    import org.apache.commons.lang3.StringUtils;
    026    import org.apache.commons.lang3.Validate;
    027
    028    /**
    029     * <p>Provides utilities for working with the {@code Formattable} interface.</p>
    030     *
    031     * <p>The {@link Formattable} interface provides basic control over formatting
    032     * when using a {@code Formatter}. It is primarily concerned with numeric precision
    033     * and padding, and is not designed to allow generalised alternate formats.</p>
    034     *
    035     * @since Lang 3.0
    036     * @version $Id: FormattableUtils.java 1132390 2011-06-05 12:45:10Z sebb $
    037     */
    038    public class FormattableUtils {
    039
    040        /**
    041         * A format that simply outputs the value as a string.
    042         */
    043        private static final String SIMPLEST_FORMAT = "%s";
    044
    045        /**
    046         * <p>{@code FormattableUtils} instances should NOT be constructed in
    047         * standard programming. Instead, the methods of the class should be invoked
    048         * statically.</p>
    049         *
    050         * <p>This constructor is public to permit tools that require a JavaBean
    051         * instance to operate.</p>
    052         */
    053        public FormattableUtils() {
    054            super();
    055        }
    056
    057        //-----------------------------------------------------------------------
    058        /**
    059         * Get the default formatted representation of the specified
    060         * {@code Formattable}.
    061         *
    062         * @param formattable  the instance to convert to a string, not null
    063         * @return the resulting string, not null
    064         */
    065        public static String toString(Formattable formattable) {
    066            return String.format(SIMPLEST_FORMAT, formattable);
    067        }
    068
    069        /**
    070         * Handles the common {@code Formattable} operations of truncate-pad-append,
    071         * with no ellipsis on precision overflow, and padding width underflow with
    072         * spaces.
    073         *
    074         * @param seq  the string to handle, not null
    075         * @param formatter  the destination formatter, not null
    076         * @param flags  the flags for formatting, see {@code Formattable}
    077         * @param width  the width of the output, see {@code Formattable}
    078         * @param precision  the precision of the output, see {@code Formattable}
    079         * @return the {@code formatter} instance, not null
    080         */
    081        public static Formatter append(CharSequence seq, Formatter formatter, int flags, int width,
    082                int precision) {
    083            return append(seq, formatter, flags, width, precision, ' ', null);
    084        }
    085
    086        /**
    087         * Handles the common {@link Formattable} operations of truncate-pad-append,
    088         * with no ellipsis on precision overflow.
    089         *
    090         * @param seq  the string to handle, not null
    091         * @param formatter  the destination formatter, not null
    092         * @param flags  the flags for formatting, see {@code Formattable}
    093         * @param width  the width of the output, see {@code Formattable}
    094         * @param precision  the precision of the output, see {@code Formattable}
    095         * @param padChar  the pad character to use
    096         * @return the {@code formatter} instance, not null
    097         */
    098        public static Formatter append(CharSequence seq, Formatter formatter, int flags, int width,
    099                int precision, char padChar) {
    100            return append(seq, formatter, flags, width, precision, padChar, null);
    101        }
    102
    103        /**
    104         * Handles the common {@link Formattable} operations of truncate-pad-append,
    105         * padding width underflow with spaces.
    106         *
    107         * @param seq  the string to handle, not null
    108         * @param formatter  the destination formatter, not null
    109         * @param flags  the flags for formatting, see {@code Formattable}
    110         * @param width  the width of the output, see {@code Formattable}
    111         * @param precision  the precision of the output, see {@code Formattable}
    112         * @param ellipsis  the ellipsis to use when precision dictates truncation, null or
    113         *  empty causes a hard truncation
    114         * @return the {@code formatter} instance, not null
    115         */
    116        public static Formatter append(CharSequence seq, Formatter formatter, int flags, int width,
    117                int precision, CharSequence ellipsis) {
    118            return append(seq, formatter, flags, width, precision, ' ', ellipsis);
    119        }
    120
    121        /**
    122         * Handles the common {@link Formattable} operations of truncate-pad-append.
    123         *
    124         * @param seq  the string to handle, not null
    125         * @param formatter  the destination formatter, not null
    126         * @param flags  the flags for formatting, see {@code Formattable}
    127         * @param width  the width of the output, see {@code Formattable}
    128         * @param precision  the precision of the output, see {@code Formattable}
    129         * @param padChar  the pad character to use
    130         * @param ellipsis  the ellipsis to use when precision dictates truncation, null or
    131         *  empty causes a hard truncation
    132         * @return the {@code formatter} instance, not null
    133         */
    134        public static Formatter append(CharSequence seq, Formatter formatter, int flags, int width,
    135                int precision, char padChar, CharSequence ellipsis) {
    136            Validate.isTrue(ellipsis == null || precision < 0 || ellipsis.length() <= precision,
    137                    "Specified ellipsis '%1$s' exceeds precision of %2$s", ellipsis, Integer.valueOf(precision));
    138            StringBuilder buf = new StringBuilder(seq);
    139            if (precision >= 0 && precision < seq.length()) {
    140                CharSequence _ellipsis = ObjectUtils.defaultIfNull(ellipsis, StringUtils.EMPTY);
    141                buf.replace(precision - _ellipsis.length(), seq.length(), _ellipsis.toString());
    142            }
    143            boolean leftJustify = (flags & LEFT_JUSTIFY) == LEFT_JUSTIFY;
    144            for (int i = buf.length(); i < width; i++) {
    145                buf.insert(leftJustify ? i : 0, padChar);
    146            }
    147            formatter.format(buf.toString());
    148            return formatter;
    149        }
    150
    151    }