.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" 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
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    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 >0, 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 "Date::Manip::Examples 3pm"
.TH Date::Manip::Examples 3pm 2024-03-02 "perl v5.38.2" "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
Date::Manip::Examples \- examples of how to use Date::Manip
.SH DESCRIPTION
.IX Header "DESCRIPTION"
This document includes a number of examples on how to do common
Date::Manip operations.  I will be happy to add new examples over
time, and welcome suggestions and examples to include.
.PP
In most cases, an example will include two different ways of getting
the answer.  The first way will be using the new (as of 6.00) OO
modules. The second will be using the old-style functional interface.
.PP
It should be noted that any time you want to work with alternate
time zones, the OO interface is STRONGLY recommended since the functional
interface does not preserve time zone information with the date, and
may therefore give incorrect results in some cases. However, working
in the time zone of the system should give correct results.
.PP
It should be noted that, in the examples below, it appears that the OO
method often requires more lines of code than the functional
interface.  There are a number of ways to shorten the OO method, but
for the examples, I wanted to include all the steps explicitly.
.SH "PARSING A DATE"
.IX Header "PARSING A DATE"
Dates can be parsed in practically any form in common usage:
.IP "\fBOO method\fR" 4
.IX Item "OO method"
.Vb 6
\&   $date = new Date::Manip::Date;
\&   $err = $date\->parse("today");
\&   $err = $date\->parse("1st Thursday in June 1992");
\&   $err = $date\->parse("05/10/93");
\&   $err = $date\->parse("12:30 Dec 12th 1880");
\&   $err = $date\->parse("8:00pm December tenth");
.Ve
.IP \fBFunctional\fR 4
.IX Item "Functional"
.Vb 5
\&   $date = ParseDate("today");
\&   $date = ParseDate("1st Thursday in June 1992");
\&   $date = ParseDate("05/10/93");
\&   $date = ParseDate("12:30 Dec 12th 1880");
\&   $date = ParseDate("8:00pm December tenth");
.Ve
.PP
The Date::Manip::Date manual has a list of all valid formats.
.SH "PARSING AN AMOUNT OF TIME"
.IX Header "PARSING AN AMOUNT OF TIME"
Amounts of time (referred to as deltas) can also be parsed:
.IP "\fBOO method\fR" 4
.IX Item "OO method"
.Vb 4
\&   $delta = new Date::Manip::Delta;
\&   $err = $delta\->parse("in 12 hours");
\&   $err = $delta\->parse("\-1:30:0");
\&   $err = $delta\->parse("4 business days later");
.Ve
.IP \fBFunctional\fR 4
.IX Item "Functional"
.Vb 3
\&   $delta = ParseDateDelta("in 12 hours");
\&   $delta = ParseDateDelta("\-1:30:0");
\&   $delta = ParseDateDelta("4 business days later");
.Ve
.SH "TO CALCULATE THE AMOUNT OF TIME BETWEEN TWO DATES"
.IX Header "TO CALCULATE THE AMOUNT OF TIME BETWEEN TWO DATES"
.Vb 2
\&   $datestr1 = "Jan 30 1999 13:00 EST";
\&   $datestr2 = "2/Mar/1999 15:30:00 +0500";
.Ve
.IP "\fBOO method\fR" 4
.IX Item "OO method"
.Vb 4
\&   $date1 = new Date::Manip::Date;
\&   $date2 = $date1\->new_date();
\&   $err = $date1\->parse($datestr1);
\&   $err = $date2\->parse($datestr2);
.Ve
.Sp
To get an exact amount of time between the two dates (expressed only in terms of
hours, minutes, seconds), use:
.Sp
.Vb 1
\&   $delta = $date1\->calc($date2);
.Ve
.Sp
To get an approximate amount of time (expressed in terms of years, months, weeks,
etc. in terms that a human would typically think of), use:
.Sp
.Vb 1
\&   $delta = $date1\->calc($date2,"approx");
.Ve
.IP \fBFunctional\fR 4
.IX Item "Functional"
.Vb 2
\&   $date1 = ParseDate($string1);
\&   $date2 = ParseDate($string2);
.Ve
.Sp
To get an exact amount:
.Sp
.Vb 1
\&   $delta = DateCalc($date1,$date2);
.Ve
.Sp
and the approximate amount:
.Sp
.Vb 1
\&   $delta = DateCalc($date1,$date2,1);
.Ve
.PP
The Date::Manip::Calc manual has information about these, and other types of
calculations.
.SH "TO ADD AN AMOUNT OF TIME TO A DATE"
.IX Header "TO ADD AN AMOUNT OF TIME TO A DATE"
To find a second date a given amount of time before or after a first date,
use the following:
.PP
.Vb 3
\&   $datestr  = "Jan 30 1999 13:00 EST";
\&   $deltastr = "12 hours ago";
\&   $deltastr = "in 3 business days";
.Ve
.IP "\fBOO method\fR" 4
.IX Item "OO method"
.Vb 4
\&   $date = new Date::Manip::Date;
\&   $delta = $date\->new_delta();
\&   $date\->parse($datestr);
\&   $delta\->parse($deltastr);
\&
\&   $d = $date\->calc($delta);
.Ve
.IP \fBFunctional\fR 4
.IX Item "Functional"
.Vb 1
\&   $date = DateCalc($datestr,$deltastr);
.Ve
.PP
If the delta is a business delta, it will do a business mode calculation.
.PP
The Date::Manip::Calc manual has information about these, and other types of
calculations.
.SH "COMPARE TWO DATES"
.IX Header "COMPARE TWO DATES"
To take two different dates and see which is earlier, do the
following:
.PP
.Vb 2
\&   $datestr1 = "Jan 30 1999 13:00 EST";
\&   $datestr2 = "2/Mar/1999 15:30:00 +0500";
.Ve
.IP "\fBOO method\fR" 4
.IX Item "OO method"
.Vb 4
\&   $date1 = new Date::Manip::Date;
\&   $date2 = $date1\->new_date;
\&   $date1\->parse($datestr1);
\&   $date2\->parse($datestr2);
\&
\&   $date1\->cmp($date2);
\&      => \-1, 0, 1
.Ve
.IP \fBFunctional\fR 4
.IX Item "Functional"
.Vb 2
\&   $date1 = ParseDate($datestr1);
\&   $date2 = ParseDate($datestr2);
\&
\&   Date_Cmp($date1,$date2);
\&      => \-1, 0, 1
.Ve
.SH "TO EXTRACT INFORMATION ABOUT A DATE OR DELTA"
.IX Header "TO EXTRACT INFORMATION ABOUT A DATE OR DELTA"
If you have a date or a delta, you can extract information
about them as follows:
.PP
.Vb 2
\&   $datestr  = "1:24:08 PM EST Feb 3, 1996";
\&   $deltastr = "12 hours ago";
.Ve
.IP "\fBOO method\fR" 4
.IX Item "OO method"
.Vb 4
\&   $date = new Date::Manip::Date;
\&   $delta = $date\->new_delta();
\&   $date\->parse($datestr);
\&   $delta\->parse($deltastr);
\&
\&   $str = $date\->printf("It is now %T on %b %e, %Y.");
\&     =>  "It is now 13:24:08 on Feb  3, 1996."
\&
\&   $str = $delta\->printf("In %hv hours, %mv minutes, %sv seconds");
\&     => "In \-12 hours, 0 minutes, 0 seconds";
.Ve
.IP \fBFunctional\fR 4
.IX Item "Functional"
.Vb 2
\&   $str = UnixDate($datestr,"It is now %T on %b %e, %Y.");
\&     =>  "It is now 13:24:08 on Feb  3, 1996."
\&
\&   $str = Delta_Format($deltastr,"In %hv hours, %mv minutes, %sv seconds");
\&     => "In \-12 hours, 0 minutes, 0 seconds";
.Ve
.PP
The Date::Manip::Date manual contains all of the format codes that can
be used to extract information from a date. The Date::Manip::Delta manual
contains the codes for a delta.
.SH "WORKING WITH EPOCH"
.IX Header "WORKING WITH EPOCH"
Date::Manip can easily be used to work with the number of seconds
since the epoch (Jan 1, 1970 00:00:00 UTC).
.PP
If you have a date, and you want to find out how many seconds it is
after the epoch, you can do it in the following ways:
.PP
.Vb 2
\&   $datestr  = "1999\-04\-30\-15:30:00 EDT";
\&   $secs  = 1234567;
.Ve
.IP "\fBOO method\fR" 4
.IX Item "OO method"
To find out how many seconds have elapsed on a certain date, you
can do the following:
.Sp
.Vb 2
\&   $date     = new Date::Manip::Date;
\&   $err      = $date\->parse($datestr);
\&
\&   $str      = $date\->printf(\*(Aq%s\*(Aq);
\&      => number of seconds
.Ve
.Sp
To find out the date that is a certain number of seconds since the
epoch, you can use the following:
.Sp
.Vb 2
\&   $date  = new Date::Manip::Date;
\&   $err   = $date\->parse("epoch $secs");
.Ve
.Sp
\&\f(CW$date\fR now contains the date wanted (in the local time zone)
.IP \fBFunctional\fR 4
.IX Item "Functional"
To find out how many seconds have elapsed:
.Sp
.Vb 2
\&   $str = UnixDate($datestr,\*(Aq%s\*(Aq);
\&     => number of seconds
.Ve
.Sp
To find the date that is a number of seconds since the epoch:
.Sp
.Vb 1
\&   $date = ParseDateString("epoch $secs");
.Ve
.PP
Note that Date::Manip will work with both positive seconds (for dates
that have come since the epoch) and negative seconds (for dates that
occurred before the epoch).
.SH "RECURRING EVENTS"
.IX Header "RECURRING EVENTS"
To find a list of dates where a recurring event happens (even very complex
recurrences), do the following:
.IP "\fBOO method\fR" 4
.IX Item "OO method"
.Vb 1
\&  # To find the 2nd Tuesday of every month from Jan 1 1999 to Apr 30 1999
\&
\&  $recur = new Date::Manip::Recur;
\&  $start = $recur\->new_date();
\&  $end   = $recur\->new_date();
\&  $start\->parse("Jan 1 1999");
\&  $end\->parse("Apr 30 1999");
\&
\&  $recur\->parse("0:1*2:2:0:0:0",$start,$end);
\&  @date = $recur\->dates();
\&
\&  # To find the Monday after Easter in 1997\-1999
\&
\&  $recur = new Date::Manip::Recur;
\&  $recur\->parse("*1997\-1999:0:0:0:0:0:0*EASTER,ND1");
\&  @date = $recur\->dates();
.Ve
.IP \fBFunctional\fR 4
.IX Item "Functional"
.Vb 2
\&  # To find the 2nd Tuesday of every month from Jan 1 1999 to Apr 30 1999
\&  @date = ParseRecur("0:1*2:2:0:0:0","","Jan 1 1999","Apr 30 1999");
\&
\&  # To find the Monday after Easter in 1997\-1999.
\&  @date = ParseRecur("*1997\-1999:0:0:0:0:0:0*EASTER,ND1");
.Ve
.PP
The Date::Manip::Recur manual contains information about recurring events.
.SH "WORKING WITH DATES IN ANOTHER LANGUAGE"
.IX Header "WORKING WITH DATES IN ANOTHER LANGUAGE"
If you want to work with dates in a language other than English (but you
are only working with a single language), do the following:
.IP "\fBOO method\fR" 4
.IX Item "OO method"
.Vb 3
\&   $date = new Date::Manip::Date;
\&   $date\->config("Language","French","DateFormat","non\-US");
\&   $date\->parse("1er decembre 1990");
.Ve
.IP \fBFunctional\fR 4
.IX Item "Functional"
.Vb 2
\&   Date_Init("Language=French","DateFormat=non\-US");
\&   $date = ParseDate("1er decembre 1990");
.Ve
.PP
The Date::Manip::Config manual has a list of all supported languages (in the
section on the Language config variable). The meaning of the DateFormat
config variable is also included.
.SH "WORKING WITH TWO DIFFERENT LANGUAGES"
.IX Header "WORKING WITH TWO DIFFERENT LANGUAGES"
If you want to work with dates in two (or more) languages, it is STRONGLY
recommended that you use the OO interface. The functional interface will
be much slower since it has to re-initialize a lot of language-specific
stuff every time you switch back and forth between languages.
.IP "\fBOO method\fR" 4
.IX Item "OO method"
.Vb 2
\&   $date_eng = new Date::Manip::Date;
\&   $date_eng\->config("Language","English","DateFormat","US");
\&
\&   $date_fre = new Date::Manip::Date;
\&   $date_fre\->config("Language","French","DateFormat","non\-US");
.Ve
.Sp
Use the \f(CW$date_eng\fR object to do English operations, the \f(CW$date_fre\fR object to
do French operations.
.IP \fBFunctional\fR 4
.IX Item "Functional"
If you are working with both French and English dates, you can call
the following to switch between them:
.Sp
.Vb 2
\&   Date_Init("Language=French","DateFormat=non\-US");
\&   Date_Init("Language=English","DateFormat=US");
.Ve
.Sp
This is NOT recommended. Use the OO method instead.
.SH "BUGS AND QUESTIONS"
.IX Header "BUGS AND QUESTIONS"
Please refer to the Date::Manip::Problems documentation for
information on submitting bug reports or questions to the author.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Date::Manip        \- main module documentation
.SH LICENSE
.IX Header "LICENSE"
This script is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.
.SH AUTHOR
.IX Header "AUTHOR"
Sullivan Beck (sbeck@cpan.org)