NAME
Database::BI::Util - Shared utility functions for Database::BI modules
SYNOPSIS
use Database::BI::Util qw(urlencode);
my $safe = urlencode($query_param_value);
DESCRIPTION
Small helpers shared by the plain-Perl modules (Database::BI::Ask, Database::BI::Insights) that build URLs without depending on Mojolicious. Nothing is exported by default.
FUNCTIONS
urlencode
my $encoded = urlencode($str);
Percent-encodes a string for use as a URI query-parameter value. Preserves the RFC 3986 unreserved characters (A-Z a-z 0-9 - . _ ~) and replaces all other bytes with %XX uppercase hex escapes. A decoded string is encoded as UTF-8 first; a string of bytes is taken as it stands.
API SPECIFICATION
INPUT
$str # string or undef
OUTPUT
'string' # percent-encoded; undef gives ''
Each character outside the unreserved set is encoded from its code point, so a character above 0xFF must be encoded to UTF-8 bytes first (Encode::encode_utf8). The application only passes ASCII column names and specs.
parse_number
Read a table cell as a number, or say it is not one.
parse_number('$1,234.56'); # 1234.56
parse_number('(1,234.56)'); # -1234.56
parse_number('USD 100'); # 100
parse_number('SKU123'); # undef
API SPECIFICATION
INPUT
$value: string, optional
OUTPUT
A number, or undef if the value is missing, empty, holds anything other than a number and its currency or thousands formatting, or lies beyond the range of a C double (POSIX::DBL_MAX, about 1.8e308) -- the browser's numbers -- whatever kind of number this perl was built with.
iso_datetime
Read an ISO 8601 date or timestamp.
iso_datetime('2026-11-06'); # ('2026-11-06', undef, undef, undef)
iso_datetime('2026-11-06 09:15'); # ('2026-11-06', '09', '15', undef)
iso_datetime('2026-11-06T23:30:00.250Z'); # ('2026-11-06', '23', '30', '00')
iso_datetime('2026-11-06T23:30:00+01:00'); # ('2026-11-06', '23', '30', '00')
iso_datetime('06/11/2026'); # ()
The time is the one written in the value: a fraction of a second and a zone (Z, +01:00, +0100, +01) are accepted and not applied, so a timestamp falls on the day it names, the one the table shows. The month and day are not checked against a calendar; the callers that need a real day check it themselves.
API SPECIFICATION
INPUT
$value: string, optional
OUTPUT
A list: the day (YYYY-MM-DD), then the hour, minute and second as written (two digits each, undef when absent), or the empty list when the value is not an ISO date or timestamp.
minute_stamp
A time to the minute, from the list localtime or gmtime gives.
minute_stamp(localtime $mtime); # '2026-11-07 14:05'
minute_stamp(gmtime $mtime) . ' UTC';
It is POSIX::strftime('%Y-%m-%d %H:%M', ...) written out: on Windows, perl 5.38's strftime did not return.
API SPECIFICATION
INPUT
@tm: the list from localtime or gmtime (at least six values)
OUTPUT
A string, YYYY-MM-DD HH:MM; the empty string when fewer than six values are given.
iso8601_utc
A moment as ISO 8601 in UTC, to the second.
iso8601_utc(); # now, '2026-11-07T14:05:09Z'
iso8601_utc(0); # '1970-01-01T00:00:00Z'
API SPECIFICATION
INPUT
$epoch: integer, optional (default: now)
OUTPUT
A string, YYYY-MM-DDTHH:MM:SSZ.
AUTHOR
Nigel Horne <njh@nigelhorne.com>
LICENCE AND COPYRIGHT
Copyright 2026 Nigel Horne.
Usage is subject to the GPL2 licence terms.