# Bit Manipulation

When you see the number `3`, you say "three" in base 10.
When the computer sees the number `3`, it says `11` in binary.

For the most part (unless you work with quantum or analogy machinery hahahaha) computers store everything as bits.
Every number is a string of bits.

In BYOND, unlike the rest of the reasonable programming world, **every number is a 32 bit single precision floating point.**
That said, you can still do **bit operations on the significand** (the 24 bit part of it)

## Defines
**We generally define bitfield usage in #define's to make them more legible.**
Bits are always powers of 2 because of how binary numbers are stored.
0 is just all bits off.
1 is the first bit.
2 is the second bit.
4 is the third bit.
8 is the fourth bit.
On and on.
**3** is the first and second bit. You get the number in base 10 by adding together the bit's **values**, so 01 + 10 = 1 + 2 = 3, yes? If you're confused, this'll make your confusion worse but explain how this works better <https://learn.sparkfun.com/tutorials/binary/all>.

## Wrapping your clauses
**Almost always wrap bit operations in ()'s. Order of operations WILL ruin your day if you aren't careful, so it doesn't hurt to be verbose!**
**ALWAYS wrap #define's in ()'s when doing math.** The compiler will optimize the extras out and it doesn't hurt performance, but it means that order of operations won't ruin your day because **you don't know where defines are put in the code, so you don't know what other operators are nearby.**

## WARNING
In BYOND these **can also be used with lists.** Make sure you're using these for binary things if you're looking below, because we'll explain later how it works for lists in [Lists](/jceGiTDDRYyO6B3TMpJweg)

## Field width
BYOND numbers have 24 bits for you to play with, from `(1<<0)` for the first bit all the way to `(1<<23)` for the 24th. **Shifting out of bounds will destroy shifted bits instead of wrapping them around.**

## Cheatsheet
**For the love of all that is holy do not skip the actual explanation on what these does.**

#define BIT1 (1<<0)
#define BIT2 (1<<1)
#define BIT3 (1<<2)

Turn on BIT1:
`variable |= BIT1`
Turn off BIT1 BIT2: The () is important for order of ops!
`variable &= ~(BIT1|BIT2)`
Turn off every bit **but** BIT1 and BIT2
`variable &= (BIT1|BIT2)`
Alternate the bits in something
`variable = ~variable`
Toggle BIT1 and BIT2
`variable ^= (BIT1|BIT2)`
Check if **either** BIT1 or BIT2 are on
`if(variable & (BIT1|BIT2))`
Check if **both** BIT1 and BIT2 are on
`if((variable & (BIT1|BIT2) == (BIT1|BIT2))`
Check if **neither** BIT1 nor BIT2 are on
`if(!(variable & (BIT1|BIT2)))`
Check if either BIT1 or BIT2 are on, **but not both**
`if(((variable & BIT1) ^ (variable & BIT2)) && (variable & (BIT1|BIT2)))`

## OR - `|`
This returns a number with the bits on if it was on in either of its operands.

Example:

(1|2) == 3

This is true.
1 is the first bit
2 is the second bit
3 is the first bit and second bit both being on.

(1|3) == 3

This is true.
3 already

This is usually used to add bits together.

## AND - `&`
This turns bits on if it was on in **both** of its operands

`1&2` = 0
`1&3` = 1
`2&3` = 2

This is usually used to check if bits are on.

## NOT/NEGATE - `~`
Unlike the others, this is an **unary operator.** It operates and returns with just one operand to the right.
`~1` **turns every bit on but the first bit.**
`~0` **turns every bit on**

This is usually used with `&` to turn bits off.

## XOR - `^`
This turns bits on if it was on in one of the operands, but not both.

`1&3` = 2
`2&3` = 1
`3&3` = 0
`3&0` = 0

## Shift left - `<<`
This shifts the LHS (left hand side) operand by the RHS (right hand side) operand number of bits.

`1<<0` = 1
`1<<1` = 2
`1<<2` = 4
`3<<1` = 6
`3<<2` = 12

## Shift right - `>>`
This does the reverse.
`1>>0` = 0
`2>>1` = 1
`4>>2` = 1
`6>>1` = 3
`6>>2` = 1

## Technical Details
BYOND bit operators only operate on the significand of the floating point number
Doing `1.526273 & 2` gives you `3` because only the 1 and 2 matters.
**That said, don't be a dunkass and abuse this, because .. just don't.**