NAME Bit::Manip::PP - Pure Perl functions to simplify bit string manipulation SYNOPSIS use Bit::Manip::PP 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 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. Currently, up to 32-bit integers are supported. EXPORT_OK Use the :all tag (eg: use Bit::Manip::PP 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.