/ 
Time-Str-0.87
/ Time::Str::Util

NAME

Time::Str::Util - Binary search and time zone database utilities

SYNOPSIS

use Time::Str::Util qw( find_tzdb_directory
                        lower_bound upper_bound range_bounds );

# Locate system zoneinfo directory
my $tzdir = find_tzdb_directory();  # /usr/share/zoneinfo or undef

my @sorted = (10, 20, 30, 40, 50);

my $i = lower_bound(\@sorted, 25);  # 2 (first element >= 25)
my $j = upper_bound(\@sorted, 30);  # 3 (first element >  30)

# With optional bounds
my $k = lower_bound(\@sorted, 25, 1, 4);  # search within [1, 4)

# Range query: indices of elements in [15, 35]
my ($lo, $hi) = range_bounds(\@sorted, 15, 35);  # (1, 3)

DESCRIPTION

This module provides binary search functions for sorted integer arrays and utilities for locating the system's IANA Time Zone Database. All functions are exportable on request. Use :all to import everything.

FUNCTIONS

lower_bound

my $index = lower_bound($arrayref, $value);
my $index = lower_bound($arrayref, $value, $lo, $hi);

Returns the index of the first element in the sorted array that is greater than or equal to $value. If all elements are less than $value, returns the length of the array (one past the last index).

Optional $lo and $hi parameters restrict the search to the half-open range [$lo, $hi). Defaults to [0, length).

range_bounds

my ($lo, $hi) = range_bounds($arrayref, $min_value, $max_value);

Returns a pair of indices ($lo, $hi) defining the half-open range [$lo, $hi) of elements within [$min_value, $max_value]. $lo is the index of the first element >= $min_value (via binary search), and $hi is the index of the first element > $max_value (via linear scan from $lo).

This is optimized for cases where few elements fall within the range, as the linear scan avoids a second binary search.

Croaks if $min_value > $max_value.

upper_bound

my $index = upper_bound($arrayref, $value);
my $index = upper_bound($arrayref, $value, $lo, $hi);

Returns the index of the first element in the sorted array that is strictly greater than $value. If all elements are less than or equal to $value, returns the length of the array.

Optional $lo and $hi parameters restrict the search to the half-open range [$lo, $hi). Defaults to [0, length).

Time Zone Database

find_tzdb_directory

my $dir = find_tzdb_directory();

Returns the path to the system's IANA Time Zone Database directory (zoneinfo), or undef if no valid directory is found.

The search order is:

1. $ENV{TZDIR} if set and the directory exists.
2. Well-known paths: /usr/share/zoneinfo, /usr/lib/zoneinfo, /usr/share/lib/zoneinfo, /etc/zoneinfo, /usr/share/zoneinfo.default.

A candidate directory is accepted only if it exists and contains a UTC file.

SEE ALSO

Time::Str

AUTHOR

Christian Hansen

COPYRIGHT AND LICENSE

Copyright (C) 2026 by Christian Hansen

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.