(Engine-Level Function)
| Description: | Sets or clears a specific bit in a value and returns the result. |
| Returns: | Numeric |
Usage:  |
Script or steady state. |
| Function Groups: | Bitwise Operation |
| Related to: | Bit | Ones |
| Format: |
SetBit(Value, BitNumber, Option) |
| Parameters: |
| Value |
| Required. Any numeric expression that gives the number to modify the bit in. |
| BitNumber |
| Required. Any numeric expression giving the bit number to set or clear. Bit 0 is the least significant bit. Legal values are from 0 to 31 inclusive. |
| Option |
| Required. Any status expression indicating whether the bit is to be set or cleared in the Value. A true indicates that the bit is to be set (i.e. set to 1), and a false indicates that it is to be cleared (i.e. set to 0). |
| Comments: |
This function is useful for saving a series of status values in a single short or long variable. If any argument is invalid, the return value is invalid. |
Examples:
a = SetBit(0, 1, 1);
In this simple example, the values for a will be 2 { 0b00000010 }. This is not a particularly useful example of SetBit, though. Most likely you will want to use it in a statement like the following:
b = SetBit(b, 2, 1);
In this case, bit number 2 will be set to 1. It is important to note, however, that if b is invalid, this statement will have no effect (i.e. it will not make b valid). A safer way to accomplish the setting of bit 2, then, might be to write
b = SetBit(PickValid(b, 0), 2, 1);
so that the b being invalid case is covered.
