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

FreeBSD Manual Pages

  
 
  

home | help
DateTime::Incomplete(3User Contributed Perl DocumentatiDateTime::Incomplete(3)

NAME
       DateTime::Incomplete - An incomplete datetime, like January 5

SYNOPSIS
	 my $dti = DateTime::Incomplete->new( year => 2003 );
	 # 2003-xx-xx
	 $dti->set( month => 12	);
	 # 2003-12-xx
	 $dt = $dti->to_datetime( base => DateTime->now	);
	 # 2003-12-19T16:54:33

DESCRIPTION
       DateTime::Incomplete is a class for representing	partial	dates and
       times.

       These are actually encountered relatively frequently.  For example, a
       birthday	is commonly given as a month and day, without a	year.

ERROR HANDLING
       Constructor and mutator methods (such as	"new" and "set") will die if
       there is	an attempt to set the datetime to an invalid value.

       Invalid values are detected by setting the appropriate fields of	a
       "base" datetime object. See the "set_base" method.

       Accessor	methods	(such as "day()") will return either a value or
       "undef",	but will never die.

THE "BASE" DATETIME
       A "DateTime::Incomplete"	object can have	a "base" "DateTime.pm" object.
       This object is used as a	default	datetime in the	"to_datetime()"
       method, and it also used	to validate inputs to the "set()" method.

       The base	object must use	the year/month/day system.  Most calendars use
       this system including Gregorian ("DateTime") and	Julian.	 Note that
       this module has not been	well tested with base objects from classes
       other than "DateTime.pm"	class.

       By default, newly created "DateTime::Incomplete"	objects	have no	base.

DATETIME-LIKE METHODS
       Most methods provided by	this class are designed	to emulate the
       behavior	of "DateTime.pm" whenever possible.

       o   new()

	   Creates a new incomplete date:

	     my	$dti = DateTime::Incomplete->new( year => 2003 );
	     # 2003-xx-xx

	   This	class method accepts parameters	for each date and time
	   component: "year", "month", "day", "hour", "minute",	"second",
	   "nanosecond".  Additionally,	it accepts "time_zone",	"locale", and
	   "base" parameters.

	   Any parameters not given default to "undef".

	   Calling the "new()" method without parameters creates a completely
	   undefined datetime:

	     my	$dti = DateTime::Incomplete->new();

       o   from_day_of_year( ... )

	   This	constructor takes the same arguments as	can be given to	the
	   "new()" method, except that it does not accept a "month" or "day"
	   argument.  Instead, it requires both	"year" and "day_of_year".  The
	   day of year must be between 1 and 366, and 366 is only allowed for
	   leap	years.

	   It creates a	"DateTime::Incomplete" object with all date fields
	   defined, but	with the time fields (hour, minute, etc.) set to
	   undef.

       o   from_object(	object => $object, ... )

	   This	class method can be used to construct a	new
	   "DateTime::Incomplete" object from any object that implements the
	   "utc_rd_values()" method.  All "DateTime::Calendar" modules must
	   implement this method in order to provide cross-calendar
	   compatibility.  This	method accepts a "locale" parameter.

	   If the object passed	to this	method has a "time_zone()" method,
	   that	is used	to set the time	zone.  Otherwise UTC is	used.

	   It creates a	"DateTime::Incomplete" object with all fields defined.

       o   from_epoch( ... )

	   This	class method can be used to construct a	new
	   "DateTime::Incomplete" object from an epoch time instead of
	   components.	Just as	with the "new()" method, it accepts
	   "time_zone" and "locale" parameters.

	   If the epoch	value is not an	integer, the part after	the decimal
	   will	be converted to	nanoseconds.  This is done in order to be
	   compatible with "Time::HiRes".

	   It creates a	"DateTime::Incomplete" object with all fields defined.

       o   now(	... )

	   This	class method is	equivalent to "DateTime->now".

	   It creates a	new "DateTime::Incomplete" object with all fields
	   defined.

       o   today( ... )

	   This	class method is	equivalent to "now()", but it leaves hour,
	   minute, second and nanosecond undefined.

       o   clone

	   Creates a new object	with the same information as the object	this
	   method is called on.

   "Get" Methods
       o   year

       o   month

       o   day

       o   hour

       o   minute

       o   second

       o   nanosecond

       o   time_zone

       o   locale

	   These methods returns the field value for the object, or "undef".

	   These values	can also be accessed using the same alias methods
	   available in	"DateTime.pm", such as "mon()",	"mday()", etc.

       o   has_year

       o   has_month

       o   has_day

       o   has_hour

       o   has_minute

       o   has_second

       o   has_nanosecond

       o   has_time_zone

       o   has_locale

       o   has_date

       o   has_time

	   Returns a boolean value indicating whether the corresponding
	   component is	defined.

	   "has_date" tests for	year, month, and day.

	   "has_time" tests for	hour, minute, and second.

       o   has

	       $has_date = $dti->has( 'year', 'month', 'day' );

	   Returns a boolean value indicating whether all fields in the
	   argument list are defined.

       o   defined_fields

	       @fields = $dti->defined_fields;	 # list	of field names

	   Returns a list containing the names of the fields that are defined.

	   The list order is: year, month, day,	hour, minute, second,
	   nanosecond, time_zone, locale.

       o   datetime, ymd, date,	hms, time, iso8601, mdy, dmy

	   These are equivalent	to DateTime stringification methods with the
	   same	name, except that the undefined	fields are replaced by 'xx' or
	   'xxxx' as appropriate.

       o   epoch

       o   hires_epoch

       o   is_dst

       o   utc_rd_values

       o   utc_rd_as_seconds

	       my $epoch = $dti->epoch(	base =>	$dt );

	   These methods are equivalent	to the "DateTime" methods with the
	   same	name.

	   They	all accept a "base" argument to	use in order to	calculate the
	   method's return values.

	   If no "base"	argument is given, then	"today"	is used.

       o   is_finite, is_infinite

	   Incomplete dates are	always "finite".

       o   strftime( $format, ... )

	   This	method implements functionality	similar	to the "strftime()"
	   method in C.	 However, if given multiple format strings, then it
	   will	return multiple	scalars, one for each format string.

	   See the "strftime Specifiers" section in the	"DateTime.pm"
	   documentation for a list of all possible format specifiers.

	   Undefined fields are	replaced by 'xx' or 'xxxx' as appropriate.

	   The specification %s	(epoch)	is calculated using "today" as the
	   base	date, unless the object	has a base datetime set.

       Computed	Values

       All other accessors, such as "day_of_week()", or	"week_year()" are
       computed	from the base values for a datetime.  When these methods are
       called, they return the requested information if	there is enough	data
       to compute them,	otherwise they return "undef"

       Unimplemented Methods

       The following "DateTime.pm" methods are not implemented in
       "DateTime::Incomplete", though some of them may be implemented in
       future versions:

       o   add_duration

       o   add

       o   subtract_duration

       o   subtract

       o   subtract_datetime

       o   subtract_datetime_absolute

       o   delta_md

       o   delta_days

       o   delta_ms

       o   compare

       o   compare_ignore_floating

       o   DefaultLanguage

   "Set" Methods
       o   set

	   Use this to set or undefine a datetime field:

	     $dti->set(	month => 12 );
	     $dti->set(	day => 24 );
	     $dti->set(	day => undef );

	   This	method takes the same arguments	as the "set()" method in
	   "DateTime.pm", but it can accept "undef" for	any value.

       o   set_time_zone

	   This	method accepts either a	time zone object or a string that can
	   be passed as	the "name" parameter to	"DateTime::TimeZone->new()".

	   Unlike with "DateTime.pm", if the new time zone's offset is
	   different from the previous time zone, no local time	adjustment is
	   made.

	   You can remove time zone information	by calling this	method with
	   the value "undef".

       o   truncate( to	=> ... )

	   This	method allows you to reset some	of the local time components
	   in the object to their "zero" values.  The "to" parameter is	used
	   to specify which values to truncate,	and it may be one of "year",
	   "month", "day", "hour", "minute", or	"second".  For example,	if
	   "month" is specified, then the local	day becomes 1, and the hour,
	   minute, and second all become 0.

	   Note	that the "to" parameter	cannot be "week".

"DATETIME::INCOMPLETE" METHODS
       "DateTime::Incomplete" objects also have	a number of methods unique to
       this class.

       o   base

	   Returns the base datetime value, or "undef" if the object has none.

       o   has_base

	   Returns a boolean value indicating whether or not the object	has a
	   base	datetime set.

       o   is_undef

	   Returns true	if the datetime	is completely undefined.

       o   can_be_datetime

	   Returns true	if the datetime	has enough information to be converted
	   to a	proper DateTime	object.

	   The year field must be valid, followed by a sequence	of valid
	   fields.

	   Examples:

	     Can be datetime:
	     2003-xx-xxTxx:xx:xx
	     2003-10-xxTxx:xx:xx
	     2003-10-13Txx:xx:xx

	     Can not be	datetime:
	     2003-10-13Txx:xx:30
	     xxxx-10-13Txx:xx:30

       o   set_base

	   Sets	the base datetime object for the "DateTime::Incomplete"
	   object.

	   The default value for "base"	is "undef", which means	no validation
	   is made on input.

       o   to_datetime

	   This	method takes an	optional "base"	parameter and returns a
	   "complete" datetime.

	     $dt = $dti->to_datetime( base => DateTime->now );

	     $dti->set_base( DateTime->now );
	     $dt = $dti->to_datetime;

	   The resulting datetime can be either	before of after	the given base
	   datetime. No	adjustments are	made, besides setting the missing
	   fields.

	   This	method will use	"today"	if the object has no base datetime set
	   and none is given as	an argument.

	   This	method may die if it results in	a datetime that	doesn't
	   actually exist, such	as February 30,	for example.

	   The fields in the resulting datetime	are set	in this	order: locale,
	   time_zone, nanosecond, second, minute, hour,	day, month, year.

       o   to_recurrence

	   This	method generates the set of all	possible datetimes that	fit
	   into	an incomplete datetime definition.

	     $dti = DateTime::Incomplete->new( month =>	12, day	=> 24 );
	     $dtset1 = $dti->to_recurrence;
	     # Christmas recurrence, with _seconds_ resolution

	     $dti->truncate( to	=> 'day' );
	     $dtset2 = $dti->to_recurrence;
	     # Christmas recurrence, with days resolution (hour/min/sec	= 00:00:00)

	   Those recurrences are "DateTime::Set" objects:

	     $dt_next_xmas = $dti->to_recurrence->next(	DateTime->today	);

	   Incomplete dates that have the year defined will generate finite
	   sets.  This kind of set can take a lot of resources (RAM and	CPU).
	   The following incomplete datetime would generate the	set of all
	   seconds in 2003:

	     2003-xx-xxTxx:xx:xx

	   Recurrences are generated with up to	1 second resolution.  The
	   "nanosecond"	value is ignored.

       o   to_spanset

	   This	method generates the set of all	possible spans that fit	into
	   an incomplete datetime definition.

	     $dti = DateTime::Incomplete->new( month =>	12, day	=> 24 );
	     $dtset1 = $dti->to_spanset;
	     # Christmas recurrence, from xxxx-12-24T00:00:00
	     #			       to xxxx-12-25T00:00:00

       o   start

       o   end

       o   to_span

	   These methods view an incomplete datetime as	a "time	span".

	   For example,	the incomplete datetime	"2003-xx-xxTxx:xx:xx" starts
	   in "2003-01-01T00:00:00" and	ends in	"2004-01-01T00:00:00".

	   The "to_span" method	returns	a "DateTime::Span" object.

	   An incomplete datetime without an year spans	"forever".  Start and
	   end datetimes are "undef".

       o   contains

	   Returns a true value	if the incomplete datetime range contains a
	   given datetime value.

	   For example:

	     2003-xx-xx	contains 2003-12-24
	     2003-xx-xx	does not contain 1999-12-14

       o   previous / next / closest

	     $dt2 = $dti->next(	$dt );

	   The "next()"	returns	the first complete date	after or equal to the
	   given datetime.

	   The "previous()" returns the	first complete date before or equal to
	   the given datetime.

	   The "closest()" returns the closest complete	date (previous or
	   next) to the	given datetime.

	   All of these	methods	return "undef" if there	is no matching
	   complete datetime.

	   If no datetime is given, these methods use the "base" datetime.

	   Note: The definition	of "previous()"	and "next()" is	different from
	   the methods of the same name	in the "DateTime::Set" class.

	   The datetimes are generated with 1 nanosecond precision. The	last
	   "time" value	of a given day is 23:59:59.999999999 (for non
	   leapsecond days).

SUPPORT
       Support for this	module is provided via the datetime@perl.org email
       list.  See http://lists.perl.org/ for more details.

AUTHORS
       Flavio S. Glock <fglock[at]cpan.org>

       With Ben	Bennett	<fiji[at]ayup.limey.net>, Claus	Farber
       <claus[at]xn--frber-gra.muc.de>,	Dave Rolsky <autarch[at]urth.org>,
       Eugene Van Der Pijll <pijll[at]gmx.net>,	Rick Measham
       <rick[at]isite.net.au>, and the DateTime	team.

COPYRIGHT
       Copyright (c) 2003 Flavio S. Glock.  All	rights reserved.  This program
       is free software; you can redistribute it and/or	modify it under	the
       same terms as Perl itself.

       The full	text of	the license can	be found in the	LICENSE	file included
       with this module.

SEE ALSO
       datetime@perl.org mailing list

       http://datetime.perl.org/

perl v5.32.1			  2015-11-10	       DateTime::Incomplete(3)

NAME | SYNOPSIS | DESCRIPTION | ERROR HANDLING | THE "BASE" DATETIME | DATETIME-LIKE METHODS | "DATETIME::INCOMPLETE" METHODS | SUPPORT | AUTHORS | COPYRIGHT | SEE ALSO

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

home | help