# SIMPOL Documentation

## Bitwise Operators

Bitwise operators are used for applying boolean operations at the individual bit level of a value. They are commonly used to set and test flag values where a single 32-bit integer may carry 32 different values in one integer. This is a very efficient way to pass a number of options in a single value. Bitwise operators are also commonly used in hashing, compression, and encryption algorithms, among others. Use of these operators is generally the province of advanced programmers and they should not be used in place of the Boolean equivalents, since although they may sometimes work, they could produce unexpected results. The bitwise operators are `AND`, `OR`, and `XOR`. These should not be confused with the lowercase operators of the same name in the case of `AND` and `OR`, which are the Boolean operators.

For those unfamiliar with bitwise operators, they operate on the individual bits where each bit contains only 0 or 1. The `AND` operator compares two values and only returns the value 1 if both bits contain a 1, otherwise it returns 0. The `OR` operator compares two values and returns 1 if either of the bits contain 1, otherwise it returns 0. The `XOR` operator compares two values and returns 1 if one of the two values has a bit set and the other does not. If both values are the same (both 1's or both 0's), then it returns 0. The following tables may help clarify things:

Table 3.1. Bitwise AND Table
Op1Op2Result
000
100
010
111

A common use for the `AND` operator is as a test to see if a bit is set in a value.

Table 3.2. Bitwise OR Table
Op1Op2Result
000
101
011
111

A common use for the `OR` operator is to set a bit in a value independent of its current state.

Table 3.3. Bitwise XOR Table
Op1Op2Result
000
101
011
110

A common use for the `XOR` operator is to toggle a bit in a value. Using `XOR` twice with the same operands will return the value back to its starting point.

### AND

2 or more

#### Types

`.nul`, `.inf`, `blob`, `boolean`, `integer`, `number`, `string`

#### Description

All operands other than `.nul` and `.inf` must be of the same type. If any operand is equal to `.nul` then the result is `.nul`. Otherwise if any operand is equal to `.inf` then the result is `.inf`. Otherwise the result is calculated according to the type of the operands.

Table 3.4. Behavior by type for AND
Type nameResult for AND when applied to this type
`.nul` If any operand is `.nul` then the result is `.nul`
`.inf` If any operand is `.inf` and no operand is `.nul` then the result is `.inf`.
blob The result is as long as the longest operand where operands that are not that long behave as if they have been extended with zero bytes. Each byte in the result is the bitwise combination of the corresponding bytes in the operands, where bytes are treated as unsigned values.
boolean The result is calculated using the obvious meanings of `AND`, `OR`, and `XOR`.
integer | number Operands that are of type number are converted to an integer by taking the integer part. The result is the bitwise combination of the integer operand values, where negative values are treated as if they represented the two's complement of their absolute value.
string The result is as long as the longest operand and each character is the bitwise combination of the corresponding characters in each operand string, where characters are considered to be unsigned values. Where operands are not as long as the result the operands behave as if they are extended with characters of Unicode code point zero (`.char(0)`).

### OR

2 or more

#### Types

`.nul`, `.inf`, `blob`, `boolean`, `integer`, `number`, `string`

#### Description

All operands other than `.nul` and `.inf` must be of the same type. If any operand is equal to `.nul` then the result is `.nul`. Otherwise if any operand is equal to `.inf` then the result is `.inf`. Otherwise the result is calculated according to the type of the operands.

Table 3.5. Behavior by type for OR
Type nameResult for OR when applied to this type
`.nul` If any operand is `.nul` then the result is `.nul`
`.inf` If any operand is `.inf` and no operand is `.nul` then the result is `.inf`.
blob The result is as long as the longest operand where operands that are not that long behave as if they have been extended with zero bytes. Each byte in the result is the bitwise combination of the corresponding bytes in the operands, where bytes are treated as unsigned values.
boolean The result is calculated using the obvious meanings of `AND`, `OR`, and `XOR`.
integer | number Operands that are of type number are converted to an integer by taking the integer part. The result is the bitwise combination of the integer operand values, where negative values are treated as if they represented the two's complement of their absolute value.
string The result is as long as the longest operand and each character is the bitwise combination of the corresponding characters in each operand string, where characters are considered to be unsigned values. Where operands are not as long as the result the operands behave as if they are extended with characters of Unicode code point zero (`.char(0)`).

### XOR

2 or more

#### Types

`.nul`, `.inf`, `blob`, `boolean`, `integer`, `number`, `string`

#### Description

All operands other than `.nul` and `.inf` must be of the same type. If any operand is equal to `.nul` then the result is `.nul`. Otherwise if any operand is equal to `.inf` then the result is `.inf`. Otherwise the result is calculated according to the type of the operands.

Table 3.6. Behavior by type for XOR
Type nameResult for XOR when applied to this type
`.nul` If any operand is `.nul` then the result is `.nul`
`.inf` If any operand is `.inf` and no operand is `.nul` then the result is `.inf`.
blob The result is as long as the longest operand where operands that are not that long behave as if they have been extended with zero bytes. Each byte in the result is the bitwise combination of the corresponding bytes in the operands, where bytes are treated as unsigned values.
boolean The result is calculated using the obvious meanings of `AND`, `OR`, and `XOR`.
integer | number Operands that are of type number are converted to an integer by taking the integer part. The result is the bitwise combination of the integer operand values, where negative values are treated as if they represented the two's complement of their absolute value.
string The result is as long as the longest operand and each character is the bitwise combination of the corresponding characters in each operand string, where characters are considered to be unsigned values. Where operands are not as long as the result the operands behave as if they are extended with characters of Unicode code point zero (`.char(0)`).