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 */ 017package org.apache.commons.lang3.text; 018 019import java.util.Formattable; 020import java.util.FormattableFlags; 021import java.util.Formatter; 022 023import org.apache.commons.lang3.ObjectUtils; 024import org.apache.commons.lang3.StringUtils; 025import org.apache.commons.lang3.Validate; 026 027/** 028 * Provides utilities for working with the {@link Formattable} interface. 029 * 030 * <p>The {@link Formattable} interface provides basic control over formatting 031 * when using a {@link Formatter}. It is primarily concerned with numeric precision 032 * and padding, and is not designed to allow generalised alternate formats.</p> 033 * 034 * @since 3.0 035 * @deprecated As of 3.6, use Apache Commons Text 036 * <a href="https://commons.apache.org/proper/commons-text/javadocs/api-release/org/apache/commons/text/FormattableUtils.html"> 037 * FormattableUtils</a> instead 038 */ 039@Deprecated 040public class FormattableUtils { 041 042 /** 043 * A format that simply outputs the value as a string. 044 */ 045 private static final String SIMPLEST_FORMAT = "%s"; 046 047 /** 048 * {@link FormattableUtils} instances should NOT be constructed in 049 * standard programming. Instead, the methods of the class should be invoked 050 * statically. 051 * 052 * <p>This constructor is public to permit tools that require a JavaBean 053 * instance to operate.</p> 054 */ 055 public FormattableUtils() { 056 } 057 058 /** 059 * Gets the default formatted representation of the specified 060 * {@link 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(final Formattable formattable) { 066 return String.format(SIMPLEST_FORMAT, formattable); 067 } 068 069 /** 070 * Handles the common {@link 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 {@link Formattable} 077 * @param width the width of the output, see {@link Formattable} 078 * @param precision the precision of the output, see {@link Formattable} 079 * @return the {@code formatter} instance, not null 080 */ 081 public static Formatter append(final CharSequence seq, final Formatter formatter, final int flags, final int width, 082 final 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 {@link Formattable} 093 * @param width the width of the output, see {@link Formattable} 094 * @param precision the precision of the output, see {@link Formattable} 095 * @param padChar the pad character to use 096 * @return the {@code formatter} instance, not null 097 */ 098 public static Formatter append(final CharSequence seq, final Formatter formatter, final int flags, final int width, 099 final int precision, final 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 {@link Formattable} 110 * @param width the width of the output, see {@link Formattable} 111 * @param precision the precision of the output, see {@link 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(final CharSequence seq, final Formatter formatter, final int flags, final int width, 117 final int precision, final 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 {@link Formattable} 127 * @param width the width of the output, see {@link Formattable} 128 * @param precision the precision of the output, see {@link 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(final CharSequence seq, final Formatter formatter, final int flags, final int width, 135 final int precision, final char padChar, final 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 final StringBuilder buf = new StringBuilder(seq); 139 if (precision >= 0 && precision < seq.length()) { 140 final CharSequence actualEllipsis = ObjectUtils.defaultIfNull(ellipsis, StringUtils.EMPTY); 141 buf.replace(precision - actualEllipsis.length(), seq.length(), actualEllipsis.toString()); 142 } 143 final boolean leftJustify = (flags & FormattableFlags.LEFT_JUSTIFY) == FormattableFlags.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}