Bric::Util::Time - Bricolage Time & Date Functions

$LastChangedRevision$

$LastChangedDate: 2004-08-12 17:13:34 -0700 (Thu, 12 Aug 2004) $

  use Bric::Util::Time ':all';
  my $formatted_date = strfdate($epoch_time, $format, $utc);
  my $local_date = local_date($db_date, $format);
  my $db_date = db_date($iso_local_date);

This package provides time and date formatting functions that may be imported into other Bricolage packages and classes.

To use any of the functons in Bric::Util::Time, you must explicitly import them into your module's namespace. This can be done in one of two ways: All of them can be imported at once, or they can be imported individually, one a a time:

  use Bric::Util::Time qw(:all);               # Imports them all.
  use Bric::Util::Time qw(local_date db_date); # Imports only those listed.

NONE.

NONE.

NONE.

NONE.

Returns a formatted date/time string. CW$time is the epoch time to be formatted. It will use the Time Zone preference set via Bric::App::Pref unless CW$utc is true, in which case the time will be formatted is UTC time. Use POSIX::setlocale to have the strfdate() output a localized format of CW$time - otherwise it defaults to the system's locale. CW$format is the stftime format in which CW$time should be formatted; defaults to ISO 8601-compliant time formatting (%Y-%m-%d CW%T). Throws: NONE. Side Effects: NONE. Notes:

*

Unable to format date.

local_date($db_date)

Takes a date/time string formatted for the database, converts it to the local time zone, and returns it in the strftime format provided by CW$format. If CW$format is not provided, the date/time will be returned in the format specified by the Date/Time Format preference. If CW$format is 'epoch', it will return the time in epoch seconds. Set CW$ENV{TZ} to get a different localtime. If CW$db_date is not provided and CW$bool is false, then local_date() returns undef. If CW$db_date is not provided and CW$bool is true, then local_date() returns the current date/time. Use this function in your accessors to return a localized date/time string to your object users.

  sub get_date { local_date($_[0]->_get('date'), $_[1]); }

Throws:

*

Unable to unpack date.

*

Unable to format date. Side Effects: NONE. Notes: NONE.

db_date($local_date)

Takes an ISO 8601 formatted date/time string (almost, see NOTES below) in the local time zone, converts it to UTC, and returns it in the format required by the database. If CW$local_date is not provided, it returns undef, unless CW$now is true, in which case it provides the current UTC time. If CW$tz is set db_date() uses the supplied time-zone instead of using the local time-zone. Use this function to convert a date/time string provided by your object's consumer into the format required by the database.

  sub set_date { db_date($_[1]); }

Throws:

*

Unable to unpack date.

*

Unable to format date. Side Effects: NONE. Notes: NONE.

NONE.

NONE.

NONE.

NONE.

ISO 8601 date support is incomplete. Currently, time-zone information in the date string is ignored. Also, date and time parts (CCYY, MM, DD, hh, mm and ss) must be separated by a single character.

David E. Wheeler <david@wheeler.net>

Bric, Bric::Util::DBI