490 lines
12 KiB
HTML
490 lines
12 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
|
<head>
|
|
<title>GT::Date - Common date parsing and manipulation routines</title>
|
|
<link rev="made" href="mailto:root@penguin.office.gossamer-threads.com" />
|
|
|
|
<style type="text/css">
|
|
/* $MVD$:fontset("Untitled Font Set 1","ARIEL","HELVETICA","HELV","SANSERIF") */
|
|
/* $MVD$:fontset("Arial","Arial") */
|
|
/* $MVD$:fontset("Arial Black","Arial Black") */
|
|
/* $MVD$:fontset("Algerian","Algerian") */
|
|
|
|
|
|
body {
|
|
background-color: white;
|
|
font-family: Verdana, Arial, sans-serif;
|
|
font-size: small;
|
|
color: black;
|
|
}
|
|
|
|
|
|
p {
|
|
background-color : white;
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
|
|
h1 {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-weight : bold;
|
|
font-size : medium;
|
|
background-color : white;
|
|
color : maroon;
|
|
}
|
|
|
|
|
|
h2 {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : medium;
|
|
font-weight : bold;
|
|
color : blue;
|
|
background-color : white;
|
|
}
|
|
|
|
|
|
h3 {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-weight : bold;
|
|
font-size : medium;
|
|
color : black;
|
|
background-color : white;
|
|
}
|
|
|
|
|
|
h4 {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-weight : bold;
|
|
font-size : small;
|
|
color : maroon;
|
|
background-color : white;
|
|
}
|
|
|
|
|
|
h5 {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-weight : bold;
|
|
font-size : small;
|
|
color : blue;
|
|
background-color : white;
|
|
}
|
|
|
|
|
|
h6 {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-weight : bold;
|
|
font-size : small;
|
|
color : black;
|
|
background-color : white;
|
|
}
|
|
|
|
|
|
ul {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
|
|
ol {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
|
|
dl {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
|
|
li {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
|
|
th {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
|
|
td {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
|
|
dl {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
|
|
dd {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
|
|
dt {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
|
|
code {
|
|
font-family : Courier;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
|
|
pre {
|
|
font-family : Courier;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
.mvd-H1 {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-weight : bold;
|
|
font-size : 14.0pt;
|
|
background-color : transparent;
|
|
background-image : none;
|
|
color : maroon;
|
|
}
|
|
|
|
|
|
.mvd-H2 {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : 12.0pt;
|
|
color : blue;
|
|
}
|
|
|
|
|
|
p.indent {
|
|
font-family : "Verdana, Arial, sans-serif";
|
|
list-style-type : circle;
|
|
list-style-position : inside;
|
|
color : black;
|
|
margin-left : 16.0pt;
|
|
}
|
|
|
|
|
|
.mvd-P-indent {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
list-style-type : circle;
|
|
list-style-position : inside;
|
|
color : black;
|
|
margin-left : 16.0pt;
|
|
}
|
|
|
|
|
|
pre.programlisting {
|
|
font-size : 9.0pt;
|
|
list-style-type : disc;
|
|
margin-left : 16.0pt;
|
|
margin-top : -14.0pt;
|
|
}
|
|
|
|
|
|
.mvd-PRE-programlisting {
|
|
font-size : 9.0pt;
|
|
list-style-type : disc;
|
|
margin-left : 16.0pt;
|
|
margin-top : -14.0pt;
|
|
}
|
|
|
|
|
|
.mvd-PRE {
|
|
font-size : 9.0pt;
|
|
}
|
|
|
|
|
|
p.note {
|
|
margin-left : 28.0pt;
|
|
}
|
|
|
|
|
|
.mvd-P-note {
|
|
margin-left : 28.0pt;
|
|
}
|
|
|
|
|
|
.mvd-H4 {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-weight : normal;
|
|
font-size : 9.0pt;
|
|
color : black;
|
|
margin-left : 6.0pt;
|
|
margin-top : -14.0pt;
|
|
}
|
|
|
|
|
|
.mvd-P {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : 10.0pt;
|
|
color : black;
|
|
}
|
|
|
|
.mvd-BODY {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
background-color : white;
|
|
}
|
|
|
|
|
|
p.indentnobullet {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
list-style-type : none;
|
|
}
|
|
|
|
|
|
.mvd-P-indentnobullet {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
list-style-type : none;
|
|
}
|
|
</style>
|
|
|
|
|
|
</head>
|
|
|
|
<body style="background-color: white">
|
|
|
|
<p><a name="__index__"></a></p>
|
|
<!-- INDEX BEGIN -->
|
|
|
|
<ul>
|
|
|
|
<li><a href="#name">NAME</a></li>
|
|
<li><a href="#synopsis">SYNOPSIS</a></li>
|
|
<li><a href="#description">DESCRIPTION</a></li>
|
|
<ul>
|
|
|
|
<li><a href="#date_is_valid">date_is_valid</a></li>
|
|
<li><a href="#date_is_greater">date_is_greater</a></li>
|
|
<li><a href="#date_is_smaller">date_is_smaller</a></li>
|
|
<li><a href="#date_get_date_get_gm">date_get date_get_gm</a></li>
|
|
<li><a href="#date_comp">date_comp</a></li>
|
|
<li><a href="#date_diff">date_diff</a></li>
|
|
<li><a href="#date_add_date_add_gm">date_add date_add_gm</a></li>
|
|
<li><a href="#date_sub_date_sub_gm">date_sub date_sub_gm</a></li>
|
|
<li><a href="#timegm">timegm</a></li>
|
|
<li><a href="#timlocal">timlocal</a></li>
|
|
<li><a href="#parse_format">parse_format</a></li>
|
|
<li><a href="#format_date">format_date</a></li>
|
|
<li><a href="#setting_date_format">Setting date format</a></li>
|
|
<li><a href="#transforming_between_date_formats_">Transforming between date formats.</a></li>
|
|
<li><a href="#getting_the_gm_offset_">Getting the GM offset.</a></li>
|
|
</ul>
|
|
|
|
<li><a href="#examples">EXAMPLES</a></li>
|
|
<li><a href="#copyright">COPYRIGHT</a></li>
|
|
<li><a href="#version">VERSION</a></li>
|
|
</ul>
|
|
<!-- INDEX END -->
|
|
|
|
<hr />
|
|
<p>
|
|
</p>
|
|
<h1><a name="name">NAME</a></h1>
|
|
<p>GT::Date - Common date parsing and manipulation routines</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="synopsis">SYNOPSIS</a></h1>
|
|
<pre>
|
|
use GT::Date qw/:all/;
|
|
my $date = date_get();
|
|
my $next_week = date_add($date, 7);
|
|
my $is_bigger = date_is_greater($date, $next_week);</pre>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="description">DESCRIPTION</a></h1>
|
|
<p>GT::Date provides several functions useful in parsing dates, and
|
|
doing date manipulation. Under the hood, it uses Time::Local
|
|
code to transform a date into seconds for comparison and
|
|
mathematical operations. It also uses <a href="glist.cgi?do=admin_gtdoc&topic=/GT/Cache.html">the GT::Cache manpage</a> to store
|
|
most of the complex work.</p>
|
|
<p>No functions are exported by default. You can either specify
|
|
the functions you need in use, or use the tags ':all' or
|
|
':timelocal'. All will give you all functions, and timelocal
|
|
will give you functions found in Time::Local.</p>
|
|
<p>GT::Date uses a package global $DATE_FMT which specifies
|
|
the format that dates should be returned in. You can change this using
|
|
the <code>date_set_format()</code> function.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="date_is_valid">date_is_valid</a></h2>
|
|
<p>Returns 1 if the argument passed in is a valid date. It must first
|
|
be in the current date format, and then be a valid date.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="date_is_greater">date_is_greater</a></h2>
|
|
<p>Returns 1 if argument 1 is greater then argument 2, otherwise 0.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="date_is_smaller">date_is_smaller</a></h2>
|
|
<p>Returns 1 if argument 1 is smaller then argument 2, otherwise 0.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="date_get_date_get_gm">date_get date_get_gm</a></h2>
|
|
<p>Called with no arguments, returns the current date based on system
|
|
time. You can specify the date you want by passing in the seconds
|
|
since epoch (output of time()).</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="date_comp">date_comp</a></h2>
|
|
<p>Equivalent to arg1 <=> arg2.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="date_diff">date_diff</a></h2>
|
|
<p>Returns number of days difference between arg1 - arg2.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="date_add_date_add_gm">date_add date_add_gm</a></h2>
|
|
<p>Returns date derived from arg1 + arg2, where the second argument
|
|
can be either a date or number of days.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="date_sub_date_sub_gm">date_sub date_sub_gm</a></h2>
|
|
<p>Returns date derived from arg1 - arg2, where the second argument
|
|
can be either a date or number of days.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="timegm">timegm</a></h2>
|
|
<p>Takes the returned array from <code>gmtime()</code> and returns a unix time
|
|
stamp.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="timlocal">timlocal</a></h2>
|
|
<p>Takes the array returned by <code>localtime()</code> and returns a unix time
|
|
stamp.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="parse_format">parse_format</a></h2>
|
|
<p>Takes a string and a date format and returns an array
|
|
ref of the first 7 arguments returned by localtime().</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="format_date">format_date</a></h2>
|
|
<p>Takes a localtime array, and a format string and returns a string
|
|
of the parsed format.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="setting_date_format">Setting date format</a></h2>
|
|
<p>You can use date_set_format to change the format. You pass in a
|
|
format string. It is made up of:</p>
|
|
<pre>
|
|
%yyyy% four digit year as in 1999
|
|
%yy% two digit year as in 99
|
|
%y% two digit year without leading 0
|
|
%mmmm% long month name as in January
|
|
%mmm% short month name as in Jan
|
|
%mm% numerical month name as in 01
|
|
%m% numerical month name without leading 0 as in 1
|
|
%dddd% long day name as in Sunday
|
|
%ddd% short day name as in Sun
|
|
%dd% numerical date
|
|
%d% numerical date without leading 0
|
|
%HH% two digit hour, 24 hour time
|
|
%H% one or two digit hour, 24 hour time
|
|
%hh% two digit hour, 12 hour time. 0 becomes 12.
|
|
%h% one or two digit hour, 12 hour time. 0 becomes 12.
|
|
%MM% two digit minute
|
|
%M% one or two digit minute (when would someone ever WANT this?)
|
|
%ss% two digit second
|
|
%s% one ot two digit second (when would someone ever WANT this?)
|
|
%tt% AM or PM (use with 12 hour time)
|
|
%o% + or - GMT offset</pre>
|
|
<p>Common formats include:</p>
|
|
<pre>
|
|
%yyyy%-%mm%-%dd% 1999-12-25
|
|
%dd%-%mmm%-%yyyy% 12-Dec-1999
|
|
%ddd% %mmm% %dd% %yyyy% Sat Dec 12 1999
|
|
%ddd% %mmm% %dd% %yyyy% Sat Dec 12 1999</pre>
|
|
<p>or RFC822 mime mail format:</p>
|
|
<pre>
|
|
%ddd%, %dd% %mmm% %yyyy% %HH%:%MM%:%ss% %o% Sat, 12, Dec 1999 21:32:02 -0800</pre>
|
|
<p>or MySQL format:</p>
|
|
<pre>
|
|
%yyyy%-%mm%-%dd% %HH%:%MM%:%ss% 1999-03-25 21:32:02</pre>
|
|
<p>The language used for month names and day names can be changed with
|
|
date_set_month(), date_set_days(), <code>date_set_days_short()</code> and
|
|
date_set_month_short().</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="transforming_between_date_formats_">Transforming between date formats.</a></h2>
|
|
<p>You can transform a date from one format to another with:</p>
|
|
<pre>
|
|
date_transform ($date, $orig_fmt, $new_fmt);</pre>
|
|
<p>where $orig_fmt and $new_fmt are date format strings described above.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="getting_the_gm_offset_">Getting the GM offset.</a></h2>
|
|
<p>You can get the number of seconds between the system time and GM time
|
|
using:</p>
|
|
<pre>
|
|
my $time = date_gmt_offset();</pre>
|
|
<p>So if you are in Pacific time, it would return 25200 seconds (-0700 time zone).</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="examples">EXAMPLES</a></h1>
|
|
<p>Get todays date, the default format unless specified is yyyy-mm-dd.</p>
|
|
<pre>
|
|
print date_get(); 2000-12-31</pre>
|
|
<p>Get todays date in a different format:</p>
|
|
<pre>
|
|
date_set_format('%ddd% %mmm% %dd% %yyyy%');
|
|
print date_get(); Sat Dec 31 2000</pre>
|
|
<p>Get the date from 1 week ago.</p>
|
|
<pre>
|
|
# Long way
|
|
my $date1 = date_get();
|
|
my $date2 = date_sub($date1, 7);</pre>
|
|
<pre>
|
|
or</pre>
|
|
<pre>
|
|
# Can pass in unix timestamp of date we want.
|
|
my $date = date_get (time - (7 * 86400));</pre>
|
|
<p>Compare two dates.</p>
|
|
<pre>
|
|
my $halloween = '2000-10-31';
|
|
my $christmas = '2000-12-25';
|
|
if (date_is_smaller($halloween, $christmas)) {
|
|
print "Halloween comes before christmas!";
|
|
}
|
|
if (date_is_greater($christmas, $halloween)) {
|
|
print "Yup, christmas comes after halloween.";
|
|
}
|
|
my @dates = ($halloween, $christmas);
|
|
print "Dates in order: ", sort date_comp @dates;</pre>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="copyright">COPYRIGHT</a></h1>
|
|
<p>Copyright (c) 2004 Gossamer Threads Inc. All Rights Reserved.
|
|
<a href="http://www.gossamer-threads.com/">http://www.gossamer-threads.com/</a></p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="version">VERSION</a></h1>
|
|
<p>Revision: $Id: Date.pm,v 1.75 2005/04/04 22:21:23 brewt Exp $</p>
|
|
|
|
</body>
|
|
|
|
</html>
|