File Coverage

blib/lib/Bit/Twiddling.pm
Criterion Covered Total %
statement 9 9 100.0
branch n/a
condition n/a
subroutine 3 3 100.0
pod n/a
total 12 12 100.0


line stmt bran cond sub pod time code
1             package Bit::Twiddling;
2              
3 3     3   173844 use strict;
  3         19  
  3         71  
4 3     3   12 use warnings;
  3         4  
  3         157  
5              
6             =head1 NAME
7              
8             Bit::Twiddling - Low-level bit-twiddling hacks
9              
10             =head1 VERSION
11              
12             Version 0.10
13              
14             =cut
15              
16             our $VERSION = '0.10';
17              
18             =head1 SYNOPSIS
19              
20             use Bit::Twiddling 'count_set_bits';
21             my $number = 0b1111_0001;
22             my $set_bits = count_set_bits($number); # 5
23              
24             use Bit::Twiddling 'nearest_higher_power_of_2';
25             print nearest_higher_power_of_2( 0); # 1
26             print nearest_higher_power_of_2(1000); # 1024
27             print nearest_higher_power_of_2(1024); # 1024
28              
29             =head1 DESCRIPTION
30              
31             This library is a collection of bit-manipulation functions written in
32             C, all taken from the L
33             Hacks|http://graphics.stanford.edu/~seander/bithacks.html> webpage.
34              
35             =cut
36              
37             require XSLoader;
38             XSLoader::load('Bit::Twiddling', $VERSION);
39              
40 3     3   13 use Exporter 'import';
  3         4  
  3         230  
41              
42             our @EXPORT_OK = qw(
43             count_set_bits
44             nearest_higher_power_of_2
45             );
46              
47             our %EXPORT_TAGS = ( all => [@EXPORT_OK] );
48              
49             1;
50              
51             =head1 EXPORTS
52              
53             Nothing is exported by default, but the following functions are
54             available for export by name
55              
56             =over 4
57              
58             count_set_bits
59              
60             nearest_higher_power_of_2
61              
62             =back
63              
64             Additionally, you can request the export of all functions by C
65             Bit::Twiddling ':all'>.
66              
67             =cut
68              
69             =head1 FUNCTIONS
70              
71             The functions in this module expect a single integer argument, but
72             will convert string to numeric if needed (and give an C
73             isn't numeric in subroutine entry> warning). If the argument is
74             C, it will be treated as if it were zero and generate a C
75             of uninitialized value in subroutine entry> warning.
76              
77             This distribution was designed to work with a perl compiled with
78             C and C. It should, however, be OK without
79             these options.
80              
81             =head2 count_set_bits
82              
83             $bits = count_set_bits($number);
84              
85             C will return the count of how many bits are set (1)
86             in the binary representation of C<$number>. C<$number> is assumed to
87             be compatible with C's C type (probably 64-bits).
88              
89             =head2 nearest_higher_power_of_2
90              
91             $power_of_2 = nearest_higher_power_of_2($number);
92              
93             C will return the largest power-of-two that
94             is greater-than-or-equal-to C<$number>.
95              
96             =head1 EXAMPLES
97              
98             There are two scripts in the C folder of the dist.
99              
100             =head2 c.pl
101              
102             This script contains the original C code that was used with
103             C to generate the module's XS.
104              
105             =head2 benchmarks.pl
106              
107             Some benchmarks of this module versus various pure Perl
108             implementations.
109              
110             =head1 AUTHOR
111              
112             Brian Greenfield
113              
114             =head1 REPORTING BUGS & OTHER WAYS TO CONTRIBUTE
115              
116             The code for this module is maintained on
117             L.
118              
119             If you have a patch, feel free to fork the repository and submit a
120             pull request. If you find a bug, please open an issue on the project
121             at GitHub (L).
122              
123             =head1 ACKNOWLEDGEMENTS
124              
125             =over
126              
127             * Steve Bertrand's
128             L
129             tutorial
130              
131             * L
132             Hacks|http://graphics.stanford.edu/~seander/bithacks.html>
133              
134             * L
135              
136             =back
137              
138             =head1 LICENSE AND COPYRIGHT
139              
140             Copyright 2018 Brian Greenfield
141              
142             This program is free software; you can redistribute it and/or modify
143             it under the same terms as Perl itself.
144              
145             See L
146              
147             =cut