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 java.util.Formattable;
20 import java.util.FormattableFlags;
21 import java.util.Formatter;
22
23 import org.apache.commons.lang3.ObjectUtils;
24 import org.apache.commons.lang3.StringUtils;
25 import org.apache.commons.lang3.Validate;
26
27 /**
28 * Provides utilities for working with the {@link Formattable} interface.
29 *
30 * <p>The {@link Formattable} interface provides basic control over formatting
31 * when using a {@link Formatter}. It is primarily concerned with numeric precision
32 * and padding, and is not designed to allow generalised alternate formats.</p>
33 *
34 * @since 3.0
35 * @deprecated As of 3.6, use Apache Commons Text
36 * <a href="https://commons.apache.org/proper/commons-text/javadocs/api-release/org/apache/commons/text/FormattableUtils.html">
37 * FormattableUtils</a> instead
38 */
39 @Deprecated
40 public class FormattableUtils {
41
42 /**
43 * A format that simply outputs the value as a string.
44 */
45 private static final String SIMPLEST_FORMAT = "%s";
46
47 /**
48 * Handles the common {@link Formattable} operations of truncate-pad-append,
49 * with no ellipsis on precision overflow, and padding width underflow with
50 * spaces.
51 *
52 * @param seq the string to handle, not null
53 * @param formatter the destination formatter, not null
54 * @param flags the flags for formatting, see {@link Formattable}
55 * @param width the width of the output, see {@link Formattable}
56 * @param precision the precision of the output, see {@link Formattable}
57 * @return the {@code formatter} instance, not null
58 */
59 public static Formatter append(final CharSequence seq, final Formatter formatter, final int flags, final int width,
60 final int precision) {
61 return append(seq, formatter, flags, width, precision, ' ', null);
62 }
63
64 /**
65 * Handles the common {@link Formattable} operations of truncate-pad-append,
66 * with no ellipsis on precision overflow.
67 *
68 * @param seq the string to handle, not null
69 * @param formatter the destination formatter, not null
70 * @param flags the flags for formatting, see {@link Formattable}
71 * @param width the width of the output, see {@link Formattable}
72 * @param precision the precision of the output, see {@link Formattable}
73 * @param padChar the pad character to use
74 * @return the {@code formatter} instance, not null
75 */
76 public static Formatter append(final CharSequence seq, final Formatter formatter, final int flags, final int width,
77 final int precision, final char padChar) {
78 return append(seq, formatter, flags, width, precision, padChar, null);
79 }
80
81 /**
82 * Handles the common {@link Formattable} operations of truncate-pad-append.
83 *
84 * @param seq the string to handle, not null
85 * @param formatter the destination formatter, not null
86 * @param flags the flags for formatting, see {@link Formattable}
87 * @param width the width of the output, see {@link Formattable}
88 * @param precision the precision of the output, see {@link Formattable}
89 * @param padChar the pad character to use
90 * @param ellipsis the ellipsis to use when precision dictates truncation, null or
91 * empty causes a hard truncation
92 * @return the {@code formatter} instance, not null
93 */
94 public static Formatter append(final CharSequence seq, final Formatter formatter, final int flags, final int width,
95 final int precision, final char padChar, final CharSequence ellipsis) {
96 Validate.isTrue(ellipsis == null || precision < 0 || ellipsis.length() <= precision,
97 "Specified ellipsis '%1$s' exceeds precision of %2$s", ellipsis, Integer.valueOf(precision));
98 final StringBuilder buf = new StringBuilder(seq);
99 if (precision >= 0 && precision < seq.length()) {
100 final CharSequence actualEllipsis = ObjectUtils.defaultIfNull(ellipsis, StringUtils.EMPTY);
101 buf.replace(precision - actualEllipsis.length(), seq.length(), actualEllipsis.toString());
102 }
103 final boolean leftJustify = (flags & FormattableFlags.LEFT_JUSTIFY) == FormattableFlags.LEFT_JUSTIFY;
104 for (int i = buf.length(); i < width; i++) {
105 buf.insert(leftJustify ? i : 0, padChar);
106 }
107 formatter.format(buf.toString());
108 return formatter;
109 }
110
111 /**
112 * Handles the common {@link Formattable} operations of truncate-pad-append,
113 * padding width underflow with spaces.
114 *
115 * @param seq the string to handle, not null
116 * @param formatter the destination formatter, not null
117 * @param flags the flags for formatting, see {@link Formattable}
118 * @param width the width of the output, see {@link Formattable}
119 * @param precision the precision of the output, see {@link Formattable}
120 * @param ellipsis the ellipsis to use when precision dictates truncation, null or
121 * empty causes a hard truncation
122 * @return the {@code formatter} instance, not null
123 */
124 public static Formatter append(final CharSequence seq, final Formatter formatter, final int flags, final int width,
125 final int precision, final CharSequence ellipsis) {
126 return append(seq, formatter, flags, width, precision, ' ', ellipsis);
127 }
128
129 /**
130 * Gets the default formatted representation of the specified
131 * {@link Formattable}.
132 *
133 * @param formattable the instance to convert to a string, not null
134 * @return the resulting string, not null
135 */
136 public static String toString(final Formattable formattable) {
137 return String.format(SIMPLEST_FORMAT, formattable);
138 }
139
140 /**
141 * {@link FormattableUtils} instances should NOT be constructed in
142 * standard programming. Instead, the methods of the class should be invoked
143 * statically.
144 *
145 * <p>This constructor is public to permit tools that require a JavaBean
146 * instance to operate.</p>
147 */
148 public FormattableUtils() {
149 }
150
151 }