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.