Name

Object::Relation::DataType::Duration - Object::Relation Duration objects

Synopsis

  my $dt = Object::Relation::DataType::Duration->new(
    years   => 2,
    months  => 10,
    days    => 16,
    hours   => 16,
    minutes => 12,
    seconds => 47,
  );

Description

This module creates the "duration" data type for use in Object::Relation attributes. It subclasses the DateTime::Duration module to offer duration objects to Object::Relation applications. It differs from DateTime::Duration in overloading the comparison operators == and eq and in providing raw() and bake() methods for serialization and deserialization to the data store.

A note about the comparison overloading: It uses the compare() method inherited from DateTime::Duration and calculates the differences against a DateTime object for the current Date and time. Thus, the caveats the apply to comare() apply also to the overloaded comparison functionality of this module.

Class Interface

Constructors

bake

  my $duration = Object::Relation::DataType::Duration->bake($string);

Parses an ISO-8601 Duration or PostgreSQL-formatted INTERVAL string and returns a Object::Relation::DataType::Duration object.

Instance Interface

raw

  my $iso_duration = $duration->raw;

Returns an ISO-8601-compliant duration string. This string takes the form "PnYnMnDTnHnMnS". For example, "P3Y6M4DT12H30M0S" defines "a period of three years, six months, four days, twelve hours, thirty minutes, and zero seconds". See http://en.wikipedia.org/wiki/ISO_8601#Duration for details and links to the ISO-8601 spec.

The values of the duration parts will be normalized. For example, if a new duration object is created with the minutes parameter set to "90", the raw representation will contain 1 hour and 30 minutes, instead.

store_raw

  my $store_duration = $duration->store_raw($store);

Returns a duration string suitable for storage in the data store. The string returned depends on the data store class. For the PostgreSQL store, the string will be returned in a PostgreSQL-standard INTERVAL string representation of the duration object.

For other data stores, it will be stored in an non-standard ISO-8601 duration string format with zero-padded parts. The number of years is padded to five places, so no durations greater than 99,999 years or less than -9,999 years are allowed for the non-PostgreSQL data stores.

  raw                Other                     PostgreSQL
  P0Y0M0DT1H0M0S     P00000Y00M00DT01H00M00S   0 years 0 mons 0 days 1 hours 0 mins 0 secs
  P0Y0M0DT-8H0M0S    P00000Y00M00DT-8H00M00S   0 years 0 mons 0 days 1 hours 0 mins 0.299 secs
  P9Y1M-12DT13H14M0S P00009Y01M-12DT13H14M00S  9 years 1 mons -12 days 13 hours 14 mins 0 secs

The reason for the special padded version of the ISO-8601 duration string is to allow data stores without a duration or interval data type to do proper string-based comparisons.

As with raw(), The values of the duration parts will be normalized.