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   189887 use strict;
  3         22  
  3         78  
4 3     3   13 use warnings;
  3         4  
  3         159  
5              
6             =head1 NAME
7              
8             Bit::Twiddling - Low-level bit-twiddling hacks
9              
10             =head1 VERSION
11              
12             Version 0.08 - 2018-08-31
13              
14             =cut
15              
16             our $VERSION = '0.08';
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             printf "There are %d ones in 0b%b\n", $set_bits, $number
24             # There are 5 ones in 0b11110001
25              
26             use Bit::Twiddling 'nearest_higher_power_of_2';
27             print nearest_higher_power_of_2( 0); # 1
28             print nearest_higher_power_of_2(1000); # 1024
29             print nearest_higher_power_of_2(1024); # 1024
30              
31             =head1 DESCRIPTION
32              
33             This library is a collection of bit-manipulation functions written in
34             C, all taken from the L
35             Hacks|http://graphics.stanford.edu/~seander/bithacks.html> webpage.
36              
37             =cut
38              
39             require XSLoader;
40             XSLoader::load('Bit::Twiddling', $VERSION);
41              
42 3     3   13 use Exporter 'import';
  3         5  
  3         236  
43              
44             our @EXPORT_OK = qw(
45             count_set_bits
46             nearest_higher_power_of_2
47             );
48              
49             our %EXPORT_TAGS = ( all => [@EXPORT_OK] );
50              
51             1;
52              
53             =head1 EXPORTS
54              
55             Nothing is exported by default, but the following functions are
56             available for export by name
57              
58             =over 4
59              
60             count_set_bits
61              
62             nearest_higher_power_of_2
63              
64             =back
65              
66             Additionally, you can request the export of all functions by C
67             Bit::Twiddling ':all'>.
68              
69             =cut
70              
71             =head1 FUNCTIONS
72              
73             The functions in this module all expect a single 64-bit integer
74             argument, but will convert string to numeric if needed (and give an
75             C warning). If
76             the argument is C, it will also be treated as if it were zero
77             and generate a C
78             warning.
79              
80             This distribution is designed to work with 64-bit ints and has NOT
81             BEEN TESTED WITH 32-BIT PERLS. I think it should be OK but I know one
82             test in C will definately fail.
83              
84             =head2 count_set_bits
85              
86             $bits = count_set_bits($number);
87              
88             C will return the count of how many bits are set (1)
89             in the binary representation of C<$number>. C<$number> is assumed to
90             be compatible with C's C type (probably 64-bits).
91              
92             =head2 nearest_higher_power_of_2
93              
94             $power_of_2 = nearest_higher_power_of_2($number);
95              
96             C will return the largest power-of-two that
97             is greater-than-or-equal-to C<$number>.
98              
99             =head1 EXAMPLES
100              
101             There are two scripts in the C folder of the dist.
102              
103             =head2 c.pl
104              
105             This script contains the original C code that was used with
106             C to generate the module's XS.
107              
108             =head2 benchmarks.pl
109              
110             Some benchmarks of this module versus various pure Perl
111             implementations.
112              
113             =head1 AUTHOR
114              
115             Brian Greenfield
116              
117             =head1 REPOSITORY
118              
119             XXX github
120              
121             =head1 BUGS
122              
123             Please use report any bugs you find to L
124             issues|https://github.com/briang/p5-bit-twiddling/issues>.
125              
126             =head1 ACKNOWLEDGEMENTS
127              
128             =over
129              
130             * Steve Bertrand's
131             L
132             tutorial
133              
134             * L
135             Hacks|http://graphics.stanford.edu/~seander/bithacks.html>
136              
137             * L
138              
139             =back
140              
141             =head1 LICENSE AND COPYRIGHT
142              
143             Copyright 2018 Brian Greenfield
144              
145             This program is free software; you can redistribute it and/or modify
146             it under the same terms as Perl itself.
147              
148             See L
149              
150             =cut