1Tickit::Utils(3)      User Contributed Perl Documentation     Tickit::Utils(3)
2
3
4

NAME

6       "Tickit::Utils" - utility functions for "Tickit"
7

DESCRIPTION

9       This module provides a number of utility functions used across
10       "Tickit".
11

FUNCTIONS

13   string_count
14          $bytes = string_count( $str, $pos, $limit )
15
16       Given a string in $str and a Tickit::StringPos instance in $pos,
17       updates the counters in $pos by counting the string, and returns the
18       number of bytes consumed. If $limit is given, then it will count no
19       further than any of the limits given.
20
21   string_countmore
22          $bytes = string_countmore( $str, $pos, $limit )
23
24       Similar to "string_count" but will not zero the counters before it
25       begins.  Counters in $pos will still be incremented.
26
27   textwidth
28          $cols = textwidth( $str )
29
30       Returns the number of screen columns consumed by the given (Unicode)
31       string.
32
33   chars2cols
34          @cols = chars2cols( $text, @chars )
35
36       Given a list of increasing character positions, returns a list of
37       column widths of those characters. In scalar context returns the first
38       columns width.
39
40   cols2chars
41          @chars = cols2chars( $text, @cols )
42
43       Given a list of increasing column widths, returns a list of character
44       positions at those widths. In scalar context returns the first
45       character position.
46
47   substrwidth
48          $substr = substrwidth $text, $startcol
49
50          $substr = substrwidth $text, $startcol, $widthcols
51
52          $substr = substrwidth $text, $startcol, $widthcols, $replacement
53
54       Similar to "substr", but counts start offset and length in screen
55       columns instead of characters
56
57   align
58          ( $before, $alloc, $after ) = align( $value, $total, $alignment )
59
60       Returns a list of three integers created by aligning the $value to a
61       position within the $total according to $alignment. The sum of the
62       three returned values will always add to total.
63
64       If the value is not larger than the total then the returned allocation
65       will be the entire value, and the remaining space will be divided
66       between before and after according to the given fractional alignment,
67       with more of the remainder being allocated to the $after position in
68       proportion to the alignment.
69
70       If the value is larger than the total, then the total is returned as
71       the allocation and the before and after positions will both be given
72       zero.
73
74   bound
75          $val = bound( $min, $val, $max )
76
77       Returns the value of $val bounded by the given minimum and maximum.
78       Either limit may be left undefined, causing no limit of that kind to be
79       applied.
80
81   distribute
82          distribute( $total, @buckets )
83
84       Given a total amount of quota, and a list of buckets, distributes the
85       quota among the buckets according to the values given in them.
86
87       Each value in the @buckets list is a "HASH" reference which will be
88       modified by the function. On entry, the following keys are inspected.
89
90       base => INT
91               If present, this bucket shall be a flexible bucket containing
92               initially this quantity of quota, but may be allocated more, or
93               less, depending on the value of the "expand" key, and how much
94               spare is remaining.
95
96       expand => INT
97               For a "base" flexible bucket, the relative distribution of
98               "expand" value among the flexible buckets determines how the
99               spare quota is distributed among them. If absent, defaults to
100               0.
101
102       fixed => INT
103               If present, this bucket shall be of the exact fixed size given.
104
105       On return, the bucket hashes will be modified to contain two more keys:
106
107       value => INT
108               The amount of quota allocated to this bucket. For "fixed"
109               buckets, this will be the fixed value. For "base" buckets, this
110               may include extra spare quota distributed in proportion to the
111               "expand" value, or may be reduced in order to fit the total.
112
113       start => INT
114               Gives the cumulative amount of quota allocated to each previous
115               bucket. The first bucket's "start" value will be 0, the second
116               will be the "value" allocated to the first, and so on.
117
118       The bucket hashes will not otherwise be modified; the caller may place
119       any extra keys in the hashes as required.
120

AUTHOR

122       Paul Evans <leonerd@leonerd.org.uk>
123
124
125
126perl v5.36.0                      2023-01-20                  Tickit::Utils(3)