# Bit manipulation API

bitmask ( bit -- mask )
  Given a bit number, yield the associated mask. 2 --> $04, 31 --> $80000000

bit? ( n bit -- f )
  Yields whether bit number "bit" is set in "n".

bit1! ( n bit -- n )
  Ensures that bit number "bit" is set in "n".

bit0! ( n bit -- n )
  Ensures that bit number "bit" is unset in "n".

bitsplit ( n bit -- hi lo )
  Split "n" in two "hi" and "lo" part by splitting it at "bit".

  $12345678 4 bitsplit .x spc> .x \ Prints 12345670 00000008

bitflag ( n "name" -- )
  Create a constant "name" with the nth bit set. For example, "3 bitflag FOO"
  is the same as "8 const FOO".

bitfield ( shift sz "name" -- )
  Compile a new word "name", along with a setter [doc/usage/word] , conveniently
  allowing getting and setting bitfields from a 32-bit integer. When setting
  such a field, the destination values resets the affected bits to zero before
  or-ring the new value in.

  The signature of the getter is ( bits -- n )
  The signature of the setter is ( n bits -- )

  Example usage:

    4 6 bitfield foo
    $12345eaf foo . \ prints 42
    42 $12345110 to foo .x \ prints $123452a0

sex8 ( n -- n )
  Provided that "n" is an 8-bit number, sign-extend it to 32-bit, that is, copy
  b7 to all upper bits. Example: $80 sex8 --> $ffffff80

sex16 ( n -- n )
  Same as sex8, but for 16-bit numbers. Example: $8000 sex16 --> $ffff8000

## C API

"needsh lib/bit" provides:

int sex8(int n);
int sex16(int n);
