Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Date::Simple(3)	      User Contributed Perl Documentation      Date::Simple(3)

NAME
       Date::Simple - a	simple date object

SYNOPSIS
	   use Date::Simple ('date', 'today');

	   # Difference	in days	between	two dates:
	   $diff = date('2001-08-27') -	date('1977-10-05');

	   # Offset $n days from now:
	   $date = today() + $n;
	   print "$date\n";  # uses ISO	8601 format (YYYY-MM-DD)

	   use Date::Simple ();
	   my $date  = Date::Simple->new('1972-01-17');
	   my $year  = $date->year;
	   my $month = $date->month;
	   my $day   = $date->day;

	   use Date::Simple (':all');
	   my $date2 = ymd($year, $month, $day);
	   my $date3 = d8('19871218');
	   my $today = today();
	   my $tomorrow	= $today + 1;
	   if ($tomorrow->year != $today->year)	{
	       print "Today is New Year's Eve!\n";
	   }

	   if ($today >	$tomorrow) {
	       die "warp in space-time continuum";
	   }

	   print "Today	is ";
	   print(('Sun','Mon','Tues','Wednes','Thurs','Fri','Satur')
		 [$today->day_of_week]);
	   print "day.\n";

	   # you can also do this:
	   ($date cmp "2001-07-01")
	   # and this
	   ($date <=> [2001, 7,	1])

DESCRIPTION
       Dates are complex enough	without	times and timezones.  This module may
       be used to create simple	date objects.  It handles:

       Validation.
	   Reject 1999-02-29 but accept	2000-02-29.

       Interval	arithmetic.
	   How many days were between two given	dates?	What date comes	N days
	   after today?

       Day-of-week calculation.
	   What	day of the week	is a given date?

       Transparent date	formatting.
	   How should a	date object be formatted.

       It does not deal	with hours, minutes, seconds, and time zones.

       A date is uniquely identified by	year, month, and day integers within
       valid ranges.  This module will not allow the creation of objects for
       invalid dates.  Attempting to create an invalid date will return	undef.
       Month numbering starts at 1 for January,	unlike in C and	Java.  Years
       are 4-digit.

       Gregorian dates up to year 9999 are handled correctly, but we rely on
       Perl's builtin "localtime" function when	the current date is requested.
       On some platforms, "localtime" may be vulnerable	to rollovers such as
       the Unix	"time_t" wraparound of 18 January 2038.

       Overloading is used so you can compare or subtract two dates using
       standard	numeric	operators such as "==",	and the	sum of a date object
       and an integer is another date object.

       Date::Simple objects are	immutable.  After assigning $date1 to $date2,
       no change to $date1 can affect $date2.  This means, for example,	that
       there is	nothing	like a "set_year" operation, and "$date++" assigns a
       new object to $date.

       This module contains various undocumented functions.  They may not be
       available on all	platforms and are likely to change or disappear	in
       future releases.	 Please	let the	author know if you think any of	them
       should be public.

   Controlling output format.
       As of version 3.0 new ways of controlling the output formats of
       Date::Simple objects has	been provided. However Date::Simple has
       traditionally provided few ways of stringification, a primary one via
       the format() method and another primary one via direct stringification.
       However the later is currently implemented as an	XS routine and the
       former is implemented through a perl routine.  This means that using
       format()	is more	expensive than stringification and that	the
       stringification format is class specific.

       In order	to alleviate some of these problems a new mechanism has	been
       introduced to Date::Simple that allows for a per	object level format
       default.	In addition a set of utility classes that have different
       stringification overloads provided.  These classes are simple
       subclasses of Date::Simple and beside the default format() and the
       overloaded stringification behaviour are	identical to Date::Simple. In
       fact one	is totally identical to	Date::Simple and is provided mostly
       for completeness.

       The classes included are:

       Date::Simple::ISO
	   Identical to	Date::Simple in	every respect but name.

       Date::Simple::D8
	   Uses	the D8 format (%Y%m%d) as the default format for printing.
	   Uses	XS for the overloaded stringification.

       Date::Simple::Fmt
	   Uses	the perl implemented format() as the default stringification
	   mechanism. The first	argument to the	constructor is expected	to be
	   the format to use for the object.

       NOTE its	important to remember that the primary difference between the
       behaviour of objects of the different classes is	how they are
       stringified when	quoted,	and what date format is	used by	default	when
       the format() method is called. Nothing else differs.

CONSTRUCTORS
       Several functions take a	string or numeric representation and generate
       a corresponding date object.  The most general is "new",	whose argument
       list may	be empty (returning the	current	date), a string	in format
       YYYY-MM-DD or YYYYMMDD, a list or arrayref of year, month, and day
       number, or an existing date object.

       Date::Simple->new ([ARG,	...])
       date ([ARG, ...])
	       my $date	= Date::Simple->new('1972-01-17');

	   The "new" method will return	a date object if the values passed in
	   specify a valid date.  (See above.)	If an invalid date is passed,
	   the method returns undef.  If the argument is invalid in form as
	   opposed to numeric range, "new" dies.

	   The "date" function provides	the same functionality but must	be
	   imported or qualified as "Date::Simple::date".  (To import all
	   public functions, do	"use Date::Simple (':all');".)	This function
	   returns undef on all	invalid	input, rather than dying in some cases
	   like	"new".

       date_fmt	(FMT,[ARG, ...])
	   Equivelent to "date"	but creates a Date::Simple::Fmt	object
	   instead. The	format is expected to be a valid POSIX::strftime
	   format string.

       date_iso	([ARG, ...])
	   Identical to	"date" but creates a Date::Simple::ISO object instead.

       date_d8 ([ARG, ...])
	   Equivelent to "date"	but creates a Date::Simple::D8 object instead.

       today()
	   Returns the current date according to "localtime".

	   Caution: To get tomorrow's date (or any fixed offset	from today),
	   do not use "today + 1".  Perl parses	this as	"today(+1)".  You need
	   to put empty	parentheses after the function:	"today() + 1".

       ymd (YEAR, MONTH, DAY)
	   Returns a date object with the given	year, month, and day numbers.
	   If the arguments do not specify a valid date, undef is returned.

	   Example:

	       use Date::Simple	('ymd');
	       $pbd = ymd(1987,	12, 18);

       d8 (STRING)
	   Parses STRING as "YYYYMMDD" and returns the corresponding date
	   object, or undef if STRING has the wrong format or specifies	an
	   invalid date.

	   Example:

	       use Date::Simple	('d8');
	       $doi = d8('17760704');

	   Mnemonic: The string	matches	"/\d{8}/".  Also, "d8" spells "date",
	   if 8	is expanded phonetically.

INSTANCE METHODS
       DATE->next
	       my $tomorrow = $today->next;

	   Returns an object representing tomorrow.

       DATE->prev
	      my $yesterday = $today->prev;

	   Returns an object representing yesterday.

       DATE->year
	       my $year	 = $date->year;

	   Return the year of DATE as an integer.

       DATE->month
	       my $month = $date->month;

	   Return the month of DATE as an integer from 1 to 12.

       DATE->day
	       my $day	 = $date->day;

	   Return the DATE's day of the	month as an integer from 1 to 31.

       DATE->day_of_week
	   Return a number representing	DATE's day of the week from 0 to 6,
	   where 0 means Sunday.

       DATE->as_ymd
	       my ($year, $month, $day)	= $date->as_ymd;

	   Returns a list of three numbers: year, month, and day.

       DATE->as_d8
	   Returns the "d8" representation (see	"d8"), like
	   "$date->format("%Y%m%d")".

       DATE->as_iso
	   Returns the ISO 8601	representation of the date (eg '2004-01-01'),
	   like	"$date->format("%Y-%m-%d")". This is in	fact the default
	   overloaded stringification mechanism	and is provided	mostly so
	   other subclasses with different overloading can still do fast ISO
	   style date output.

       DATE->as_str ([STRING])
       DATE->format ([STRING])
       DATE->strftime ([STRING])
	   These functions are equivalent.  Return a string representing the
	   date, in the	format specified.  If you don't	pass a parameter, the
	   default date	format for the object is used if one has been
	   specified, otherwise	uses the default date format for the class the
	   object is a member of, or as	a last fallback	uses the
	   $Date::Simple::Standard_Format which	is changeable, but probably
	   shouldn't be	modified. See "default_format" for details.

	       my $change_date = $date->format("%d %b %y");
	       my $iso_date1 = $date->format("%Y-%m-%d");
	       my $iso_date2 = $date->format;

	   The formatting parameter is similar to one you would	pass to
	   strftime(3).	 This is because we actually do	pass it	to strftime to
	   format the date.  This may result in	differing behavior across
	   platforms and locales and may not even work everywhere.

       DATE->default_format ([FORMAT])
	   This	method sets or gets the	default_format for the DATE object or
	   class that it is called on.

OPERATORS
       Some operators can be used with Date::Simple instances.	If one side of
       an expression is	a date object, and the operator	expects	two date
       objects,	the other side is interpreted as "date(ARG)", so an array
       reference or ISO	8601 string will work.

       DATE + NUMBER
       DATE - NUMBER
	   You can construct a new date	offset by a number of days using the
	   "+" and "-" operators.

       DATE1 - DATE2
	   You can subtract two	dates to find the number of days between them.

       DATE1 ==	DATE2
       DATE1 < DATE2
       DATE1 <=> DATE2
       DATE1 cmp DATE2
       etc.
	   You can compare two dates using the arithmetic or string comparison
	   operators.  Equality	tests ("==" and	"eq") return false when	one of
	   the expressions can not be converted	to a date.  Other comparison
	   tests die in	such cases.  This is intentional, because in a sense,
	   all non-dates are not "equal" to all	dates, but in no sense are
	   they	"greater" or "less" than dates.

       DATE += NUMBER
       DATE -= NUMBER
	   You can increment or	decrement a date by a number of	days using the
	   += and -= operators.	 This actually generates a new date object and
	   is equivalent to "$date = $date + $number".

       "$date"
	   You can interpolate a date instance directly	into a string, in the
	   format specified by ISO 8601	(eg: 2000-01-17) for Date::Simple and
	   Date::Simple::ISO, for Date::Simple::D8 this	is the same as calling
	   as_d8() on the object, and for Date::Simple::Fmt this is the	same
	   as calling format() on the object.

UTILITIES
       leap_year (YEAR)
	   Returns true	if YEAR	is a leap year.

       days_in_month (YEAR, MONTH)
	   Returns the number of days in MONTH,	YEAR.

       leap_year (YEAR)
	   Returns true	if YEAR	is a leap year.

       days_in_month (YEAR, MONTH)
	   Returns the number of days in MONTH,	YEAR.

AUTHOR
	   Marty Pauley	<marty@kasei.com>
	   John	Tobey <jtobey@john-edwin-tobey.org>
	   Yves	Orton <demerphq@hotmail.com>

COPYRIGHT
	     Copyright (C) 2001	 Kasei.
	     Copyright (C) 2001,2002 John Tobey.
	     Copyright (C) 2004	Yves Orton.

	     This program is free software; you	can redistribute it and/or
	     modify it under the terms of either:

	     a)	the GNU	General	Public License;
		either version 2 of the	License, or (at	your option) any later
		version.  You should have received a copy of the GNU General
		Public License along with this program;	see the	file COPYING.
		If not,	write to the Free Software Foundation, Inc., 59
		Temple Place, Suite 330, Boston, MA 02111-1307 USA

	     b)	the Perl Artistic License.

	     This program is distributed in the	hope that it will be useful,
	     but WITHOUT ANY WARRANTY; without even the	implied	warranty of
	     MERCHANTABILITY or	FITNESS	FOR A PARTICULAR PURPOSE.

SEE ALSO
       Date::Simple::Fmt Date::Simple::ISO Date::Simple::D8 and	of course perl

perl v5.32.1			  2008-12-26		       Date::Simple(3)

NAME | SYNOPSIS | DESCRIPTION | CONSTRUCTORS | INSTANCE METHODS | OPERATORS | UTILITIES | AUTHOR | COPYRIGHT | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Date::Simple&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help