Name

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

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:

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 $format is 'object', it will return a DateTime object. 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:

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:

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:

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