.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Spreadsheet::WriteExcel::Utility 3"
.TH Spreadsheet::WriteExcel::Utility 3 "2013-11-07" "perl v5.16.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Utility \- Helper functions for Spreadsheet::WriteExcel.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
Functions to help with some common tasks when using Spreadsheet::WriteExcel.
.PP
These functions mainly relate to dealing with rows and columns in A1 notation and to handling dates and times.
.PP
.Vb 1
\&    use Spreadsheet::WriteExcel::Utility;               # Import everything
\&
\&    ($row, $col)    = xl_cell_to_rowcol(\*(AqC2\*(Aq);          # (1, 2)
\&    $str            = xl_rowcol_to_cell(1, 2);          # C2
\&    $str            = xl_inc_col(\*(AqZ1\*(Aq  );               # AA1
\&    $str            = xl_dec_col(\*(AqAA1\*(Aq );               # Z1
\&
\&    $date           = xl_date_list(2002, 1, 1);         # 37257
\&    $date           = xl_parse_date("11 July 1997");    # 35622
\&    $time           = xl_parse_time(\*(Aq3:21:36 PM\*(Aq);      # 0.64
\&    $date           = xl_decode_date_EU("13 May 2002"); # 37389
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module provides a set of functions to help with some common tasks encountered when using the Spreadsheet::WriteExcel module. The two main categories of function are:
.PP
Row and column functions: these are used to deal with Excel's A1 representation of cells. The functions in this category are:
.PP
.Vb 7
\&    xl_rowcol_to_cell
\&    xl_cell_to_rowcol
\&    xl_range_formula
\&    xl_inc_row
\&    xl_dec_row
\&    xl_inc_col
\&    xl_dec_col
.Ve
.PP
Date and Time functions: these are used to convert dates and times to the numeric format used by Excel. The functions in this category are:
.PP
.Vb 7
\&    xl_date_list
\&    xl_date_1904
\&    xl_parse_time
\&    xl_parse_date
\&    xl_parse_date_init
\&    xl_decode_date_EU
\&    xl_decode_date_US
.Ve
.PP
All of these functions are exported by default. However, you can use import lists if you wish to limit the functions that are imported:
.PP
.Vb 4
\&    use Spreadsheet::WriteExcel::Utility;                  # Import everything
\&    use Spreadsheet::WriteExcel::Utility qw(xl_date_list); # xl_date_list only
\&    use Spreadsheet::WriteExcel::Utility qw(:rowcol);      # Row/col functions
\&    use Spreadsheet::WriteExcel::Utility qw(:dates);       # Date functions
.Ve
.SH "ROW AND COLUMN FUNCTIONS"
.IX Header "ROW AND COLUMN FUNCTIONS"
Spreadsheet::WriteExcel supports two forms of notation to designate the position of cells: Row-column notation and A1 notation.
.PP
Row-column notation uses a zero based index for both row and column while A1 notation uses the standard Excel alphanumeric sequence of column letter and 1\-based row. Columns range from A to \s-1IV\s0 i.e. 0 to 255, rows range from 1 to 16384 in Excel 5 and 65536 in Excel 97. For example:
.PP
.Vb 2
\&    (0, 0)      # The top left cell in row\-column notation.
\&    (\*(AqA1\*(Aq)      # The top left cell in A1 notation.
\&
\&    (1999, 29)  # Row\-column notation.
\&    (\*(AqAD2000\*(Aq)  # The same cell in A1 notation.
.Ve
.PP
Row-column notation is useful if you are referring to cells programmatically:
.PP
.Vb 3
\&    for my $i (0 .. 9) {
\&        $worksheet\->write($i, 0, \*(AqHello\*(Aq); # Cells A1 to A10
\&    }
.Ve
.PP
A1 notation is useful for setting up a worksheet manually and for working with formulas:
.PP
.Vb 2
\&    $worksheet\->write(\*(AqH1\*(Aq, 200);
\&    $worksheet\->write(\*(AqH2\*(Aq, \*(Aq=H7+1\*(Aq);
.Ve
.PP
The functions in the following sections can be used for dealing with A1 notation, for example:
.PP
.Vb 2
\&    ($row, $col)    = xl_cell_to_rowcol(\*(AqC2\*(Aq);  # (1, 2)
\&    $str            = xl_rowcol_to_cell(1, 2);  # C2
.Ve
.PP
Cell references in Excel can be either relative or absolute. Absolute references are prefixed by the dollar symbol as shown below:
.PP
.Vb 4
\&    A1      # Column and row are relative
\&    $A1     # Column is absolute and row is relative
\&    A$1     # Column is relative and row is absolute
\&    $A$1    # Column and row are absolute
.Ve
.PP
An absolute reference only has an effect if the cell is copied. Refer to the Excel documentation for further details. All of the following functions support absolute references.
.ie n .SS "xl_rowcol_to_cell($row, $col, $row_absolute, $col_absolute)"
.el .SS "xl_rowcol_to_cell($row, \f(CW$col\fP, \f(CW$row_absolute\fP, \f(CW$col_absolute\fP)"
.IX Subsection "xl_rowcol_to_cell($row, $col, $row_absolute, $col_absolute)"
.Vb 4
\&    Parameters: $row:           Integer
\&                $col:           Integer
\&                $row_absolute:  Boolean (1/0) [optional, default is 0]
\&                $col_absolute:  Boolean (1/0) [optional, default is 0]
\&
\&    Returns:    A string in A1 cell notation
.Ve
.PP
This function converts a zero based row and column cell reference to a A1 style string:
.PP
.Vb 3
\&    $str = xl_rowcol_to_cell(0, 0); # A1
\&    $str = xl_rowcol_to_cell(0, 1); # B1
\&    $str = xl_rowcol_to_cell(1, 0); # A2
.Ve
.PP
The optional parameters \f(CW$row_absolute\fR and \f(CW$col_absolute\fR can be used to indicate if the row or column is absolute:
.PP
.Vb 3
\&    $str = xl_rowcol_to_cell(0, 0, 0, 1); # $A1
\&    $str = xl_rowcol_to_cell(0, 0, 1, 0); # A$1
\&    $str = xl_rowcol_to_cell(0, 0, 1, 1); # $A$1
.Ve
.PP
See \*(L"\s-1ROW AND COLUMN FUNCTIONS\*(R"\s0 for an explanation of absolute cell references.
.SS "xl_cell_to_rowcol($string)"
.IX Subsection "xl_cell_to_rowcol($string)"
.Vb 1
\&    Parameters: $string         String in A1 format
\&
\&    Returns:    List            ($row, $col)
.Ve
.PP
This function converts an Excel cell reference in A1 notation to a zero based row and column. The function will also handle Excel's absolute, \f(CW\*(C`$\*(C'\fR, cell notation.
.PP
.Vb 6
\&    my ($row, $col) = xl_cell_to_rowcol(\*(AqA1\*(Aq);     # (0, 0)
\&    my ($row, $col) = xl_cell_to_rowcol(\*(AqB1\*(Aq);     # (0, 1)
\&    my ($row, $col) = xl_cell_to_rowcol(\*(AqC2\*(Aq);     # (1, 2)
\&    my ($row, $col) = xl_cell_to_rowcol(\*(Aq$C2\*(Aq );   # (1, 2)
\&    my ($row, $col) = xl_cell_to_rowcol(\*(AqC$2\*(Aq );   # (1, 2)
\&    my ($row, $col) = xl_cell_to_rowcol(\*(Aq$C$2\*(Aq);   # (1, 2)
.Ve
.ie n .SS "xl_range_formula($sheetname, $row_1, $row_2, $col_1, $col_2)"
.el .SS "xl_range_formula($sheetname, \f(CW$row_1\fP, \f(CW$row_2\fP, \f(CW$col_1\fP, \f(CW$col_2\fP)"
.IX Subsection "xl_range_formula($sheetname, $row_1, $row_2, $col_1, $col_2)"
.Vb 5
\&    Parameters: $sheetname      String
\&                $row_1:         Integer
\&                $row_2:         Integer
\&                $col_1:         Integer
\&                $col_2:         Integer
\&
\&    Returns:    A worksheet range formula as a string.
.Ve
.PP
This function converts zero based row and column cell references to an A1 style formula string:
.PP
.Vb 3
\&    my $str = xl_range_formula(\*(AqSheet1\*(Aq,   0,  9, 0, 0); # =Sheet1!$A$1:$A$10
\&    my $str = xl_range_formula(\*(AqSheet2\*(Aq,   6, 65, 1, 1); # =Sheet2!$B$7:$B$66
\&    my $str = xl_range_formula(\*(AqNew data\*(Aq, 1,  8, 2, 2); # =\*(AqNew data\*(Aq!$C$2:$C$9
.Ve
.PP
This is useful for setting ranges in Chart objects:
.PP
.Vb 4
\&    $chart\->add_series(
\&        categories    => xl_range_formula(\*(AqSheet1\*(Aq, 1, 9, 0, 0),
\&        values        => xl_range_formula(\*(AqSheet1\*(Aq, 1, 9, 1, 1),
\&    );
\&
\&    # Which is the same as:
\&
\&    $chart\->add_series(
\&        categories    => \*(Aq=Sheet1!$A$2:$A$10\*(Aq,
\&        values        => \*(Aq=Sheet1!$B$2:$B$10\*(Aq,
\&    );
.Ve
.SS "xl_inc_row($string)"
.IX Subsection "xl_inc_row($string)"
.Vb 1
\&    Parameters: $string, a string in A1 format
\&
\&    Returns:    Incremented string in A1 format
.Ve
.PP
This functions takes a cell reference string in A1 notation and increments the row. The function will also handle Excel's absolute, \f(CW\*(C`$\*(C'\fR, cell notation:
.PP
.Vb 4
\&    my $str = xl_inc_row(\*(AqA1\*(Aq  ); # A2
\&    my $str = xl_inc_row(\*(AqB$2\*(Aq ); # B$3
\&    my $str = xl_inc_row(\*(Aq$C3\*(Aq ); # $C4
\&    my $str = xl_inc_row(\*(Aq$D$4\*(Aq); # $D$5
.Ve
.SS "xl_dec_row($string)"
.IX Subsection "xl_dec_row($string)"
.Vb 1
\&    Parameters: $string, a string in A1 format
\&
\&    Returns:    Decremented string in A1 format
.Ve
.PP
This functions takes a cell reference string in A1 notation and decrements the row. The function will also handle Excel's absolute, \f(CW\*(C`$\*(C'\fR, cell notation:
.PP
.Vb 4
\&    my $str = xl_dec_row(\*(AqA2\*(Aq  ); # A1
\&    my $str = xl_dec_row(\*(AqB$3\*(Aq ); # B$2
\&    my $str = xl_dec_row(\*(Aq$C4\*(Aq ); # $C3
\&    my $str = xl_dec_row(\*(Aq$D$5\*(Aq); # $D$4
.Ve
.SS "xl_inc_col($string)"
.IX Subsection "xl_inc_col($string)"
.Vb 1
\&    Parameters: $string, a string in A1 format
\&
\&    Returns:    Incremented string in A1 format
.Ve
.PP
This functions takes a cell reference string in A1 notation and increments the column. The function will also handle Excel's absolute, \f(CW\*(C`$\*(C'\fR, cell notation:
.PP
.Vb 4
\&    my $str = xl_inc_col(\*(AqA1\*(Aq  ); # B1
\&    my $str = xl_inc_col(\*(AqZ1\*(Aq  ); # AA1
\&    my $str = xl_inc_col(\*(Aq$B1\*(Aq ); # $C1
\&    my $str = xl_inc_col(\*(Aq$D$5\*(Aq); # $E$5
.Ve
.SS "xl_dec_col($string)"
.IX Subsection "xl_dec_col($string)"
.Vb 1
\&    Parameters: $string, a string in A1 format
\&
\&    Returns:    Decremented string in A1 format
.Ve
.PP
This functions takes a cell reference string in A1 notation and decrements the column. The function will also handle Excel's absolute, \f(CW\*(C`$\*(C'\fR, cell notation:
.PP
.Vb 4
\&    my $str = xl_dec_col(\*(AqB1\*(Aq  ); # A1
\&    my $str = xl_dec_col(\*(AqAA1\*(Aq ); # Z1
\&    my $str = xl_dec_col(\*(Aq$C1\*(Aq ); # $B1
\&    my $str = xl_dec_col(\*(Aq$E$5\*(Aq); # $D$5
.Ve
.SH "TIME AND DATE FUNCTIONS"
.IX Header "TIME AND DATE FUNCTIONS"
Dates and times in Excel are represented by real numbers, for example \*(L"Jan 1 2001 12:30 \s-1AM\*(R"\s0 is represented by the number 36892.521.
.PP
The integer part of the number stores the number of days since the epoch and the fractional part stores the percentage of the day in seconds.
.PP
The epoch can be either 1900 or 1904. Excel for Windows uses 1900 and Excel for Macintosh uses 1904. The epochs are:
.PP
.Vb 2
\&    1900: 0 January 1900 i.e. 31 December 1899
\&    1904: 1 January 1904
.Ve
.PP
Excel on Windows and the Macintosh will convert automatically between one system and the other. By default Spreadsheet::WriteExcel uses the 1900 format. To use the 1904 epoch you must use the \f(CW\*(C`set_1904()\*(C'\fR workbook method, see the Spreadsheet::WriteExcel documentation.
.PP
There are two things to note about the 1900 date format. The first is that the epoch starts on 0 January 1900. The second is that the year 1900 is erroneously but deliberately treated as a leap year. Therefore you must add an extra day to dates after 28 February 1900. The functions in the following section will deal with these issues automatically. The reason for this anomaly is explained at http://support.microsoft.com/support/kb/articles/Q181/3/70.asp
.PP
Note, a date or time in Excel is like any other number. To display the number as a date you must apply a number format to it: Refer to the \f(CW\*(C`set_num_format()\*(C'\fR method in the Spreadsheet::WriteExcel documentation:
.PP
.Vb 3
\&    $date = xl_date_list(2001, 1, 1, 12, 30);
\&    $format\->set_num_format(\*(Aqmmm d yyyy hh:mm AM/PM\*(Aq);
\&    $worksheet\->write(\*(AqA1\*(Aq, $date , $format); # Jan 1 2001 12:30 AM
.Ve
.PP
To use these functions you must install the \f(CW\*(C`Date::Manip\*(C'\fR and \f(CW\*(C`Date::Calc\*(C'\fR modules. See \s-1REQUIREMENTS\s0 and the individual requirements of each functions.
.PP
See also the DateTime::Format::Excel module,http://search.cpan.org/search?dist=DateTime\-Format\-Excel which is part of the DateTime project and which deals specifically with converting dates and times to and from Excel's format.
.ie n .SS "xl_date_list($years, $months, $days, $hours, $minutes, $seconds)"
.el .SS "xl_date_list($years, \f(CW$months\fP, \f(CW$days\fP, \f(CW$hours\fP, \f(CW$minutes\fP, \f(CW$seconds\fP)"
.IX Subsection "xl_date_list($years, $months, $days, $hours, $minutes, $seconds)"
.Vb 6
\&    Parameters: $years:         Integer
\&                $months:        Integer [optional, default is 1]
\&                $days:          Integer [optional, default is 1]
\&                $hours:         Integer [optional, default is 0]
\&                $minutes:       Integer [optional, default is 0]
\&                $seconds:       Float   [optional, default is 0]
\&
\&    Returns:    A number that represents an Excel date
\&                or undef for an invalid date.
\&
\&    Requires:   Date::Calc
.Ve
.PP
This function converts an array of data into a number that represents an Excel date. All of the parameters are optional except for \f(CW$years\fR.
.PP
.Vb 4
\&    $date1 = xl_date_list(2002, 1, 2);              # 2 Jan 2002
\&    $date2 = xl_date_list(2002, 1, 2, 12);          # 2 Jan 2002 12:00 pm
\&    $date3 = xl_date_list(2002, 1, 2, 12, 30);      # 2 Jan 2002 12:30 pm
\&    $date4 = xl_date_list(2002, 1, 2, 12, 30, 45);  # 2 Jan 2002 12:30:45 pm
.Ve
.PP
This function can be used in conjunction with functions that parse date and time strings. In fact it is used in most of the following functions.
.SS "xl_parse_time($string)"
.IX Subsection "xl_parse_time($string)"
.Vb 1
\&    Parameters: $string, a textual representation of a time
\&
\&    Returns:    A number that represents an Excel time
\&                or undef for an invalid time.
.Ve
.PP
This function converts a time string into a number that represents an Excel time. The following time formats are valid:
.PP
.Vb 4
\&    hh:mm       [AM|PM]
\&    hh:mm       [AM|PM]
\&    hh:mm:ss    [AM|PM]
\&    hh:mm:ss.ss [AM|PM]
.Ve
.PP
The meridian, \s-1AM\s0 or \s-1PM,\s0 is optional and case insensitive. A 24 hour time is assumed if the meridian is omitted
.PP
.Vb 4
\&    $time1 = xl_parse_time(\*(Aq12:18\*(Aq);
\&    $time2 = xl_parse_time(\*(Aq12:18:14\*(Aq);
\&    $time3 = xl_parse_time(\*(Aq12:18:14 AM\*(Aq);
\&    $time4 = xl_parse_time(\*(Aq1:18:14 AM\*(Aq);
.Ve
.PP
Time in Excel is expressed as a fraction of the day in seconds. Therefore you can calculate an Excel time as follows:
.PP
.Vb 1
\&    $time = ($hours*3600 +$minutes*60 +$seconds)/(24*60*60);
.Ve
.SS "xl_parse_date($string)"
.IX Subsection "xl_parse_date($string)"
.Vb 1
\&    Parameters: $string, a textual representation of a date and time
\&
\&    Returns:    A number that represents an Excel date
\&                or undef for an invalid date.
\&
\&    Requires:   Date::Manip and Date::Calc
.Ve
.PP
This function converts a date and time string into a number that represents an Excel date.
.PP
The parsing is performed using the \f(CW\*(C`ParseDate()\*(C'\fR function of the Date::Manip module. Refer to the Date::Manip documentation for further information about the date and time formats that can be parsed. In order to use this function you will probably have to initialise some Date::Manip variables via the \f(CW\*(C`xl_parse_date_init()\*(C'\fR function, see below.
.PP
.Vb 1
\&    xl_parse_date_init("TZ=GMT","DateFormat=non\-US");
\&
\&    $date1 = xl_parse_date("11/7/97");
\&    $date2 = xl_parse_date("Friday 11 July 1997");
\&    $date3 = xl_parse_date("10:30 AM Friday 11 July 1997");
\&    $date4 = xl_parse_date("Today");
\&    $date5 = xl_parse_date("Yesterday");
.Ve
.PP
Note, if you parse a string that represents a time but not a date this function will add the current date. If you want the time without the date you can do something like the following:
.PP
.Vb 2
\&    $time  = xl_parse_date("10:30 AM");
\&    $time \-= int($time);
.Ve
.ie n .SS "xl_parse_date_init(""variable=value"", ...)"
.el .SS "xl_parse_date_init(``variable=value'', ...)"
.IX Subsection "xl_parse_date_init(variable=value, ...)"
.Vb 1
\&    Parameters: A list of Date::Manip variable strings
\&
\&    Returns:    A list of all the Date::Manip strings
\&
\&    Requires:   Date::Manip
.Ve
.PP
This function is used to initialise variables required by the Date::Manip module. You should call this function before calling \f(CW\*(C`xl_parse_date()\*(C'\fR. It need only be called once.
.PP
This function is a thin wrapper for the \f(CW\*(C`Date::Manip::Date_Init()\*(C'\fR function. You can use \f(CW\*(C`Date_Init()\*(C'\fR  directly if you wish. Refer to the Date::Manip documentation for further information.
.PP
.Vb 2
\&    xl_parse_date_init("TZ=MST","DateFormat=US");
\&    $date1 = xl_parse_date("11/7/97");  # November 7th 1997
\&
\&    xl_parse_date_init("TZ=GMT","DateFormat=non\-US");
\&    $date1 = xl_parse_date("11/7/97");  # July 11th 1997
.Ve
.SS "xl_decode_date_EU($string)"
.IX Subsection "xl_decode_date_EU($string)"
.Vb 1
\&    Parameters: $string, a textual representation of a date and time
\&
\&    Returns:    A number that represents an Excel date
\&                or undef for an invalid date.
\&
\&    Requires:   Date::Calc
.Ve
.PP
This function converts a date and time string into a number that represents an Excel date.
.PP
The date parsing is performed using the \f(CW\*(C`Decode_Date_EU()\*(C'\fR function of the Date::Calc module. Refer to the Date::Calc for further information about the date formats that can be parsed. Also note the following from the Date::Calc documentation:
.PP
\&\*(L"If the year is given as one or two digits only (i.e., if the year is less than 100), it is mapped to the window 1970 \-2069 as follows\*(R":
.PP
.Vb 2
\&     0 E<lt>= $year E<lt>  70  ==>  $year += 2000;
\&    70 E<lt>= $year E<lt> 100  ==>  $year += 1900;
.Ve
.PP
The time portion of the string is parsed using the \f(CW\*(C`xl_parse_time()\*(C'\fR function described above.
.PP
Note: the \s-1EU\s0 in the function name means that a European date format is assumed if it is not clear from the string. See the first example below.
.PP
.Vb 3
\&    $date1 = xl_decode_date_EU("11/7/97"); #11 July 1997
\&    $date2 = xl_decode_date_EU("Sat 12 Sept 1998");
\&    $date3 = xl_decode_date_EU("4:30 AM Sat 12 Sept 1998");
.Ve
.SS "xl_decode_date_US($string)"
.IX Subsection "xl_decode_date_US($string)"
.Vb 1
\&    Parameters: $string, a textual representation of a date and time
\&
\&    Returns:    A number that represents an Excel date
\&                or undef for an invalid date.
\&
\&    Requires:   Date::Calc
.Ve
.PP
This function converts a date and time string into a number that represents an Excel date.
.PP
The date parsing is performed using the \f(CW\*(C`Decode_Date_US()\*(C'\fR function of the Date::Calc module. Refer to the Date::Calc for further information about the date formats that can be parsed. Also note the following from the Date::Calc documentation:
.PP
\&\*(L"If the year is given as one or two digits only (i.e., if the year is less than 100), it is mapped to the window 1970 \-2069 as follows\*(R":
.PP
.Vb 2
\&     0 <= $year <  70  ==>  $year += 2000;
\&    70 <= $year < 100  ==>  $year += 1900;
.Ve
.PP
The time portion of the string is parsed using the \f(CW\*(C`xl_parse_time()\*(C'\fR function described above.
.PP
Note: the \s-1US\s0 in the function name means that an American date format is assumed if it is not clear from the string. See the first example below.
.PP
.Vb 3
\&    $date1 = xl_decode_date_US("11/7/97"); # 7 November 1997
\&    $date2 = xl_decode_date_US("12 Sept Saturday 1998");
\&    $date3 = xl_decode_date_US("4:30 AM 12 Sept Sat 1998");
.Ve
.SS "xl_date_1904($date)"
.IX Subsection "xl_date_1904($date)"
.Vb 1
\&    Parameters: $date, an Excel date with a 1900 epoch
\&
\&    Returns:    an Excel date with a 1904 epoch or zero if
\&                the $date is before 1904
.Ve
.PP
This function converts an Excel date based on the 1900 epoch into a date based on the 1904 epoch.
.PP
.Vb 2
\&    $date1 = xl_date_list(2002, 1, 13); # 13 Jan 2002, 1900 epoch
\&    $date2 = xl_date_1904($date1);      # 13 Jan 2002, 1904 epoch
.Ve
.PP
See also the \f(CW\*(C`set_1904()\*(C'\fR workbook method in the Spreadsheet::WriteExcel documentation.
.SH "REQUIREMENTS"
.IX Header "REQUIREMENTS"
The date and time functions require functions from the \f(CW\*(C`Date::Manip\*(C'\fR and \f(CW\*(C`Date::Calc\*(C'\fR modules. The required functions are \*(L"autoused\*(R" from these modules so that you do not have to install them unless you wish to use the date and time routines. Therefore it is possible to use the row and column functions without having \f(CW\*(C`Date::Manip\*(C'\fR and \f(CW\*(C`Date::Calc\*(C'\fR installed.
.PP
For more information about \*(L"autousing\*(R" refer to the documentation on the \f(CW\*(C`autouse\*(C'\fR pragma.
.SH "BUGS"
.IX Header "BUGS"
When using the autoused functions from \f(CW\*(C`Date::Manip\*(C'\fR and \f(CW\*(C`Date::Calc\*(C'\fR on Perl 5.6.0 with \f(CW\*(C`\-w\*(C'\fR you will get a warning like this:
.PP
.Vb 1
\&    "Subroutine xxx redefined ..."
.Ve
.PP
The current workaround for this is to put \f(CW\*(C`use warnings;\*(C'\fR near the beginning of your program.
.SH "AUTHOR"
.IX Header "AUTHOR"
John McNamara jmcnamara@cpan.org
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright MM-MMX, John McNamara.
.PP
All Rights Reserved. This module is free software. It may be used, redistributed and/or modified under the same terms as Perl itself.