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