Bric::Util::Time(3p)  User Contributed Perl Documentation Bric::Util::Time(3p)



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:

           o   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:

           o   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:

           o   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:

           o   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



perl v5.12.2                      2007-05-15              Bric::Util::Time(3p)
