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, `<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.

