io.starter.OpenXLS

Class DateConverter

java.lang.Object

io.starter.OpenXLS.DateConverter

public class DateConverter
extends Object

Provides methods for conversion to and from Excel serial date values.

Excel stores dates as the number of days since midnight on January 1, 1900. Times are represented as fractional days. For example, 6:00 AM on February 2, 1900 is represented as 33.25. Excel incorrectly treats 1900 as a leap year, so serial dates after February 28, 1900 are one higher than they otherwise should be and the value 60 is unmapped. It also interprets the value 0 as January 0, 1900.

Excel does not support negative serial date values, so it cannot handle dates prior to 1900. It also does not currently accept date values with a year of 10000 or greater. OpenXLS does not currently support negative date values, but this feature is planned. If you wish to restrict the output to the subset of values supported by Excel, you may enable input validation by calling setValidate(boolean).

Due to the inherent inaccuracy of floating-point types, values from this class can only be guaranteed to equal values generated by Excel to eight decimal places. This provides accuracy to the unit milliseconds, the maximum precision of Java's date classes. Accuracy outside the range supported by Excel is not guaranteed and will degrade as the values get farther from zero.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	DateConverter.DateFormat The set of supported serial date encoding schemes.

Constructor Summary

Constructors

Constructor and Description
DateConverter()

Method Summary

Modifier and Type	Method and Description
static Double	calcDateValue(String dateString) DATEVALUE Returns the serial number of the date represented by date_text.
static Calendar	convertStringToCalendar(String dateStr) Converts a string representation of a date into a valid calendar object date must be in format mm/dd/yy (or yyyy)
static Calendar	getCalendar() Gets a clone of the calendar used for date calculation.
static Calendar	getCalendarFromCell(Cell cell) Gets the Calendar for the given cell.
static Calendar	getCalendarFromCellWithPrecision(Cell cell, int roundingCalendarField) returns a Java Calendar from a CellHandle containing an Excel-formatted Date The Excel date format does not map 100% accurately to Java dates, due to the limitation of the precision of the Excel floating-point value record.
static Calendar	getCalendarFromNumber(double date) Deprecated. Use getCalendarFromNumber( double, DateFormat ) instead.
static Calendar	getCalendarFromNumber(double date, DateConverter.DateFormat format) Parses the the given Excel serial date and returns a Calendar.
static Calendar	getCalendarFromNumber(Object number) Deprecated. Use getCalendarFromNumber(double) instead.
static Date	getDate(String str) attempt to interpret a date string into a date returns null if cannot be converted to date
static Date	getDateFromCell(CellHandle cell) Gets the Date for the given cell.
static Date	getDateFromNumber(double date) Deprecated. Use getCalendarFromNumber( double, DateFormat ) instead.
static Date	getDateFromNumber(Object number) Deprecated. Use getDateFromNumber(double) instead.
static String	getFormattedDateVal(CellHandle cell) Deprecated. The date format handling in this method is wildly incorrect. It is retained only to provide compatibility with legacy OpenXLS XML files.
static Calendar	getNonLocalizedCalendarFromNumber(Object number) Deprecated. Identical to getDateFromNumber(Object).
static Date	getNonLocalizedDateFromNumber(Object number) Deprecated. Identical to getDateFromNumber(Object).
static boolean	getValidate() Returns whether input validation is on.
static double	getXLSDateVal(Calendar cal) Deprecated. Use getXLSDateVal( Calendar, DateFormat ) instead.
static double	getXLSDateVal(Calendar cal, DateConverter.DateFormat format) Converts the value of the given Calendar to an Excel serial date.
static double	getXLSDateVal(Date date) Deprecated. Use getXLSDateVal( Date, DateFormat ) instead.
static double	getXLSDateVal(Date date, DateConverter.DateFormat format) Converts the given Date to an Excel serial date in the default time zone.
static boolean	isDatePattern(String possibleDate) Inspects a string to determine if it is a date.
static boolean	isParseableDateString(String str) returns whether this method will work with your input string
static Date	parseDate(String s, int pat) Deprecated. The date format handling in this method is wildly incorrect. It is retained only to provide compatibility with legacy OpenXLS XML files.
static void	setCalendar(Calendar cal) Sets the calendar used to perform date calculation.
static void	setValidate(boolean validate) Sets whether to perform input validation.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

DateConverter

public DateConverter()

Method Detail

getCalendar

public static Calendar getCalendar()

Gets a clone of the calendar used for date calculation.

setCalendar

public static void setCalendar(Calendar cal)

Sets the calendar used to perform date calculation. This allows you to set the locale and time zone to something other than the system default.

Parameters:

cal - the calendar that should be used for date calculations

getValidate

public static boolean getValidate()

Returns whether input validation is on.

setValidate

public static void setValidate(boolean validate)

Sets whether to perform input validation.

isParseableDateString

public static boolean isParseableDateString(String str)

returns whether this method will work with your input string

getDate

public static Date getDate(String str)

attempt to interpret a date string into a date returns null if cannot be converted to date

getXLSDateVal

public static double getXLSDateVal(Calendar cal)

Deprecated. Use getXLSDateVal( Calendar, DateFormat ) instead.

Converts the value of the given Calendar to an Excel serial date. The date will be returned in the legacy 1900 format.

Parameters:

cal - the Calendar to convert

Returns:

the Excel serial date representing the given calendar's value in the calendar's time zone

getXLSDateVal

public static double getXLSDateVal(Calendar cal,
                                   DateConverter.DateFormat format)

Converts the value of the given Calendar to an Excel serial date.

Parameters:

cal - the Calendar to convert

format - the serial date format to use

Returns:

the Excel serial date representing the given calendar's value in the calendar's time zone

getXLSDateVal

public static double getXLSDateVal(Date date,
                                   DateConverter.DateFormat format)

Converts the given Date to an Excel serial date in the default time zone.

Parameters:

date - the date to be converted

format - the serial date format to use

Returns:

the Excel serial date value corresponding to the given date

getXLSDateVal

public static double getXLSDateVal(Date date)

Deprecated. Use getXLSDateVal( Date, DateFormat ) instead.

Converts the given Date to an Excel serial date in the default time zone. The date will be returned in the legacy 1900 format.

Parameters:

date - the date to be converted

Returns:

the Excel serial date value corresponding to the given date

getCalendarFromNumber

public static Calendar getCalendarFromNumber(double date)

Deprecated. Use getCalendarFromNumber( double, DateFormat ) instead.

Parses the the given Excel serial date and returns a Calendar. The date will be interpreted in the legacy 1900 format.

Parameters:

date - the Excel serial date to be interpreted

Returns:

a Calendar representing the given Excel date interpreted in the default time zone

getCalendarFromNumber

public static Calendar getCalendarFromNumber(double date,
                                             DateConverter.DateFormat format)

Parses the the given Excel serial date and returns a Calendar.

Parameters:

date - the Excel serial date to be interpreted

format - the date format with which to interpret the serial date

Returns:

a Calendar representing the given Excel date interpreted in the default time zone

getDateFromNumber

public static Date getDateFromNumber(double date)

Deprecated. Use getCalendarFromNumber( double, DateFormat ) instead.

Parses the the given Excel serial date and returns a Date. The date will be interpreted in the legacy 1900 format.

Parameters:

date - the Excel serial date to be interpreted

format - the date format with which to interpret the serial date

Returns:

a Calendar representing the given Excel date interpreted in the default time zone

getDateFromNumber

public static Date getDateFromNumber(Object number)

Deprecated. Use getDateFromNumber(double) instead.

Gets the Date for the given Excel serial date.

Parameters:

number - a Number representing the serial date to be interpreted

Returns:

a Date representing the given Excel date interpreted in the default time zone

Throws:

ClassCastException - if the passed object is not a Number

getNonLocalizedDateFromNumber

public static Date getNonLocalizedDateFromNumber(Object number)

Deprecated. Identical to getDateFromNumber(Object).

Gets the Date for the given Excel serial date.

Parameters:

number - a Number representing the serial date to be interpreted

Returns:

a Date representing the given Excel date interpreted in the default time zone

Throws:

ClassCastException - if the passed object is not a Number

getCalendarFromNumber

public static Calendar getCalendarFromNumber(Object number)

Deprecated. Use getCalendarFromNumber(double) instead.

Gets the Calendar for the given Excel serial date.

Parameters:

date - the Excel serial date or datestring to be interpreted

Returns:

a Calendar representing the given Excel date interpreted in the default time zone

Throws:

ClassCastException - if the passed object is not a Number

getNonLocalizedCalendarFromNumber

public static Calendar getNonLocalizedCalendarFromNumber(Object number)

Deprecated. Identical to getDateFromNumber(Object).

Gets the Date for the given Excel serial date.

Parameters:

number - a Number representing the serial date to be interpreted

Returns:

a Date representing the given Excel date interpreted in the default time zone

Throws:

ClassCastException - if the passed object is not a Number

getDateFromCell

public static Date getDateFromCell(CellHandle cell)

Gets the Date for the given cell.

Parameters:

cell - a CellHandle whose value should be interpreted

Returns:

a Date representing the given Excel date interpreted in the default time zone

getCalendarFromCellWithPrecision

public static Calendar getCalendarFromCellWithPrecision(Cell cell,
                                                        int roundingCalendarField)

returns a Java Calendar from a CellHandle containing an Excel-formatted Date The Excel date format does not map 100% accurately to Java dates, due to the limitation of the precision of the Excel floating-point value record. Due to this, OpenXLS dates may be too precise, this method will round the java.util.Date returned to the precision entered. Rounding is handled by the ROUND_HALF_UP method. Pass in a static Calendar precision, options are Calendar.HOUR Calendar.MINUTE Calendar.SECOND Calendar.MILLISECOND

Returns:

Calendar - A GregorianCalendar value of the Cell

getCalendarFromCell

public static Calendar getCalendarFromCell(Cell cell)

Gets the Calendar for the given cell.

Parameters:

cell - a CellHandle whose value should be interpreted

Returns:

a Calendar representing the given Excel date interpreted in the default time zone

isDatePattern

public static boolean isDatePattern(String possibleDate)

Inspects a string to determine if it is a date. Looks for a pattern such as mm/dd/yy, m/d/yy, mm/dd/yyyy etc.

Parameters:

possibleDate - the string to check for date formats

Returns:

whether the given string matches a known date format

convertStringToCalendar

public static Calendar convertStringToCalendar(String dateStr)

Converts a string representation of a date into a valid calendar object date must be in format mm/dd/yy (or yyyy)

Parameters:

dateStr -

Returns:

null if not a valid date

getFormattedDateVal

public static String getFormattedDateVal(CellHandle cell)

Deprecated. The date format handling in this method is wildly incorrect. It is retained only to provide compatibility with legacy OpenXLS XML files.

Returns the value of the cell as a date formatted as a String date representation. The format is determined by inspecting the excel format. Currently supported formats in this method are: mm/dd/yy dd-mmm-yy dd-mmm mmm-yy mm/dd/yy hh:mm If the cell's date forrmat pattern falls outside of this range, the default output will be in the following format mm/dd/yyyy

Returns:

String, the value of a cell formatted as a date

parseDate

public static Date parseDate(String s,
                             int pat)

Deprecated. The date format handling in this method is wildly incorrect. It is retained only to provide compatibility with legacy OpenXLS XML files.

calcDateValue

public static Double calcDateValue(String dateString)

DATEVALUE Returns the serial number of the date represented by date_text. Use DATEVALUE to convert a date represented by text to a serial number. Syntax DATEVALUE(date_text) Date_text is text that represents a date in a Microsoft Excel date format. For example, "1/30/2008" or "30-Jan-2008" are text strings within quotation marks that represent dates. Using the default date system in Excel for Windows, date_text must represent a date from January 1, 1900, to December 31, 9999. Using the default date system in Excel for the Macintosh, date_text must represent a date from January 1, 1904, to December 31, 9999. DATEVALUE returns the #VALUE! error value if date_text is out of this range. If the year portion of date_text is omitted, DATEVALUE uses the current year from your computer's built-in clock. Time information in date_text is ignored. Remarks Excel stores dates as sequential serial numbers so they can be used in calculations. By default, January 1, 1900 is serial number 1, and January 1, 2008 is serial number 39448 because it is 39,448 days after January 1, 1900. Excel for the Macintosh uses a different date system as its default. Most functions automatically convert date values to serial numbers.

Parameters:

String - dateString

Returns: