Name

OpenXPKI::DateTime - tools to handle various date and timestamp formats.

Description

Tools for date/time manipulation.

Functions

convert_date

Converts a DateTime object to various date formats used throughout OpenXPKI and returns the corresponding representation. Before converting the object the Time Zone is adjusted to UTC.

If OUTFORMAT is not specified the output format defaults to iso8601.

Possible output formats: iso8601: ISO 8601 formatted date (YYYY-MM-DDTHH:MM:SS), default epoch: seconds since the epoch openssltime: time format used in OpenSSL index files (YYMMDDHHMMSSZ) generalizedtime: time format used in OpenSSL index files (YYYYMMDDHHMMSSZ) terse: terse time format (YYYYMMDDHHMMSS) printable: human readable ISO-like time format (YYYY-MM-DD HH:MM:SS)

Example

    my $dt = DateTime->now();

    print OpenXPKI::DateTime::convert_date({
        DATE      => $dt,
        OUTFORMAT => 'iso8601',
    });

get_validity

Returns a DateTime object that reflects the requested validity in UTC.

Possible validity formats (specified via VALIDITYFORMAT):

'relativedate': the specified validity is interpreted as a relative terse date string. This is the default.
'absolutedate': the specified validity is interpreted as an absolute terse date string.
'days': the specified validity is interpreted as an integer number of days (positive or negative) as an offset to the reference date.
'epoch': the specified validity is a unix epoch, used as absolute date.
'detect': tries to guess what it got, relativedate if it has a sign (+/-), epoch if it has between 9 and 10 digits and absolutedate otherwise. Also consumes iso8601 formated strings. Days can not be autodetected as they look like relativedate.
'absolutedate' is only valid with eight (day only), 12 (minutes) or 14 (seconds) digits.

Reference date

If a relative validity is specified the duration is added to a reference date that defaults to the current time (UTC).

If the named parameter REFERENCEDATE is specified, this date is taken as the basis for calculating the relative date. The parameter could either contain a DateTime object or a parsable date string (i.e. '2012-05-24T08:33:47' see Date::Parse for a list of valid strings) which will be converted to an UTC DateTime object.

Terse date strings

The validity specification is passed in as the named parameter VALIDITY.

Absolute validities are specified in the format

  YYYYMMDD[HH[MM[SS]]]

Missing optional time specifications are replaced with '00'. Example:

  2006031618   is interpreted as 2006-03-16 18:00:00 UTC

Relative validities are specified as a partial terse date string in the format

  +YY[MM[DD[HH[MM[SS]]]]]   or
  -YY[MM[DD[HH[MM[SS]]]]]

Positive relative validities are interpreted as date offsets in the future as seen from reference date, negative relativie validities are interpreted as date offsets in the past.

Examples:

  -000001    (yesterday)
  +0003      (three months from now)

Usage example

  my $offset = DateTime->now( timezone => 'UTC' );
  $offset->add( months => 2 );

  my $somedate = OpenXPKI::DateTime::get_validity(
        {
        REFERENCEDATE => $offset,
        VALIDITY => '+0205',
        VALIDITYFORMAT => 'relativedate',
        },
    );
  print $somedate->datetime()

After this has been executed a date should be printed that is 2 years and 7 months in the future: the relative validity 2 years, 5 months is added to the offset which is 2 months in the future from now.

parse_date_utc

Helpermethod. Passes the given parameter $date_string to Date::Parse::strptime and constructs from the return an UTC DateTime object

is_relative

Static helper, check if a datestring looks like a relative format. (Check if the first character is a +/-).