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

FreeBSD Manual Pages

  
 
  

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

NAME
       Badger::Date - simple object representation of a	date

SYNOPSIS
	   use Badger::Date;

	   # date defaults to today to date/time now
	   my $date = Badger::Date->new();
	   my $date = Badger::Date->today();

	   # or	from ISO-8601 date (or similar)
	   my $stamp = Badger::Date->new('2015-03-19');

	   # or	from individual	arguments
	   my $date = Badger::Date->new(
	       year    => 2015,
	       month   => 3,
	       day     => 19
	   );

DESCRIPTION
       This module implements a	small and simple object	for representing a
       date.  Its scope	is intentionally limited to the	kind of	applications
       that require very basic date functionality with minimal overhead.

       For any non-trivial date	manipulation you should	almost certainly be
       using the most excellent	DateTime modules instead.

       This code is derived from Badger::Timestamp.

EXPORTABLE SUBROUTINES
   DATE
       This is a shortcut aliases to "Badger::Date".

	   use Badger::Date 'DATE';

	   my $date = DATE->new();	   # same as Badger::Date->new();

   Date()
       This subroutine returns the name	of the "Badger::Date" class when
       called without arguments. Thus it can be	used as	an alias for
       "Badger::Date" as per DATE.

	   use Badger::Date 'Date';

	   my $ts = Date->new();  # same as Badger::Date->new();

       When called with	arguments, it creates a	new "Badger::Date" object.

	   my $ts = Date($date);  # same as Badger::Date->new($date);

   Today()
       Returns a "Badger::Date"	for the	current	date.

METHODS
   new('YYYY-MM-DD')
       Constructor method to create a new "Badger::Date" object	from a date
       string or seconds since the epoch.

       The date	should contain 4 digits	for the	year and two for each of the
       month and day separated by any non-numerical characters.

	   # examples of valid formats
	   my $date = Badger::Date->new('2015-03-19');
	   my $date = Badger::Date->new('2015/03/19');

       The "Badger::Date" module converts these	to the canonical form of
       "YYYY-MM-DD"

	   my $date = Badger::Date->new('2015/03/19');
	   print $date;	      #	2015-03-19

       You can also construct a	"Badger::Date" object by specifying the	number
       of seconds since	the epoch.  This is the	value return by	system
       functions like "time()" and used	for file creation/modification times.

	   my $stamp = Badger::Date->new(time());

       Or can can pass it an existing "Badger::Date" object.

	   my $stamp2 =	Badger::Date->new($stamp);

       If you don't specify any	argument then you get the current system time
       as returned by "time()".

	   my $now = Badger::Date->new;

   today()
       Returns a "Badger::Date"	object representing the	current	date.

   copy()
       Returns a new "Badger::Date" object creates as a	copy of	the current
       one.

	   my $copy = $date->copy;

       This can	be useful for making adjustments to a date without affecting
       the original object.

	   my $later = $date->copy->adjust( months => 3	);

   date()
       Returns the complete date in canonical form.

	   print $date->date();	 # 2015-03-19

       This method is called automatically whenever the	object is used as a
       string value.

	   print $date;		      #	2015-03-19

   format($format)
       Returns a formatted version of the timestamp, generated using the POSIX
       strftime	function.

	   print $date->format('%d-%b-%y');

   year() / years()
       Returns the year.

	   print $date->year();	      #	2015

       Can also	be called with an argument to change the year.

	   $date->year(2016);

   month() / months()
       Returns the month.

	   print $date->month();      #	03

       Can also	be called with an argument to change the yonth.

	   $date->month(04);

   day() / days()
       Returns the day.

	   print $date->day();	      #	19

       Can also	be called with an argument to change the day.

	   $date->day(20);

   days_in_month()
       Returns the number of days in the current month.	 Accounts correctly
       for leap	years.

   leap_year()
       Returns a true value (1)	if the year is a leap year, a false value (0)
       if not.

   epoch_time()
       Returns the timestamp object as the number of seconds since the epoch
       time.

   compare($when)
       This method is used to chronologically compare two dates	to determine
       if one is earlier, later, or exactly equal to another.

       The method can be passed	another	"Badger::Date" object to compare
       against or an argument or arguments from	which a	"Badger::Date" object
       can be constructed. If no arguments are passed then it defaults to a
       comparison against the current time.

	   my $date    = Badger::Date->new('2015-01-10');
	   my $compare = Badger::Date->new('2015-03-19');

	   $date->before($compare);	      #	date object
	   $date->before('2015-03-19');	      #	literal	date
	   $date->before($epoch_seconds);     #	epoch seconds, e.g. from file time
	   $date->before;		      #	before now

       The method returns -1 if	the date object	represents a date before the
       date passed as an argument, 1 if	it's after, or 0 if it's equal.

   equal($when)
       This is a method	of convenience which uses compare() to test if two
       timestamps are equal.  You can pass it any of the arguments accepted by
       the compare() method.

	   if ($date1->equal($date2)) {
	       print "both dates are equal\n";
	   }

       This method is overloaded onto the "==" operator, allowing you to
       perform more natural comparisons.

	   if ($date1 == $date2) {
	       print "both date	are equal\n";
	   }

   before($when)
       This is a method	of convenience which uses compare() to test if one
       date occurs before another.  It returns a true value (1)	if the first
       timestamp (the object) is before	the second (the	argument), or a	false
       value (0) otherwise.

	   if ($date1->before($date2)) {
	       print "$date1 is	before $date2\n";
	   }

       This method is overloaded onto the "<" operator.

	   if ($date1 <	$date2)	{
	       print "$date1 is	before $date2\n";
	   }

   after($when)
       This is a method	of convenience which uses compare() to test if one
       date occurs after another.  It returns a	true value (1) if the first
       date (the object) is after the second (the argument), or	a false	value
       (0) otherwise.

	   if ($date1->after($date2)) {
	       print "$date1 is	after $date2\n";
	   }

       This method is overloaded onto the ">" operator.

	   if ($date1 >	$date2)	{
	       print "$date1 is	after $date2\n";
	   }

   not_equal($when)
       This is an alias	to the compare() method.  It returns a true value (-1
       or +1, both of which Perl considers to be true values) if the dates are
       not equal or false value	(0) if they are.

	   if ($date1->not_equal($date2)) {
	       print "$date1 is	not equal to $date2\n";
	   }

       This method is overloaded onto the "!=" operator.

	   if ($date1 != $date2) {
	       print "$date1 is	not equal to $date2\n";
	   }

   not_before($when)
       This is a method	of convenience which uses compare() to test if one
       date does not occur before another. It returns a	true value (1) if the
       first date (the object) is equal	to or after the	second (the argument),
       or a false value	(0) otherwise.

	   if ($date1->not_before($date2)) {
	       print "$date1 is	not before $date2\n";
	   }

       This method is overloaded onto the ">=" operator.

	   if ($date1 >= $date2) {
	       print "$date1 is	not before $date2\n";
	   }

   not_after($when)
       This is a method	of convenience which uses compare() to test if one
       date does not occur after another. It returns a true value (1) if the
       first date (the object) is equal	to or before the second	(the
       argument), or a false value (0) otherwise.

	   if ($date1->not_after($date2)) {
	       print "$date1 is	not after $date2\n";
	   }

       This method is overloaded onto the "<=" operator.

	   if ($date1 <= $date2) {
	       print "$date1 is	not after $date2\n";
	   }

   adjust(%adjustments)
       Method to adjust	the date by a fixed amount or amounts.

	   # positive adjustment
	   $date->adjust( months => 6, years =>	1 );

	   # negative adjustment
	   $date->adjust( months => -18	);

       Named parameters	can be passed as arguments or via a hash reference.

	   $date->adjust(  months => -18  );	    # naked
	   $date->adjust({ months => -18 });	    # clothed

       You can specify units using singular (day, month, year) or plural
       (days, months, years) keys. The method will correctly handle values
       outside the usual ranges. For example, you can specify a	change of 18
       months, -2000 days, and so on.

       A single	non-reference argument is assumed to be	a duration which is
       converted to a number of	seconds	via the	duration() method.

   duration($duration)
       Returns the number of seconds in	a duration. A single numerical
       argument	is assumed to be a number of seconds and is returned
       unchanged.

	   $date->adjust(300);	   # 300 seconds

       A single	non-numerical argument should have a suffix indicating the
       units.  In "compact form" this is a single letter.  We use lower	case
       "m" for minutes and upper case "M" for months.

	   $date->adjust("2d");	   # or	"2 days"
	   $date->adjust("6M");	   # or	"6 months"
	   $date->adjust("5y");	   # or	"5 years"

       Alternately you can spell the units out in full as shown	in the right
       column above.  However, we only look at the first character of the
       following word so you can write all sorts of nonsense which we will
       dutifully accept	without	complaint.

	   $date->adjust("5 Monkeys"); # 5 months
	   $date->adjust("9 doobies"); # 9 days
	   $date->adjust("3 yaks");    # 3 years

       For the sake of convenience, the	method will automatically convert the
       word "month" into "Month" so that the first letter is correctly
       capitalised.

AUTHOR
       Andy Wardley <http://wardley.org>

COPYRIGHT
       Copyright (C) 2001-2015 Andy Wardley.  All Rights Reserved.

       This module is free software; you can redistribute it and/or modify it
       under the same terms as Perl itself.

perl v5.32.1			  2016-12-12		       Badger::Date(3)

NAME | SYNOPSIS | DESCRIPTION | EXPORTABLE SUBROUTINES | METHODS | AUTHOR | COPYRIGHT

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

home | help