.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.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.  | will give a
.\" real vertical bar.  \*(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-|\(bv\*(Tr
.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" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "DateTime::Format::Excel 3"
.TH DateTime::Format::Excel 3 "2008-01-07" "perl v5.8.8" "User Contributed Perl Documentation"
.SH "NAME"
DateTime::Format::Excel \- Convert between DateTime and Excel dates.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    use DateTime::Format::Excel;
.Ve
.PP
.Vb 1
\&    # From Excel via class method:
.Ve
.PP
.Vb 2
\&    my $datetime = DateTime::Format::Excel->parse_datetime( 37680 );
\&    print $datetime->ymd('.'); # '2003.02.28'
.Ve
.PP
.Vb 1
\&    #  or via an object
.Ve
.PP
.Vb 2
\&    my $excel = DateTime::Format::Excel->new();
\&    print $excel->parse_datetime( 25569 )->ymd; # '1970-01-01'
.Ve
.PP
.Vb 1
\&    # Back to Excel number:
.Ve
.PP
.Vb 4
\&    use DateTime;
\&    my $dt = DateTime->new( year => 1979, month => 7, day => 16 );
\&    my $daynum = DateTime::Format::Excel->format_datetime( $dt );
\&    print $daynum; # 29052
.Ve
.PP
.Vb 3
\&    # or via an object
\&    my $other_daynum = $excel->format_datetime( $dt );
\&    print $other_daynum; # 29052
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Excel uses a different system for its dates than most Unix programs.
This module allows you to convert between a few of the Excel raw formats
and \f(CW\*(C`DateTime\*(C'\fR objects, which can then be further converted via any
of the other \f(CW\*(C`DateTime::Format::*\*(C'\fR modules, or just with \f(CW\*(C`DateTime\*(C'\fR's
methods.
.PP
If you happen to be dealing with dates between 1\ Jan\ 1900 and
1\ Mar\ 1900 please read the notes on epochs.
.PP
If you're wanting to handle actual spreadsheet files, you may find
Spreadsheet::WriteExcel and Spreadsheet::ParseExcel of use.
.SH "CONSTRUCTORS"
.IX Header "CONSTRUCTORS"
.Sh "new"
.IX Subsection "new"
Creates a new \f(CW\*(C`DateTime::Format::Excel\*(C'\fR instance. This is generally
not required for simple operations. If you wish to use a different
epoch, however, then you'll need to create an object.
.PP
.Vb 2
\&   my $excel = DateTime::Format::Excel->new()
\&   my $copy = $excel->new();
.Ve
.PP
It takes no parameters. If called on an existing object then it
clones the object.
.Sh "clone"
.IX Subsection "clone"
This method is provided For those who prefer to explicitly clone via a
method called \f(CW\*(C`clone()\*(C'\fR. If called as a class method it will die.
.PP
.Vb 1
\&   my $clone = $original->clone();
.Ve
.SH "CLASS/OBJECT METHODS"
.IX Header "CLASS/OBJECT METHODS"
These methods work as both class and object methods.
.Sh "parse_datetime"
.IX Subsection "parse_datetime"
Given an Excel day number, return a \f(CW\*(C`DateTime\*(C'\fR object representing that
date and time.
.PP
.Vb 3
\&    # As a class method
\&    my $datetime = DateTime::format::Excel->parse_datetime( 37680 );
\&    print $datetime->ymd('.'); # '2003.02.28'
.Ve
.PP
.Vb 4
\&    # Or via an object
\&    my $excel = DateTime::Format::Excel->new();
\&    my $viaobj $excel->parse_datetime( 25569 );
\&    print $viaobj->ymd; # '1970-01-01'
.Ve
.Sh "format_datetime"
.IX Subsection "format_datetime"
Given a \f(CW\*(C`DateTime\*(C'\fR object, return the Excel daynum time.
.PP
.Vb 4
\&    use DateTime;
\&    my $dt = DateTime->new( year => 1979, month => 7, day => 16 );
\&    my $daynum = DateTime::Format::Excel->format_datetime( $dt );
\&    print $daynum; # 29052
.Ve
.PP
.Vb 5
\&    # or via an object
\&    my $excel = DateTime::Format::Excel->new();
\&    $excel->epoch_mac(); # Let's imagine we want the Mac number
\&    my $mac_daynum = $excel->format_datetime( $dt );
\&    print $mac_daynum; # 27590
.Ve
.SH "OBJECT METHODS"
.IX Header "OBJECT METHODS"
.Sh "epoch"
.IX Subsection "epoch"
In scalar context, returns a string identifying the current epoch.
.PP
.Vb 1
\&   my $epoch = $excel->epoch();
.Ve
.PP
Currently either `mac' or `win' with the default being `win'.
.PP
In list context, returns appropriate parameters with which to
create a \f(CW\*(C`DateTime\*(C'\fR object representing the start of the epoch.
.PP
.Vb 1
\&   my $base = DateTime->new( $excel->epoch );
.Ve
.Sh "epoch_mac"
.IX Subsection "epoch_mac"
Set the object to use a Macintosh epoch.
.PP
.Vb 1
\&   $excel->epoch_mac(); # epoch is now  1 Jan 1904
.Ve
.PP
Thus, 1 maps to \f(CW\*(C`2 Jan 1904\*(C'\fR.
.Sh "epoch_win"
.IX Subsection "epoch_win"
Set the object to use a Windows Excel epoch.
.PP
.Vb 1
\&   $excel->epoch_win(); # epoch is now 30 Dec 1899
.Ve
.PP
Thus, 2 maps to \f(CW\*(C`1 Jan 1900\*(C'\fR.
.SH "EPOCHS"
.IX Header "EPOCHS"
Excel uses ``number of days since 31\ Dec\ 1899''. Naturally, Microsoft
messed this up because they happened to believe that 1900 was a leap
year. In this module, we assume what Psion assumed for their Abacus /
Sheet program: 1\ Jan\ 1900 maps to 2 rather than 1. Thus, 61 maps to
1\ Mar\ 1900 in both Excel and this module (and Abacus).
.PP
\&\fIExcel for Macintosh\fR has a little option hidden away in its
calculations preferences. It can use either the Windows epoch, or it can
use the Macintosh epoch, which means that the day number is calculated
as ``number of days since \ 1\ Jan\ 1904''. This module supports both
notations.
.PP
\&\fBNote\fR: the results of this module have only been compared with
\&\fIMicrosoft Excel for Macintosh 98\fR and \fIAbacus\fR on the
\&\fIAcorn Pocket Book\fR. Where they have differed, I've opted for \fIAbacus\fR's
result rather than \fIExcel\fR's.
.SH "THANKS"
.IX Header "THANKS"
Dave Rolsky (\s-1DROLSKY\s0) for kickstarting the DateTime project.
.SH "SUPPORT"
.IX Header "SUPPORT"
Support for this module is provided via the datetime@perl.org email
list. See http://lists.perl.org/ for more details.
.PP
Alternatively, log them via the \s-1CPAN\s0 \s-1RT\s0 system via the web or email:
.PP
.Vb 2
\&    http://rt.cpan.org/NoAuth/ReportBug.html?Queue=DateTime%3A%3AFormat%3A%3AExcel
\&    bug-datetime-format-excel@rt.cpan.org
.Ve
.PP
This makes it much easier for me to track things and thus means
your problem is less likely to be neglected.
.SH "LICENCE AND COPYRIGHT"
.IX Header "LICENCE AND COPYRIGHT"
Copyright E<copy> 2003 Iain Truskett. All rights reserved. This library
is free software; you can redistribute it and/or modify it under the
same terms as Perl itself.
.PP
The full text of the licences can be found in the \fIArtistic\fR and
\&\fI\s-1COPYING\s0\fR files included with this module.
.SH "AUTHOR"
.IX Header "AUTHOR"
Originally written by Iain Truskett <spoon@cpan.org>, who died on
December 29, 2003.
.PP
Maintained by Dave Rolsky <autarch@urth.org>.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
datetime@perl.org mailing list.
.PP
http://datetime.perl.org/
.PP
perl, DateTime, Spreadsheet::WriteExcel