NAME
Tickit::Utils
- utility functions for Tickit
DESCRIPTION
This module provides a number of utility functions used across Tickit
.
FUNCTIONS
string_count
$bytes = string_count( $str, $pos, $limit )
Given a string in $str
and a Tickit::StringPos instance in $pos
, updates the counters in $pos
by counting the string, and returns the number of bytes consumed. If $limit
is given, then it will count no further than any of the limits given.
string_countmore
$bytes = string_countmore( $str, $pos, $limit )
Similar to string_count
but will not zero the counters before it begins. Counters in $pos
will still be incremented.
textwidth
$cols = textwidth( $str )
Returns the number of screen columns consumed by the given (Unicode) string.
chars2cols
@cols = chars2cols( $text, @chars )
Given a list of increasing character positions, returns a list of column widths of those characters. In scalar context returns the first columns width.
cols2chars
@chars = cols2chars( $text, @cols )
Given a list of increasing column widths, returns a list of character positions at those widths. In scalar context returns the first character position.
substrwidth
$substr = substrwidth $text, $startcol
$substr = substrwidth $text, $startcol, $widthcols
$substr = substrwidth $text, $startcol, $widthcols, $replacement
Similar to substr
, but counts start offset and length in screen columns instead of characters
align
( $before, $alloc, $after ) = align( $value, $total, $alignment )
Returns a list of three integers created by aligning the $value
to a position within the $total
according to $alignment
. The sum of the three returned values will always add to total.
If the value is not larger than the total then the returned allocation will be the entire value, and the remaining space will be divided between before and after according to the given fractional alignment, with more of the remainder being allocated to the $after
position in proportion to the alignment.
If the value is larger than the total, then the total is returned as the allocation and the before and after positions will both be given zero.
bound
$val = bound( $min, $val, $max )
Returns the value of $val
bounded by the given minimum and maximum. Either limit may be left undefined, causing no limit of that kind to be applied.
distribute
distribute( $total, @buckets )
Given a total amount of quota, and a list of buckets, distributes the quota among the buckets according to the values given in them.
Each value in the @buckets
list is a HASH
reference which will be modified by the function. On entry, the following keys are inspected.
- base => INT
-
If present, this bucket shall be a flexible bucket containing initially this quantity of quota, but may be allocated more, or less, depending on the value of the
expand
key, and how much spare is remaining. - expand => INT
-
For a
base
flexible bucket, the relative distribution ofexpand
value among the flexible buckets determines how the spare quota is distributed among them. If absent, defaults to 0. - fixed => INT
-
If present, this bucket shall be of the exact fixed size given.
On return, the bucket hashes will be modified to contain two more keys:
- value => INT
-
The amount of quota allocated to this bucket. For
fixed
buckets, this will be the fixed value. Forbase
buckets, this may include extra spare quota distributed in proportion to theexpand
value, or may be reduced in order to fit the total. - start => INT
-
Gives the cumulative amount of quota allocated to each previous bucket. The first bucket's
start
value will be 0, the second will be thevalue
allocated to the first, and so on.
The bucket hashes will not otherwise be modified; the caller may place any extra keys in the hashes as required.
AUTHOR
Paul Evans <leonerd@leonerd.org.uk>