$BITFIND (ObjectScript)
Synopsis
$BITFIND(bitstring,bitvalue,position,direction)
Arguments
Argument | Description |
---|---|
bitstring | An expression that evaluates to a bitstring. If bitstring is an undefined variable, then $BITFIND returns 0. |
bitvalue | The value (0 or 1) to search for within the bitstring. |
position |
Optional — The bit position from which the search begins, specified as a positive integer. Searching forward or backward, bit positions are counted from 1 from the beginning of the bit string. Search is inclusive of this position. When searching forward (direction = 1 or left unspecified), a missing position or position value of 0 is treated as specifying position 1. When searching backward (direction = -1), a missing position or position value of 0 is treated as specifying the last position in the bitstring. |
direction |
Optional — A direction flag. Available values are 1 and -1.
|
Description
$BITFIND(bitstring,bitvalue) returns the position of the first occurrence of the specified bitvalue (0 or 1) within the bitstring bitstring, searching from left to right. Bit positions are counted from 1 from the beginning of the bit string.
$BITFIND(bitstring,bitvalue,position) returns the position of the first occurrence at or after position of the specified bitvalue in bitstring.
$BITFIND(bitstring,bitvalue,position,direction) specifies the direction in which to search within the bitstring. When direction = 1 or is left unspecified, $BITFIND searches forward, from left to right. When direction = -1, $BITFIND search backward, from right to left. Whether searching forward or backward, bit positions are counted from 1 from the beginning of the bit string.
If the desired bit value is not found, or if position (searching forward) is greater than the number of bits within the bitstring, the return value is 0. If the specified bitstring is an undefined variable, the return value is 0. If the specified bitstring is not a valid bitstring, an <INVALID BIT STRING> error is issued.
There is also general information on bitstring functions.
Examples
Create a 20-element bit string of 1s and 0s.
set bitvalues = "00110001101010000111"
for i = 1:1:$length(bitvalues) { set $bit(bitstring,i) = $extract(bitvalues,i)}
Return the positions of the first bits that have a value of 0 and 1, respectively. By not specifying a position or direction value, $BITFIND searches from position 1 onward.
write $BITFIND(bitstring,0) // returns 1
write $BITFIND(bitstring,1) // returns 3
Return the positions of the first bits have a value of 0 and 1, starting at position 5. $BITFIND searches from position 5 onward.
set position = 5
write $BITFIND(bitstring,0,position) // returns 5
write $BITFIND(bitstring,1,position) // returns 8
Return the positions of the first bits have a value of 0 and 1, starting at position 5 and specifying the backward argument as -1. $BITFIND searches backward, from right to left, starting from position 5.
write $BITFIND(bitstring,0,position,-1) // returns 5
write $BITFIND(bitstring,1,position,-1) // returns 4
Return the position of the first bit that has a value of 1, starting at positions that are outside the bounds of the bit string.
write $BITFIND(bitstring,1,-100) // Search from -100 forward: returns 3
write $BITFIND(bitstring,1,-100,-1) // Search from -100 backward: returns 0
write $BITFIND(bitstring,1,100) // Search from 100 foward: returns 0
write $BITFIND(bitstring,1,100,-1) // Search from 100 backward: returns 20
Return a list of all of the 1 bit positions and 0 bit positions in the bit string.
set position = 0
write !,"Bit positions with value 1: "
for { set position=$BITFIND(bitstring,1,position+1) quit:'position write position,", " }
write !,"Bit positions with value 0: "
for { set position=$BITFIND(bitstring,0,position+1) quit:'position write position,", " }