NAME
Bit::Manip - Functions to simplify bit string manipulation
SYNOPSIS
use Bit::Manip qw(:all);
my $b; # bit string
$b = 128; # 10000000
$b = bit_toggle($b, 4); # 10010000
$b = bit_toggle($b, 4); # 10000000
$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;
$b = bit_set($b, 2, 0b101); # 10010100
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
Provides functions to aid in bit manipulation (set, unset, toggle,
shifting) etc. Particularly useful for embedded programming and writing
device communication software.
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_bin
bit_count
bit_mask
bit_get
bit_set
bit_toggle
bit_on
bit_off
FUNCTIONS
bit_bin
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
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_get
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). This value must be lower than `$msb'.
Return: Integer, the modified `$data' param.
bit_set
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'.
$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, 0b111); # (0x07, or 7)
printf("%b\n", $x); # prints 11110000
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
Sets a single bit (sets to `1'), regardless of its current state.
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
Unsets a single bit (sets to `0'), regardless of its current state.
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_mask
Generates a bit mask for the specific bits you specify.
Parameters:
$bits
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.