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 static java.util.FormattableFlags.LEFT_JUSTIFY; 020 021import java.util.Formattable; 022import java.util.Formatter; 023 024import org.apache.commons.lang3.ObjectUtils; 025import org.apache.commons.lang3.StringUtils; 026import 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 3.0 036 * @deprecated as of 3.6, use commons-text 037 * <a href="https://commons.apache.org/proper/commons-text/javadocs/api-release/org/apache/commons/text/FormattableUtils.html"> 038 * FormattableUtils</a> instead 039 */ 040@Deprecated 041public class FormattableUtils { 042 043 /** 044 * A format that simply outputs the value as a string. 045 */ 046 private static final String SIMPLEST_FORMAT = "%s"; 047 048 /** 049 * <p>{@code FormattableUtils} instances should NOT be constructed in 050 * standard programming. Instead, the methods of the class should be invoked 051 * statically.</p> 052 * 053 * <p>This constructor is public to permit tools that require a JavaBean 054 * instance to operate.</p> 055 */ 056 public FormattableUtils() { 057 } 058 059 //----------------------------------------------------------------------- 060 /** 061 * Gets the default formatted representation of the specified 062 * {@code Formattable}. 063 * 064 * @param formattable the instance to convert to a string, not null 065 * @return the resulting string, not null 066 */ 067 public static String toString(final Formattable formattable) { 068 return String.format(SIMPLEST_FORMAT, formattable); 069 } 070 071 /** 072 * Handles the common {@code Formattable} operations of truncate-pad-append, 073 * with no ellipsis on precision overflow, and padding width underflow with 074 * spaces. 075 * 076 * @param seq the string to handle, not null 077 * @param formatter the destination formatter, not null 078 * @param flags the flags for formatting, see {@code Formattable} 079 * @param width the width of the output, see {@code Formattable} 080 * @param precision the precision of the output, see {@code Formattable} 081 * @return the {@code formatter} instance, not null 082 */ 083 public static Formatter append(final CharSequence seq, final Formatter formatter, final int flags, final int width, 084 final int precision) { 085 return append(seq, formatter, flags, width, precision, ' ', null); 086 } 087 088 /** 089 * Handles the common {@link Formattable} operations of truncate-pad-append, 090 * with no ellipsis on precision overflow. 091 * 092 * @param seq the string to handle, not null 093 * @param formatter the destination formatter, not null 094 * @param flags the flags for formatting, see {@code Formattable} 095 * @param width the width of the output, see {@code Formattable} 096 * @param precision the precision of the output, see {@code Formattable} 097 * @param padChar the pad character to use 098 * @return the {@code formatter} instance, not null 099 */ 100 public static Formatter append(final CharSequence seq, final Formatter formatter, final int flags, final int width, 101 final int precision, final char padChar) { 102 return append(seq, formatter, flags, width, precision, padChar, null); 103 } 104 105 /** 106 * Handles the common {@link Formattable} operations of truncate-pad-append, 107 * padding width underflow with spaces. 108 * 109 * @param seq the string to handle, not null 110 * @param formatter the destination formatter, not null 111 * @param flags the flags for formatting, see {@code Formattable} 112 * @param width the width of the output, see {@code Formattable} 113 * @param precision the precision of the output, see {@code Formattable} 114 * @param ellipsis the ellipsis to use when precision dictates truncation, null or 115 * empty causes a hard truncation 116 * @return the {@code formatter} instance, not null 117 */ 118 public static Formatter append(final CharSequence seq, final Formatter formatter, final int flags, final int width, 119 final int precision, final CharSequence ellipsis) { 120 return append(seq, formatter, flags, width, precision, ' ', ellipsis); 121 } 122 123 /** 124 * Handles the common {@link Formattable} operations of truncate-pad-append. 125 * 126 * @param seq the string to handle, not null 127 * @param formatter the destination formatter, not null 128 * @param flags the flags for formatting, see {@code Formattable} 129 * @param width the width of the output, see {@code Formattable} 130 * @param precision the precision of the output, see {@code Formattable} 131 * @param padChar the pad character to use 132 * @param ellipsis the ellipsis to use when precision dictates truncation, null or 133 * empty causes a hard truncation 134 * @return the {@code formatter} instance, not null 135 */ 136 public static Formatter append(final CharSequence seq, final Formatter formatter, final int flags, final int width, 137 final int precision, final char padChar, final CharSequence ellipsis) { 138 Validate.isTrue(ellipsis == null || precision < 0 || ellipsis.length() <= precision, 139 "Specified ellipsis '%1$s' exceeds precision of %2$s", ellipsis, Integer.valueOf(precision)); 140 final StringBuilder buf = new StringBuilder(seq); 141 if (precision >= 0 && precision < seq.length()) { 142 final CharSequence _ellipsis = ObjectUtils.defaultIfNull(ellipsis, StringUtils.EMPTY); 143 buf.replace(precision - _ellipsis.length(), seq.length(), _ellipsis.toString()); 144 } 145 final boolean leftJustify = (flags & LEFT_JUSTIFY) == LEFT_JUSTIFY; 146 for (int i = buf.length(); i < width; i++) { 147 buf.insert(leftJustify ? i : 0, padChar); 148 } 149 formatter.format(buf.toString()); 150 return formatter; 151 } 152 153}