Persistent::DataType::DateTime - A Date and Time Class

Constructor - Create a New DateTime Object
value - Accesses the Value of the Date
get_compare_op - Returns the Comparison Operator for DateTime
year - Accesses the Year of the Date
month - Accesses the Month of the Date
day - Accesses the Day of the Date
hours - Accesses the Hours of the Date
minutes - Accesses the Minutes of the Date
seconds - Accesses the Seconds of the Date

SEE ALSO
BUGS
AUTHORS
COPYRIGHT

NAME

Persistent::DataType::DateTime - A Date and Time Class

SYNOPSIS

  use Persistent::DataType::DateTime;
  use English;

  eval {  ### in case an exception is thrown ###

    ### allocate a date ###
    my $date = new Persistent::DataType::DateTime(localtime);

    ### get/set value of date ###
    $value = $date->value($year, $month, $day,
                          $hours, $minutes, $seconds);

    ### get/set year of the date ###
    $year = $date->year($new_year);

    ### get/set month of the date ###
    $month = $date->month($new_month);

    ### get/set day of the date ###
    $day = $date->day($new_day);

    ### get/set hours of the date ###
    $hours = $date->hours($new_hours);

    ### get/set minutes of the date ###
    $minutes = $date->minutes($new_minutes);

    ### get/set seconds of the date ###
    $seconds = $date->seconds($new_seconds);

    ### returns 'cmp' for dates ###
    my $cmp_op = $date->get_compare_op();
  };

  if ($EVAL_ERROR) {  ### catch those exceptions! ###
    print "An error occurred: $EVAL_ERROR\n";
  }

ABSTRACT

This is a date and time class used by the Persistent framework of classes to implement the attributes of objects. This class provides methods for accessing a date in a variety of formats.

This class is usually not invoked directly, at least not when used with the Persistent framework of classes. However, the constructor arguments of this class are usually of interest when defining the attributes of a Persistent object since the add_attribute method of the Persistent classes instantiates this class directly. Also, the arguments to the value method are of interest when dealing with the accessor methods of the Persistent classes since the accessor methods pass their arguments to the value method and return the string value from the value method.

This class is part of the Persistent base package which is available from:

  http://www.bigsnow.org/persistent
  ftp://ftp.bigsnow.org/pub/persistent

DESCRIPTION

Before we get started describing the methods in detail, it should be noted that all error handling in this class is done with exceptions. So you should wrap an eval block around all of your code. Please see the the Persistent manpage documentation for more information on exception handling in Perl.

METHODS

Constructor -- Create a New DateTime Object

  use Persistent::DataType::DateTime;

  eval {
    $date = new Persistent::DataType::DateTime($datestring);
    $date = new Persistent::DataType::DateTime('now');
    $date = new Persistent::DataType::DateTime('');
    $date = new Persistent::DataType::DateTime(undef);
    $date = new Persistent::DataType::DateTime($year, $month, $day,
                                               $hour, $min, $sec);
    $date = new Persistent::DataType::DateTime(localtime);
  };
  croak "Exception caught: $@" if $@;

Initializes a DateTime object. This method throws Perl execeptions so use it with an eval block.

This constructor accepts several forms of arguments:

$datestring

If the sole argument is a string, it is assumed to contain the date and time in the following format:

  YYYY-MM-DD hh:mm:ss
           or
  YYYY/MM/DD hh:mm:ss

This is also the format that is returned by the value method of this object.

Another valid format to pass is the following:

  DD-Mon-YYYY

where Mon is the three letter abbreviation for the month. The case of the letters is not sensitive (i.e. jan or Jan or JAN is alright).

'now'

If the sole argument is the word 'now', then the current date and time are used.

undef or the empty string ('')

If the sole argument is undef or the empty string (''), then the date and time are set to undef.

$year, $month, $day, $hour, $min, $sec

If more than one argument is given (and less than 7), it is assumed that the date and time are being given as a series of integers in the above order where their formats are the following:

  $year = 0 .. 9999  ### 4 digit year ###
  $month = 1 .. 12
  $day = 1 .. 31
  $hours = 0 .. 23
  $minutes = 0 .. 59
  $seconds = 0 .. 59

$sec, $min, $hour, $mday, $mon, $year, $wday, $yday, $isdst

If more than six arguments are passed, it is assumed that the date and time are being given as a series of integers in the above order, which happens to be the same order as the array that the Perl built-ins, localtime and gmtime, return. See the perlfunc manpage for more information.

value -- Accesses the Value of the Date

  eval {
    $date_string = $date->value($datestring);
    $date_string = $date->value('now');
    $date_string = $date->value('');
    $date_string = $date->value(undef);
    $date_string = $date->value($year, $month, $day,
                                $hour, $min, $sec);
    $date_string = $date->value(localtime);
  };
  croak "Exception caught: $@" if $@;

Returns (and optionally sets) the value of the DateTime object. This method throws Perl execeptions so use it with an eval block.

The arguments are as described above in Constructor -- Create a New DateTime Object.

get_compare_op -- Returns the Comparison Operator for DateTime

  $cmp_op = $date->get_compare_op();

Returns the comparison operator for the DateTime class which is 'cmp'. This method does not throw execeptions.

Parameters:

None

year -- Accesses the Year of the Date

  eval {
    ### set the year ###
    $date->year($new_year);

    ### get the year ###
    $year = $date->year();
  };
  croak "Exception caught: $@" if $@;

Returns (and optionally sets) the year of the DateTime object. This method throws Perl execeptions so use it with an eval block.

Parameters:

$year: A 4-digit year. The year must be >= 0 and <= 9999. If it is undef then the year will be set to undef.

month -- Accesses the Month of the Date

  eval {
    ### set the month ###
    $date->month($new_month);

    ### get the month ###
    $month = $date->month();
  };
  croak "Exception caught: $@" if $@;

Returns (and optionally sets) the month of the DateTime object. This method throws Perl execeptions so use it with an eval block.

Parameters:

$month: The month must be >= 1 and <= 12. If it is undef then the month will be set to undef.

day -- Accesses the Day of the Date

  eval {
    ### set the day ###
    $date->day($new_day);

    ### get the day ###
    $day = $date->day();
  };
  croak "Exception caught: $@" if $@;

Returns (and optionally sets) the day of the DateTime object. This method throws Perl execeptions so use it with an eval block.

Parameters:

$day: The day must be >= 1 and <= 31. If it is undef then the day will be set to undef.

hours -- Accesses the Hours of the Date

  eval {
    ### set the hours ###
    $date->hours($new_hours);

    ### get the hours ###
    $hours = $date->hours();
  };
  croak "Exception caught: $@" if $@;

Returns (and optionally sets) the hours of the DateTime object. This method throws Perl execeptions so use it with an eval block.

Parameters:

$hours: The hours must be >= 0 and <= 23. If it is undef then the hours will be set to undef.

minutes -- Accesses the Minutes of the Date

  eval {
    ### set the minutes ###
    $date->minutes($new_minutes);

    ### get the minutes ###
    $minutes = $date->minutes();
  };
  croak "Exception caught: $@" if $@;

Returns (and optionally sets) the minutes of the DateTime object. This method throws Perl execeptions so use it with an eval block.

Parameters:

$minutes: The minutes must be >= 1 and <= 59. If it is undef then the minutes will be set to undef.

seconds -- Accesses the Seconds of the Date

  eval {
    ### set the seconds ###
    $date->seconds($new_seconds);

    ### get the seconds ###
    $seconds = $date->seconds();
  };
  croak "Exception caught: $@" if $@;

Returns (and optionally sets) the seconds of the DateTime object. This method throws Perl execeptions so use it with an eval block.

Parameters:

$seconds: The seconds must be >= 0 and <= 59. If it is undef then the seconds will be set to undef.

BUGS

This software is definitely a work in progress. So if you find any bugs please email them to me with a subject of 'Persistent Bug' at:

  winters@bigsnow.org

And you know, include the regular stuff, OS, Perl version, snippet of code, etc.

AUTHORS

  David Winters <winters@bigsnow.org>

COPYRIGHT

Persistent::DataType::DateTime - A Date and Time Class