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 of "expand" 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. For "base" buckets, this may include extra spare quota
               distributed in proportion to the "expand" 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 the "value" 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>