View Javadoc
1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one or more
3    * contributor license agreements.  See the NOTICE file distributed with
4    * this work for additional information regarding copyright ownership.
5    * The ASF licenses this file to You under the Apache License, Version 2.0
6    * (the "License"); you may not use this file except in compliance with
7    * the License.  You may obtain a copy of the License at
8    *
9    *      http://www.apache.org/licenses/LICENSE-2.0
10   *
11   * Unless required by applicable law or agreed to in writing, software
12   * distributed under the License is distributed on an "AS IS" BASIS,
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   * See the License for the specific language governing permissions and
15   * limitations under the License.
16   */
17  package org.apache.commons.lang3.text;
18  
19  import static java.util.FormattableFlags.LEFT_JUSTIFY;
20  
21  import java.util.Formattable;
22  import java.util.Formatter;
23  
24  import org.apache.commons.lang3.ObjectUtils;
25  import org.apache.commons.lang3.StringUtils;
26  import org.apache.commons.lang3.Validate;
27  
28  /**
29   * <p>Provides utilities for working with the {@code Formattable} interface.</p>
30   *
31   * <p>The {@link Formattable} interface provides basic control over formatting
32   * when using a {@code Formatter}. It is primarily concerned with numeric precision
33   * and padding, and is not designed to allow generalised alternate formats.</p>
34   *
35   * @since Lang 3.0
36   * @deprecated as of 3.6, use commons-text
37   * <a href="https://commons.apache.org/proper/commons-text/javadocs/api-release/org/apache/commons/text/FormattableUtils.html">
38   * FormattableUtils</a> instead
39   */
40  @Deprecated
41  public class FormattableUtils {
42  
43      /**
44       * A format that simply outputs the value as a string.
45       */
46      private static final String SIMPLEST_FORMAT = "%s";
47  
48      /**
49       * <p>{@code FormattableUtils} instances should NOT be constructed in
50       * standard programming. Instead, the methods of the class should be invoked
51       * statically.</p>
52       *
53       * <p>This constructor is public to permit tools that require a JavaBean
54       * instance to operate.</p>
55       */
56      public FormattableUtils() {
57          super();
58      }
59  
60      //-----------------------------------------------------------------------
61      /**
62       * Get the default formatted representation of the specified
63       * {@code Formattable}.
64       *
65       * @param formattable  the instance to convert to a string, not null
66       * @return the resulting string, not null
67       */
68      public static String toString(final Formattable formattable) {
69          return String.format(SIMPLEST_FORMAT, formattable);
70      }
71  
72      /**
73       * Handles the common {@code Formattable} operations of truncate-pad-append,
74       * with no ellipsis on precision overflow, and padding width underflow with
75       * spaces.
76       *
77       * @param seq  the string to handle, not null
78       * @param formatter  the destination formatter, not null
79       * @param flags  the flags for formatting, see {@code Formattable}
80       * @param width  the width of the output, see {@code Formattable}
81       * @param precision  the precision of the output, see {@code Formattable}
82       * @return the {@code formatter} instance, not null
83       */
84      public static Formatter append(final CharSequence seq, final Formatter formatter, final int flags, final int width,
85              final int precision) {
86          return append(seq, formatter, flags, width, precision, ' ', null);
87      }
88  
89      /**
90       * Handles the common {@link Formattable} operations of truncate-pad-append,
91       * with no ellipsis on precision overflow.
92       *
93       * @param seq  the string to handle, not null
94       * @param formatter  the destination formatter, not null
95       * @param flags  the flags for formatting, see {@code Formattable}
96       * @param width  the width of the output, see {@code Formattable}
97       * @param precision  the precision of the output, see {@code Formattable}
98       * @param padChar  the pad character to use
99       * @return the {@code formatter} instance, not null
100      */
101     public static Formatter append(final CharSequence seq, final Formatter formatter, final int flags, final int width,
102             final int precision, final char padChar) {
103         return append(seq, formatter, flags, width, precision, padChar, null);
104     }
105 
106     /**
107      * Handles the common {@link Formattable} operations of truncate-pad-append,
108      * padding width underflow with spaces.
109      *
110      * @param seq  the string to handle, not null
111      * @param formatter  the destination formatter, not null
112      * @param flags  the flags for formatting, see {@code Formattable}
113      * @param width  the width of the output, see {@code Formattable}
114      * @param precision  the precision of the output, see {@code Formattable}
115      * @param ellipsis  the ellipsis to use when precision dictates truncation, null or
116      *  empty causes a hard truncation
117      * @return the {@code formatter} instance, not null
118      */
119     public static Formatter append(final CharSequence seq, final Formatter formatter, final int flags, final int width,
120             final int precision, final CharSequence ellipsis) {
121         return append(seq, formatter, flags, width, precision, ' ', ellipsis);
122     }
123 
124     /**
125      * Handles the common {@link Formattable} operations of truncate-pad-append.
126      *
127      * @param seq  the string to handle, not null
128      * @param formatter  the destination formatter, not null
129      * @param flags  the flags for formatting, see {@code Formattable}
130      * @param width  the width of the output, see {@code Formattable}
131      * @param precision  the precision of the output, see {@code Formattable}
132      * @param padChar  the pad character to use
133      * @param ellipsis  the ellipsis to use when precision dictates truncation, null or
134      *  empty causes a hard truncation
135      * @return the {@code formatter} instance, not null
136      */
137     public static Formatter append(final CharSequence seq, final Formatter formatter, final int flags, final int width,
138             final int precision, final char padChar, final CharSequence ellipsis) {
139         Validate.isTrue(ellipsis == null || precision < 0 || ellipsis.length() <= precision,
140                 "Specified ellipsis '%1$s' exceeds precision of %2$s", ellipsis, Integer.valueOf(precision));
141         final StringBuilder buf = new StringBuilder(seq);
142         if (precision >= 0 && precision < seq.length()) {
143             final CharSequence _ellipsis = ObjectUtils.defaultIfNull(ellipsis, StringUtils.EMPTY);
144             buf.replace(precision - _ellipsis.length(), seq.length(), _ellipsis.toString());
145         }
146         final boolean leftJustify = (flags & LEFT_JUSTIFY) == LEFT_JUSTIFY;
147         for (int i = buf.length(); i < width; i++) {
148             buf.insert(leftJustify ? i : 0, padChar);
149         }
150         formatter.format(buf.toString());
151         return formatter;
152     }
153 
154 }