org.apache.poi.ss.usermodel.DataFormatter Maven / Gradle / Ivy
/* ====================================================================
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
==================================================================== */
package org.apache.poi.ss.usermodel;
import java.util.regex.Pattern;
import java.util.regex.Matcher;
import java.util.*;
import java.lang.reflect.InvocationTargetException;
import java.lang.reflect.Method;
import java.math.RoundingMode;
import java.text.*;
/**
* DataFormatter contains methods for formatting the value stored in an
* Cell. This can be useful for reports and GUI presentations when you
* need to display data exactly as it appears in Excel. Supported formats
* include currency, SSN, percentages, decimals, dates, phone numbers, zip
* codes, etc.
*
* Internally, formats will be implemented using subclasses of {@link Format}
* such as {@link DecimalFormat} and {@link SimpleDateFormat}. Therefore the
* formats used by this class must obey the same pattern rules as these Format
* subclasses. This means that only legal number pattern characters ("0", "#",
* ".", "," etc.) may appear in number formats. Other characters can be
* inserted before or after the number pattern to form a
* prefix or suffix.
*
*
* For example the Excel pattern "$#,##0.00 "USD"_);($#,##0.00 "USD")"
* will be correctly formatted as "$1,000.00 USD" or "($1,000.00 USD)".
* However the pattern "00-00-00" is incorrectly formatted by
* DecimalFormat as "000000--". For Excel formats that are not compatible with
* DecimalFormat, you can provide your own custom {@link Format} implementation
* via DataFormatter.addFormat(String,Format). The following
* custom formats are already provided by this class:
*
*
*
- SSN "000-00-0000"
* - Phone Number "(###) ###-####"
* - Zip plus 4 "00000-0000"
*
*
* If the Excel format pattern cannot be parsed successfully, then a default
* format will be used. The default number format will mimic the Excel General
* format: "#" for whole numbers and "#.##########" for decimal numbers. You
* can override the default format pattern with
* Returns the formatted value of a cell as a String regardless
* of the cell type. If the Excel format pattern cannot be parsed then the
* cell value will be formatted using a default format.
* When passed a null or blank cell, this method will return an empty
* String (""). Formulas in formula type cells will not be evaluated.
*
* Returns the formatted value of a cell as a String regardless
* of the cell type. If the Excel format pattern cannot be parsed then the
* cell value will be formatted using a default format.
* When passed a null or blank cell, this method will return an empty
* String (""). Formula cells will be evaluated using the given
* {@link FormulaEvaluator} if the evaluator is non-null. If the
* evaluator is null, then the formula String will be returned. The caller
* is responsible for setting the currentRow on the evaluator
*
* Sets a default number format to be used when the Excel format cannot be
* parsed successfully. Note: This is a fall back for when an error
* occurs while parsing an Excel number format pattern. This will not
* affect cells with the General format.
*
* The value that will be passed to the Format's format method (specified
* by
* The value that will be passed to the Format's format method (specified
* by
* DataFormatter.setDefaultNumberFormat(Format). Note: the
* default format will only be used when a Format cannot be created from the
* cell's data format string.
*
* @author James May (james dot may at fmr dot com)
*
*/
public class DataFormatter {
/** Pattern to find a number format: "0" or "#" */
private static final Pattern numPattern = Pattern.compile("[0#]+");
/** Pattern to find days of week as text "ddd...." */
private static final Pattern daysAsText = Pattern.compile("([d]{3,})", Pattern.CASE_INSENSITIVE);
/** Pattern to find "AM/PM" marker */
private static final Pattern amPmPattern = Pattern.compile("((A|P)[M/P]*)", Pattern.CASE_INSENSITIVE);
/** A regex to find patterns like [$$-1009] and [$?-452]. */
private static final Pattern specialPatternGroup = Pattern.compile("(\\[\\$[^-\\]]*-[0-9A-Z]+\\])");
/**
* A regex to match the colour formattings rules.
* Allowed colours are: Black, Blue, Cyan, Green,
* Magenta, Red, White, Yellow, "Color n" (1<=n<=56)
*/
private static final Pattern colorPattern =
Pattern.compile("(\\[BLACK\\])|(\\[BLUE\\])|(\\[CYAN\\])|(\\[GREEN\\])|" +
"(\\[MAGENTA\\])|(\\[RED\\])|(\\[WHITE\\])|(\\[YELLOW\\])|" +
"(\\[COLOR\\s*\\d\\])|(\\[COLOR\\s*[0-5]\\d\\])", Pattern.CASE_INSENSITIVE);
/**
* The decimal symbols of the locale used for formatting values.
*/
private final DecimalFormatSymbols decimalSymbols;
/**
* The date symbols of the locale used for formatting values.
*/
private final DateFormatSymbols dateSymbols;
/** General format for whole numbers. */
private final Format generalWholeNumFormat;
/** General format for decimal numbers. */
private final Format generalDecimalNumFormat;
/** A default format to use when a number pattern cannot be parsed. */
private Format defaultNumFormat;
/**
* A map to cache formats.
* Mapnull if the any of the
* following is true:
*
*
*
* @param cell The cell to retrieve a Format for
* @return A Format for the format String
*/
private Format getFormat(Cell cell) {
if ( cell.getCellStyle() == null) {
return null;
}
int formatIndex = cell.getCellStyle().getDataFormat();
String formatStr = cell.getCellStyle().getDataFormatString();
if(formatStr == null || formatStr.trim().length() == 0) {
return null;
}
return getFormat(cell.getNumericCellValue(), formatIndex, formatStr);
}
private Format getFormat(double cellValue, int formatIndex, String formatStr) {
// Excel supports positive/negative/zero, but java
// doesn't, so we need to do it specially
if(formatStr.indexOf(';') != formatStr.lastIndexOf(';')) {
int lastAt = formatStr.lastIndexOf(';');
String zeroFormat = formatStr.substring(lastAt+1);
String normalFormat = formatStr.substring(0,lastAt);
if(cellValue == 0.0) {
formatStr = zeroFormat;
} else {
formatStr = normalFormat;
}
}
// See if we already have it cached
Format format = formats.get(formatStr);
if (format != null) {
return format;
}
if ("General".equals(formatStr) || "@".equals(formatStr)) {
if (DataFormatter.isWholeNumber(cellValue)) {
return generalWholeNumFormat;
}
return generalDecimalNumFormat;
}
format = createFormat(cellValue, formatIndex, formatStr);
formats.put(formatStr, format);
return format;
}
/**
* Create and return a Format based on the format string from a cell's
* style. If the pattern cannot be parsed, return a default pattern.
*
* @param cell The Excel cell
* @return A Format representing the excel format. May return null.
*/
public Format createFormat(Cell cell) {
int formatIndex = cell.getCellStyle().getDataFormat();
String formatStr = cell.getCellStyle().getDataFormatString();
return createFormat(cell.getNumericCellValue(), formatIndex, formatStr);
}
private Format createFormat(double cellValue, int formatIndex, String sFormat) {
String formatStr = sFormat;
// Remove colour formatting if present
Matcher colourM = colorPattern.matcher(formatStr);
while(colourM.find()) {
String colour = colourM.group();
// Paranoid replacement...
int at = formatStr.indexOf(colour);
if(at == -1) break;
String nFormatStr = formatStr.substring(0,at) +
formatStr.substring(at+colour.length());
if(nFormatStr.equals(formatStr)) break;
// Try again in case there's multiple
formatStr = nFormatStr;
colourM = colorPattern.matcher(formatStr);
}
// try to extract special characters like currency
Matcher m = specialPatternGroup.matcher(formatStr);
while(m.find()) {
String match = m.group();
String symbol = match.substring(match.indexOf('$') + 1, match.indexOf('-'));
if (symbol.indexOf('$') > -1) {
StringBuffer sb = new StringBuffer();
sb.append(symbol.substring(0, symbol.indexOf('$')));
sb.append('\\');
sb.append(symbol.substring(symbol.indexOf('$'), symbol.length()));
symbol = sb.toString();
}
formatStr = m.replaceAll(symbol);
m = specialPatternGroup.matcher(formatStr);
}
if(formatStr == null || formatStr.trim().length() == 0) {
return getDefaultFormat(cellValue);
}
if(DateUtil.isADateFormat(formatIndex,formatStr) &&
DateUtil.isValidExcelDate(cellValue)) {
return createDateFormat(formatStr, cellValue);
}
if (numPattern.matcher(formatStr).find()) {
return createNumberFormat(formatStr, cellValue);
}
// TODO - when does this occur?
return null;
}
private Format createDateFormat(String pFormatStr, double cellValue) {
String formatStr = pFormatStr;
formatStr = formatStr.replaceAll("\\\\-","-");
formatStr = formatStr.replaceAll("\\\\,",",");
formatStr = formatStr.replaceAll("\\\\ "," ");
formatStr = formatStr.replaceAll("\\\\/","/"); // weird: m\\/d\\/yyyy
formatStr = formatStr.replaceAll(";@", "");
formatStr = formatStr.replaceAll("\"/\"", "/"); // "/" is escaped for no reason in: mm"/"dd"/"yyyy
boolean hasAmPm = false;
Matcher amPmMatcher = amPmPattern.matcher(formatStr);
while (amPmMatcher.find()) {
formatStr = amPmMatcher.replaceAll("@");
hasAmPm = true;
amPmMatcher = amPmPattern.matcher(formatStr);
}
formatStr = formatStr.replaceAll("@", "a");
Matcher dateMatcher = daysAsText.matcher(formatStr);
if (dateMatcher.find()) {
String match = dateMatcher.group(0);
formatStr = dateMatcher.replaceAll(match.toUpperCase().replaceAll("D", "E"));
}
// Convert excel date format to SimpleDateFormat.
// Excel uses lower and upper case 'm' for both minutes and months.
// From Excel help:
/*
The "m" or "mm" code must appear immediately after the "h" or"hh"
code or immediately before the "ss" code; otherwise, Microsoft
Excel displays the month instead of minutes."
*/
StringBuffer sb = new StringBuffer();
char[] chars = formatStr.toCharArray();
boolean mIsMonth = true;
Listtrue if d is a whole number
*/
private static boolean isWholeNumber(double d) {
return d == Math.floor(d);
}
/**
* Returns a default format for a cell.
* @param cell The cell
* @return a default format
*/
public Format getDefaultFormat(Cell cell) {
return getDefaultFormat(cell.getNumericCellValue());
}
private Format getDefaultFormat(double cellValue) {
// for numeric cells try user supplied default
if (defaultNumFormat != null) {
return defaultNumFormat;
// otherwise use general format
}
if (isWholeNumber(cellValue)){
return generalWholeNumFormat;
}
return generalDecimalNumFormat;
}
/**
* Performs Excel-style date formatting, using the
* supplied Date and format
*/
private String performDateFormatting(Date d, Format dateFormat) {
if(dateFormat != null) {
return dateFormat.format(d);
}
return d.toString();
}
/**
* Returns the formatted value of an Excel date as a String based
* on the cell's DataFormat. i.e. "Thursday, January 02, 2003"
* , "01/02/2003" , "02-Jan" , etc.
*
* @param cell The cell
* @return a formatted date string
*/
private String getFormattedDateString(Cell cell) {
Format dateFormat = getFormat(cell);
if(dateFormat instanceof ExcelStyleDateFormatter) {
// Hint about the raw excel value
((ExcelStyleDateFormatter)dateFormat).setDateToBeFormatted(
cell.getNumericCellValue()
);
}
Date d = cell.getDateCellValue();
return performDateFormatting(d, dateFormat);
}
/**
* Returns the formatted value of an Excel number as a String
* based on the cell's DataFormat. Supported formats include
* currency, percents, decimals, phone number, SSN, etc.:
* "61.54%", "$100.00", "(800) 555-1234".
*
* @param cell The cell
* @return a formatted number string
*/
private String getFormattedNumberString(Cell cell) {
Format numberFormat = getFormat(cell);
double d = cell.getNumericCellValue();
if (numberFormat == null) {
return String.valueOf(d);
}
return numberFormat.format(new Double(d));
}
/**
* Formats the given raw cell value, based on the supplied
* format index and string, according to excel style rules.
* @see #formatCellValue(Cell)
*/
public String formatRawCellContents(double value, int formatIndex, String formatString) {
return formatRawCellContents(value, formatIndex, formatString, false);
}
/**
* Formats the given raw cell value, based on the supplied
* format index and string, according to excel style rules.
* @see #formatCellValue(Cell)
*/
public String formatRawCellContents(double value, int formatIndex, String formatString, boolean use1904Windowing) {
// Is it a date?
if(DateUtil.isADateFormat(formatIndex,formatString) &&
DateUtil.isValidExcelDate(value)) {
Format dateFormat = getFormat(value, formatIndex, formatString);
if(dateFormat instanceof ExcelStyleDateFormatter) {
// Hint about the raw excel value
((ExcelStyleDateFormatter)dateFormat).setDateToBeFormatted(value);
}
Date d = DateUtil.getJavaDate(value, use1904Windowing);
return performDateFormatting(d, dateFormat);
}
// else Number
Format numberFormat = getFormat(value, formatIndex, formatString);
if (numberFormat == null) {
return String.valueOf(value);
}
return numberFormat.format(new Double(value));
}
/**
* java.text.Format#format) will be a double value from a
* numeric cell. Therefore the code in the format method should expect a
* Number value.
* java.text.Format#format) will be a double value from a
* numeric cell. Therefore the code in the format method should expect a
* Number value.
* true
*/
/* package */ static DecimalFormat createIntegerOnlyFormat(String fmt) {
DecimalFormat result = new DecimalFormat(fmt);
result.setParseIntegerOnly(true);
return result;
}
/**
* Enables excel style rounding mode (round half up)
* on the Decimal Format if possible.
* This will work for Java 1.6, but isn't possible
* on Java 1.5.
*/
public static void setExcelStyleRoundingMode(DecimalFormat format) {
try {
Method srm = format.getClass().getMethod("setRoundingMode", RoundingMode.class);
srm.invoke(format, RoundingMode.HALF_UP);
} catch(NoSuchMethodException e) {
// Java 1.5
} catch(IllegalAccessException iae) {
// Shouldn't happen
throw new RuntimeException("Unable to set rounding mode", iae);
} catch(InvocationTargetException ite) {
// Shouldn't happen
throw new RuntimeException("Unable to set rounding mode", ite);
} catch(SecurityException se) {
// Not much we can do here
}
}
/**
* Format class for Excel's SSN format. This class mimics Excel's built-in
* SSN formatting.
*
* @author James May
*/
@SuppressWarnings("serial")
private static final class SSNFormat extends Format {
public static final Format instance = new SSNFormat();
private static final DecimalFormat df = createIntegerOnlyFormat("000000000");
private SSNFormat() {
// enforce singleton
}
/** Format a number as an SSN */
public static String format(Number num) {
String result = df.format(num);
StringBuffer sb = new StringBuffer();
sb.append(result.substring(0, 3)).append('-');
sb.append(result.substring(3, 5)).append('-');
sb.append(result.substring(5, 9));
return sb.toString();
}
public StringBuffer format(Object obj, StringBuffer toAppendTo, FieldPosition pos) {
return toAppendTo.append(format((Number)obj));
}
public Object parseObject(String source, ParsePosition pos) {
return df.parseObject(source, pos);
}
}
/**
* Format class for Excel Zip + 4 format. This class mimics Excel's
* built-in formatting for Zip + 4.
* @author James May
*/
@SuppressWarnings("serial")
private static final class ZipPlusFourFormat extends Format {
public static final Format instance = new ZipPlusFourFormat();
private static final DecimalFormat df = createIntegerOnlyFormat("000000000");
private ZipPlusFourFormat() {
// enforce singleton
}
/** Format a number as Zip + 4 */
public static String format(Number num) {
String result = df.format(num);
StringBuffer sb = new StringBuffer();
sb.append(result.substring(0, 5)).append('-');
sb.append(result.substring(5, 9));
return sb.toString();
}
public StringBuffer format(Object obj, StringBuffer toAppendTo, FieldPosition pos) {
return toAppendTo.append(format((Number)obj));
}
public Object parseObject(String source, ParsePosition pos) {
return df.parseObject(source, pos);
}
}
/**
* Format class for Excel phone number format. This class mimics Excel's
* built-in phone number formatting.
* @author James May
*/
@SuppressWarnings("serial")
private static final class PhoneFormat extends Format {
public static final Format instance = new PhoneFormat();
private static final DecimalFormat df = createIntegerOnlyFormat("##########");
private PhoneFormat() {
// enforce singleton
}
/** Format a number as a phone number */
public static String format(Number num) {
String result = df.format(num);
StringBuffer sb = new StringBuffer();
String seg1, seg2, seg3;
int len = result.length();
if (len <= 4) {
return result;
}
seg3 = result.substring(len - 4, len);
seg2 = result.substring(Math.max(0, len - 7), len - 4);
seg1 = result.substring(Math.max(0, len - 10), Math.max(0, len - 7));
if(seg1 != null && seg1.trim().length() > 0) {
sb.append('(').append(seg1).append(") ");
}
if(seg2 != null && seg2.trim().length() > 0) {
sb.append(seg2).append('-');
}
sb.append(seg3);
return sb.toString();
}
public StringBuffer format(Object obj, StringBuffer toAppendTo, FieldPosition pos) {
return toAppendTo.append(format((Number)obj));
}
public Object parseObject(String source, ParsePosition pos) {
return df.parseObject(source, pos);
}
}
}