# cpct_get6Bits

Returns the value ( [0-63] ) of a given group of 6 bits into an array

#### C Definition

u8 cpct_get6Bits (void* array, u16 index);

#### Input Parameters (4 Bytes)

(2B DE) array | Pointer to the first byte of the array
(2B HL) index | Index of the group of 6 bits to be retrieved from the array

#### Assembly call (Input parameters on registers)

>     call cpct_get6Bits_asm

#### Parameter Restrictions

- array must be the memory location of the first byte of the array. However, this function will accept any given 16-value, without performing any check. So, be warned that giving mistaken values to this function will not make it fail, but return an unpredictable value.
- index position of the group of 6 bits to be retrieved from the array, starting in 0. As this function does not perform any boundary check, if you gave an index outside the boundaries of the array, the return result would be unpredictable and meaningless.

#### Return value

u8 | Value of the selected group of 6 bits: [0-63]

#### Known limitations

- Maximum of 65536 groups of 6-bits, 49152 bytes per array.

#### Details

Returns a value from 0 to 63 depending on the value of the 6-bits group at the given position (index) in the specified array. It will treat memory at array location as if it contained consecutive 6-bits values instead of bytes. The function internally does the required calculations to get 6-bits groups.

#### Examples

>     // Declare and initialize a 6-bit Array with some useful macros
>     const CPCT_6BITARRAY(my_array, 8) = {
>        CPCT_ENCODE6BITS(10, 12, 31, 45),
>        CPCT_ENCODE6BITS( 7, 60, 18,  2)
>     };

>     // Recover some of the values of the array (take into account that
>     // array indexes start at 0)
>     u8 value1 = cpct_get6Bits(my_array, 0);
>     u8 value3 = cpct_get6Bits(my_array, 2);
>     u8 value6 = cpct_get6Bits(my_array, 5);

>     // This should print 10, 31 and 60
>     printf("Values obtained: %d %d %d\n", value1, value3, value6);

#### Destroyed Register values

AF, BC, DE, HL

#### Required memory

C-bindings | 70 bytes
ASM-bindings | 67 bytes

#### Time Measures

>     Case      | microSecs (us) | CPU Cycles |
>     -----------------------------------------
>     Best (0)  |      37        |     148    |
>     -----------------------------------------
>     Worst(1|3)|      49        |     196    |
>     -----------------------------------------
>     ASM Saving|     -12        |     -48    |
>     -----------------------------------------

We first divide INDEX / 4 because each 4 values are stored in groups of 3-bytes. Therefore, this let us count how many groups of 3-bytes do we have to advance to get to the 3-bytes where our desired value is stored. The remainder of the division tells us which one of the 4 values contained in that target 3-byte group, contains the desired value. Each group of 3-bytes stores the 4 values as follows: [00000011][11112222][22333333]

unsigned char (u8 = unsigned 8-bits, 1 byte )
Returns the value ( [0-63] ) of a given group of 6 bits into an array
unsigned int (u16 = unsigned 16-bits, 2 bytes)
Close