NAME
Bit::Manip::PP - Pure Perl functions to simplify bit string
manipulation
SYNOPSIS
use Bit::Manip qw(:all);
my $b; # bit string
$b = 128; # 10000000
# toggle a bit off and on
$b = bit_tog($b, 4); # 10010000
$b = bit_tog($b, 4); # 10000000
# turn a bit off, then back on
$b = bit_off($b, 7); # 0
$b = bit_on($b, 7); # 10000000
# get the value of a range of bits...
# in this case, we'll print the value of bits 4-3
$b = 0b00111000; (56)
print bit_get($b, 4, 3); # 3
# set a range of bits...
# let's set bits 4-2 to binary 101
$b = 0b10000000;
my $num_bits = 3; # 0b101 in the call is 3 bits
$b = bit_set($b, 2, $num_bits, 0b101); # 10010100
# clear some bits
$b = 0b11111111;
$num_bits = 3;
$lsb = 3;
$b = bit_clr($b, $lsb, $num_bits); # 11000111
# helpers
my ($num_bits, $lsb) = (3, 2);
print bit_mask($num_bits, $lsb); # 28, or 11100
print bit_bin(255); # 11111111 (same as printf("%b", 255);)
DESCRIPTION
This is the Pure Perl version of the XS-based Bit::Manip distribution.
Provides functions to aid in bit manipulation (set, unset, toggle,
shifting) etc. Particularly useful for embedded programming and writing
device communication software.
In functions that modify your data, you can pass your data by value and
get the modified value returned, or pass it in as a scalar reference
and we'll modify the data inline.
Currently, up to 32-bit integers are supported.
EXPORT_OK
Use the :all tag (eg: use Bit::Manip qw(:all);) to import the following
functions into your namespace, or pick and choose individually:
bit_get
bit_set
bit_clr
bit_tog
bit_on
bit_off
bit_bin
bit_count
bit_mask
FUNCTIONS
bit_get($data, $msb, $lsb)
Retrieves the value of specified bits within a bit string.
Parameters:
$data
Mandatory: Integer, the bit string you want to send in. Eg: 255 for
11111111 (or 0xFF).
$msb
Mandatory: Integer, the Most Significant Bit (leftmost) of the group of
bits to collect the value for (starting from 0 from the right, so with
1000, so you'd send in 3 as the start parameter for the bit set to 1).
Must be 1
$lsb
Optional: Integer, the Least Significant Bit (rightmost) of the group
of bits to collect the value for (starting at 0 from the right). A
value of 0 means return the value from $msb through to the very end of
the bit string. A value of 1 will capture from $msb through to bit 1
(second from right). If $msb is equal to $lsb, we'll return just that
bit.
Return: Integer, the modified $data param.
bit_set($data, $lsb, $nbits, $value)
Allows you to set a value for specific bits in your bit string.
Parameters:
$data
Mandatory: Integer, the bit string you want to manipulate bits in.
$lsb
Mandatory: Integer, the least significant bit (rightmost) in the bit
range you want to manipulate. For example, if you wanted to set a new
value for bits 7-5, you'd send in 5.
$nbits
Mandatory: Integer, the number of bits you're sending in. We need this
param in the event your leading bit is a zero. For example, if you're
sending in 0b111 or 0b001, this param would be 3.
$value
Mandatory: Integer, the value that you want to change the specified
bits to. Easiest if you send in a binary string (eg: 0b1011 in Perl).
Return: Integer, the modified $data param.
Example:
You have an 8-bit register where the MSB is a start bit, and the rest
of the bits are zeroed out:
my $data = 0b10000000; # (0x80, or 128)
The datasheet for the hardware you're writing to requires you to set
bits 6-4 to 111 in binary (always start from bit 0, not 1):
10000000
^^^ ^
6-4 0
Code:
my $x = bit_set($data, 4, 3, 0b111); # (0x07, or 7)
printf("%b\n", $x); # prints 11110000
bit_clr($data, $lsb, $nbits)
Clear (unset to 0) specific bits in the bit string.
Parameters:
$data
Mandatory: Integer, the bit string you want to manipulate bits in.
$lsb
Mandatory: Integer, the least significant bit (rightmost) in the bit
range you want to manipulate. For example, if you wanted to clear bits
7-5, you'd send in 5.
$nbits
Mandatory: Integer, the number of bits you're wanting to clear,
starting from the $lsb bit, and clearing the number of bits to the
left.
Returns the modified bit string.
bit_toggle($data, $bit)
See "bit_tog".
bit_tog($data, $bit)
AKA: bit_toggle().
Toggles a single bit. If it's 0 it'll toggle to 1 and vice-versa.
Parameters:
$data
Mandatory: Integer, the number/bit string to toggle a bit in.
$bit
Mandatory: Integer, the bit number counting from the right-most (LSB)
bit starting from 0.
Return: Integer, the modified $data param.
bit_on($data, $bit)
Sets a single bit (sets to 1), regardless of its current state. This is
just a short form of setting a single bit with bit_set.
Parameters:
$data
Mandatory: Integer, the number/bit string to toggle a bit in.
$bit
Mandatory: Integer, the bit number counting from the right-most (LSB)
bit starting from 0.
Return: Integer, the modified $data param.
bit_off($data, $bit)
Unsets a single bit (sets to 0), regardless of its current state. This
is just a short form of clearing a single bit with bit_set.
Parameters:
$data
Mandatory: Integer, the number/bit string to toggle a bit in.
$bit
Mandatory: Integer, the bit number counting from the right-most (LSB)
bit starting from 0.
Return: Integer, the modified $data param.
bit_bin($data)
Returns the binary representation of a number as a string of ones and
zeroes.
Parameters:
$data
Mandatory: Integer, the number you want to convert.
bit_count($num, $set)
Returns either the total count of bits in a number, or just the number
of set bits (if the $set, parameter is sent in and is true).
Parameters:
$num
Mandatory: Unsigned integer, the number to retrieve the total number of
bits for. For example, if you send in 15, the total number of bits
would be 4, likewise, for 255, the number of bits would be 16.
$set
Optional: Integer. If this is sent and is a true value, we'll return
the number of *set* bits only. For example, for 255, the set bits will
be 8 (ie. all of them), and for 8, the return will be 1 (as only the
MSB is set out of all four of the total).
Return: Integer, the number of bits that make up the number if $set is
0, and the number of set bits (1's) if $set is true.
bit_mask($nbits, $lsb)
Generates a bit mask for the specific bits you specify.
Parameters:
$nbits
Mandatory: Integer, the number of bits to get the mask for.
$lsb
Mandatory: Integer, the LSB at which you plan on implementing your
change.
Return: Integer, the bit mask ready to be applied.
AUTHOR
Steve Bertrand,
LICENSE AND COPYRIGHT
Copyright 2017 Steve Bertrand.
This program is free software; you can redistribute it and/or modify it
under the terms of either: the GNU General Public License as published
by the Free Software Foundation; or the Artistic License.
See http://dev.perl.org/licenses/ for more information.