Bric::Util::Time(3)

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

VERSION
$LastChangedRevision$

DATE
$LastChangedDate: 2004-06-04 12:21:12 -0700 (Fri, 04 Jun 2004) $

SYNOPSIS
  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);

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

INTERFACE
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.

  Constructors
NONE.

  Destructors
NONE.

  Public Class Methods
NONE.

  Public Instance Methods
NONE.

  Functions

strfdate([$time[, $format[, $utc]]])
    Returns a formatted date/time string. $time is the epoch time to be formatted. It will use the Time Zone preference set via Bric::App::Pref unless $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 $time - otherwise it defaults to the system's locale. $format is the stftime format in which $time should be formatted; defaults to ISO 8601-compliant time formatting ("%Y-%m-%d %T").

    Throws: NONE.

    Side Effects: NONE.

    Notes:

    *   Unable to format date.

local_date($db_date)
local_date($db_date, $format)
local_date(undef, undef, $bool)
local_date(undef, $format, $bool)
    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 $format. If $format is not provided, the date/time will be returned in the format specified by the Date/Time Format preference. If $format is 'epoch', it will return the time in epoch seconds. Set $ENV{TZ} to get a different localtime. If $db_date is not provided and $bool is false, then local_date() returns undef. If $db_date is not provided and $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)
db_date($local_date, $now)
db_date($local_date, undef, $tz)
    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 $local_date is not provided, it returns undef, unless $now is true, in which case it provides the current UTC time. If $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.

PRIVATE
NONE.

  Private Class Methods
NONE.

  Private Instance Methods
NONE.

  Private Functions
NONE.

NOTES
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.

AUTHOR
David E. Wheeler <david@wheeler.net>

SEE ALSO
Bric, Bric::Util::DBI