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