.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Tickit::Utils 3pm"
.TH Tickit::Utils 3pm "2018-11-01" "perl v5.28.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
"Tickit::Utils" \- utility functions for "Tickit"
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module provides a number of utility functions used across \f(CW\*(C`Tickit\*(C'\fR.
.SH "FUNCTIONS"
.IX Header "FUNCTIONS"
.SS "string_count"
.IX Subsection "string_count"
.Vb 1
\&   $bytes = string_count( $str, $pos, $limit )
.Ve
.PP
Given a string in \f(CW$str\fR and a Tickit::StringPos instance in \f(CW$pos\fR,
updates the counters in \f(CW$pos\fR by counting the string, and returns the number
of bytes consumed. If \f(CW$limit\fR is given, then it will count no further than
any of the limits given.
.SS "string_countmore"
.IX Subsection "string_countmore"
.Vb 1
\&   $bytes = string_countmore( $str, $pos, $limit )
.Ve
.PP
Similar to \f(CW\*(C`string_count\*(C'\fR but will not zero the counters before it begins.
Counters in \f(CW$pos\fR will still be incremented.
.SS "textwidth"
.IX Subsection "textwidth"
.Vb 1
\&   $cols = textwidth( $str )
.Ve
.PP
Returns the number of screen columns consumed by the given (Unicode) string.
.SS "chars2cols"
.IX Subsection "chars2cols"
.Vb 1
\&   @cols = chars2cols( $text, @chars )
.Ve
.PP
Given a list of increasing character positions, returns a list of column
widths of those characters. In scalar context returns the first columns width.
.SS "cols2chars"
.IX Subsection "cols2chars"
.Vb 1
\&   @chars = cols2chars( $text, @cols )
.Ve
.PP
Given a list of increasing column widths, returns a list of character
positions at those widths. In scalar context returns the first character
position.
.SS "substrwidth"
.IX Subsection "substrwidth"
.Vb 1
\&   $substr = substrwidth $text, $startcol
\&
\&   $substr = substrwidth $text, $startcol, $widthcols
\&
\&   $substr = substrwidth $text, $startcol, $widthcols, $replacement
.Ve
.PP
Similar to \f(CW\*(C`substr\*(C'\fR, but counts start offset and length in screen columns
instead of characters
.SS "align"
.IX Subsection "align"
.Vb 1
\&   ( $before, $alloc, $after ) = align( $value, $total, $alignment )
.Ve
.PP
Returns a list of three integers created by aligning the \f(CW$value\fR to a
position within the \f(CW$total\fR according to \f(CW$alignment\fR. The sum of the three
returned values will always add to total.
.PP
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 \f(CW$after\fR position in proportion to the alignment.
.PP
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.
.SS "bound"
.IX Subsection "bound"
.Vb 1
\&   $val = bound( $min, $val, $max )
.Ve
.PP
Returns the value of \f(CW$val\fR bounded by the given minimum and maximum. Either
limit may be left undefined, causing no limit of that kind to be applied.
.SS "distribute"
.IX Subsection "distribute"
.Vb 1
\&   distribute( $total, @buckets )
.Ve
.PP
Given a total amount of quota, and a list of buckets, distributes the quota
among the buckets according to the values given in them.
.PP
Each value in the \f(CW@buckets\fR list is a \f(CW\*(C`HASH\*(C'\fR reference which will be
modified by the function. On entry, the following keys are inspected.
.IP "base => \s-1INT\s0" 8
.IX Item "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 \f(CW\*(C`expand\*(C'\fR key, and how much spare is remaining.
.IP "expand => \s-1INT\s0" 8
.IX Item "expand => INT"
For a \f(CW\*(C`base\*(C'\fR flexible bucket, the relative distribution of \f(CW\*(C`expand\*(C'\fR value
among the flexible buckets determines how the spare quota is distributed among
them. If absent, defaults to 0.
.IP "fixed => \s-1INT\s0" 8
.IX Item "fixed => INT"
If present, this bucket shall be of the exact fixed size given.
.PP
On return, the bucket hashes will be modified to contain two more keys:
.IP "value => \s-1INT\s0" 8
.IX Item "value => INT"
The amount of quota allocated to this bucket. For \f(CW\*(C`fixed\*(C'\fR buckets, this will
be the fixed value. For \f(CW\*(C`base\*(C'\fR buckets, this may include extra spare quota
distributed in proportion to the \f(CW\*(C`expand\*(C'\fR value, or may be reduced in order
to fit the total.
.IP "start => \s-1INT\s0" 8
.IX Item "start => INT"
Gives the cumulative amount of quota allocated to each previous bucket. The
first bucket's \f(CW\*(C`start\*(C'\fR value will be 0, the second will be the \f(CW\*(C`value\*(C'\fR
allocated to the first, and so on.
.PP
The bucket hashes will not otherwise be modified; the caller may place any
extra keys in the hashes as required.
.SH "AUTHOR"
.IX Header "AUTHOR"
Paul Evans <leonerd@leonerd.org.uk>