1#  You may distribute under the terms of either the GNU General Public License
2#  or the Artistic License (the same terms as Perl itself)
3#
4#  (C) Paul Evans, 2012-2016 -- leonerd@leonerd.org.uk
5
6package Tickit::StringPos 0.72;
7
8use v5.14;
9use warnings;
10
11# XS code comes from Tickit itself
12require Tickit;
13
14=head1 NAME
15
16C<Tickit::StringPos> - store string position counters
17
18=head1 SYNOPSIS
19
20 use Tickit::StringPos;
21 use Tickit::Utils qw( string_count );
22
23 my $pos = Tickit::StringPos->zero;
24 string_count( "Here is a message", $pos );
25
26 print "The message consumes ", $pos->columns, " columns\n";
27
28=head1 DESCRIPTION
29
30Instances in this object class store four position counters that relate to
31counting strings.
32
33The C<bytes> member counts UTF-8 bytes which encode individual codepoints. For
34example the Unicode character U+00E9 is encoded by two bytes 0xc3, 0xa9; it
35would increment the bytes counter by 2 and the C<codepoints> counter by 1.
36
37The C<codepoints> member counts individual Unicode codepoints.
38
39The C<graphemes> member counts whole composed graphical clusters of
40codepoints, where combining accents which count as individual codepoints do
41not count as separate graphemes. For example, the codepoint sequence U+0065
42U+0301 would increment the C<codepoint> counter by 2 and the C<graphemes>
43counter by 1.
44
45The C<columns> member counts the number of screen columns consumed by the
46graphemes. Most graphemes consume only 1 column, but some are defined in
47Unicode to consume 2.
48
49Instances are also used to store count limits, where any memeber may be set
50to -1 to indicate no limit in that counter.
51
52=cut
53
54=head1 CONSTRUCTORS
55
56=head2 zero
57
58   $pos = Tickit::StringPos->zero
59
60Returns a new instance with all counters set to zero.
61
62=head2 limit_bytes
63
64=head2 limit_codepoints
65
66=head2 limit_graphemes
67
68=head2 limit_columns
69
70   $pos = Tickit::StringPos->limit_bytes( $bytes )
71
72   $pos = Tickit::StringPos->limit_codepoints( $codepoints )
73
74   $pos = Tickit::StringPos->limit_graphemes( $graphemes )
75
76   $pos = Tickit::StringPos->limit_columns( $columns )
77
78Return a new instance with one counter set to the given limit and the other
79three counters set to -1.
80
81=cut
82
83=head1 METHODS
84
85=head2 bytes
86
87=head2 codepoints
88
89=head2 graphemes
90
91=head2 columns
92
93   $bytes = $pos->bytes
94
95   $codepoints = $pos->codepoints
96
97   $graphemes = $pos->graphemes
98
99   $columns = $pos->columns
100
101Return the current value the counters.
102
103=cut
104
105=head1 AUTHOR
106
107Paul Evans <leonerd@leonerd.org.uk>
108
109=cut
110
1110x55AA;
112