Bric::Util::Time(3)

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

VERSION
$LastChangedRevision$

DATE
$LastChangedDate: 2007-05-15 14:06:24 +0200 (Tue, 15 May 2007) $

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);
  my $dt = datetime($iso_format_date, $tz);

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.

  Constants
These constants define values that can be used comparatively to determine which are the more precise time parts. The higher the value, the more precise the time part.

YEAR
MONTH
DAY
HOUR
MINUTE
SECOND
MILLISECOND
MICROSECOND

PRECISIONS

This constant contains an array reference of array references with strings corresponding to the numeric value of each time part. This constant is suitable for passing to a select list for display.

  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 in UTC time. Use "DateTime->DefaultLocale()" to have the "strfdate()" output a localized format of $time--otherwise it defaults to the "English" locale. $format is the stftime format in which $time should be formatted; defaults to ISO 8601-compliant time formatting ("%Y-%m-%d %T.%6N").

    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 time zone set in the "Time Zone" preference, and returns it in the "strftime" format provided by $format. If $format is not provided, the date/time will be returned in the format set in the "Date/Time Format" preference. If $format is 'epoch', it will return the time in epoch seconds. 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 Bricolage accessor methods to return a localized date/time string.

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

    Throws:

    *   Unable to parse 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 in the time zone set in the "Time Zone" preference, 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, then "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 parse date.

    Side Effects: NONE.

    Notes: NONE.

datetime($iso_formatted_date)
datetime($iso_formatted_date, $tz)
    Takes an ISO 8601 formatted date/time string and returns a DateTime object. The timze zone set on the DateTime object will be either the value of $tz or the value set in the "Time Zone" preference.

    Throws:

    *   Unable to parse 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@justatheory.com>

SEE ALSO
Bric, Bric::Util::DBI