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
    
        bit_toggle(\$b, 4); # same as above, but with a reference
    
        $b = bit_off($b, 7);    # 0 
        $b = bit_on($b, 7);     # 10000000 
    
        bit_off(\$b, 7);
        bit_on(\$b, 7);
    
        # 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, 3, 0b101); # 10010100
    
        bit_set(\$b, 2, 3, 0b101); # reference
    
        # clear some bits
    
        $b = 0b11111111;
    
        $num_bits = 3;
        $lsb = 3;
    
        $b = bit_clr($b, $lsb, $num_bits); # 11000111
    
        bit_clr(\$b, $lsb, $num_bits); # reference
    
        # 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::PP qw(:all);) to import the
    following functions into your namespace, or pick and choose
    individually:

        bit_get 
        bit_set
        bit_clr
        bit_toggle
        bit_on
        bit_off
        bit_bin
        bit_count
        bit_mask

FUNCTIONS

 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 equal to or 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.
    Optionally, send in a reference to the scalar, and we'll work directly
    on it instead of passing by value and getting the updated value
    returned.

        $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 plan on setting. This is so
    that any leading zeros are honoured.

        $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 if <C$data> is passed in by
    value, or 0 if passed in by reference.

    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

    Clear (unset to 0) specific bits in the bit string.

    Parameters:

        $data

    Mandatory: Integer, the bit string you want to manipulate bits in.
    Optionally, send in a reference to the scalar, and we'll work directly
    on it instead of passing by value and getting the updated value
    returned.

        $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.

    Return: Integer, the modified $data param if <C$data> is passed in by
    value, or 0 if passed in by reference.

 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.
    Optionally, send in a reference to the scalar, and we'll work directly
    on it instead of passing by value and getting the updated value
    returned.

        $bit

    Mandatory: Integer, the bit number counting from the right-most (LSB)
    bit starting from 0.

    Return: Integer, the modified $data param if <C$data> is passed in by
    value, or 0 if passed in by reference.

 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.
    Optionally, send in a reference to the scalar, and we'll work directly
    on it instead of passing by value and getting the updated value
    returned.

        $bit

    Mandatory: Integer, the bit number counting from the right-most (LSB)
    bit starting from 0.

    Return: Integer, the modified $data param if <C$data> is passed in by
    value, or 0 if passed in by reference.

 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.
    Optionally, send in a reference to the scalar, and we'll work directly
    on it instead of passing by value and getting the updated value
    returned.

        $bit

    Mandatory: Integer, the bit number counting from the right-most (LSB)
    bit starting from 0.

    Return: Integer, the modified $data param if <C$data> is passed in by
    value, or 0 if passed in by reference.

 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.

 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.

AUTHOR

    Steve Bertrand, <steveb at cpan.org>

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.

