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; my $num_bits = 3; # 0b101 in the call is 3 bits $b = bit_set($b, 2, $num_bits, 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'. $bits 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_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.