A series of functions beginning with $ZBIT lets you manipulate a bit stream. Internally, GT.M stores a bit stream in the form of a bit string. A bit string embeds a bit stream in such a way that the first byte specifies the number of trailing bits in the last byte that are not part of the bit-stream. In this way, GT.M is able to store bit-streams of lengths other than multiples of 8 bits in byte format. So for example, a first byte of value of zero (0) indicates that all of the bits in the last byte belong to the bit-stream, while a one (1) indicates the last bit is excluded and a seven (7) indicates that only the first bit in the last byte belongs to the bit-stream.
If you have to convert a character string into a bit string then add a leading byte to that character string so that all $ZBIT functions can recognize it. The most common and straightforward way of doing this is to concatenate a $CHAR(n) on the front of the character string, where the value of n is zero through seven (0-7) – most commonly zero (0). If you pass a bit string as an argument to a routine that is expecting a character string, then that caller routine must strip off the first (and possibly the last) byte so that it can recognize the character string.
This section contains the description of all $ZBIT function and an example of using $ZBIT functions to turn a character into a bit stream and return a coded value. However, the most appropriate use of these functions may include the formation of checksums, handling of bit-data (say pixels from a scan), or interfacing with a routine that requires bit-oriented arguments.
Performs a logical AND function on two bit strings and returns a bit string equal in length to the shorter of the two arguments (containing set bits in those positions where both of the input strings have set bits). Positions corresponding to positions where either of the input strings have a cleared bit, also have cleared bits in the resulting string.
The format for the $ZBITAND() function is:
$ZBITAND(expr1,expr2)
The first expression specifies one of the bit strings that is input to the AND operation.
The second expression specifies the other bit string that is input to the AND operation.
GTM> ; The binary representation of A is 01000001 GTM>Set BITSTRINGB=$zbitset($zbitset($zbitstr(8,0),2,1),7,1) ; The binary representation of B is 01000010 GTM>set BITSTRINGAB=$zbitand(BITSTRINGA,BITSTRINGB) GTM>for i=1:1:8 write $zbitget(BITSTRINGAB,I) 01000000
This examples uses $ZBITAND to perform a bitwise AND operation on A and B.
A= 01000001 B= 01000010 A bitwise AND B=0100000
Returns the number of ON bits in a bit string.
The format for the $ZBITCOUNT function is:
$ZBITCOUNT(expr)
The expression specifies the bit string to examine.
Example:
GTM>set BITSTRINGA=$ZBITSET($ZBITSET($ZBITSTR(8,0),2,1),8,1) ; The binary representation of A is 01000001 GTM>set BITSTRINGB=$zbitset($zbitset($zbitstr(8,0),2,1),7,1) ; The binary representation of B is 01000010 GTM>Set BITSTRINGC=$zbitor(BITSTRINGA,BITSTRINGB) ; A OR B=01000011 GTM>write $zbitcount(BITSTRINGA) 2 GTM>write $zbitcount(BITSTRINGB) 2 GTM>write $zbitcount(BITSTRINGC) 3 GTM>
This example displays the number of ON bits in BITSTRINGA, BITSTRINGB, and BITSTRINGC.
Performs the analog of $FIND() on a bit string. It returns an integer that identifies the position after the first position equal to a truth-valued expression that occurs at, or after, the specified starting position.
The format for the $ZBITFIND function is:
$ZBITFIND(expr,tvexpr[,intexpr])
The expression specifies the bit string to examine.
The truth-valued expression specifies the bit value for which $ZBITFIND() searches (1 or 0).
The optional integer argument specifies the starting position at which to begin the search. If this argument is missing, $ZBITFIND() begins searching at the first position of the string. $ZBIT functions count the first bit as position one (1).
If the optional integer argument exceeds the length of the string, or if the function finds no further bits, $ZBITFIND() returns a zero value.
Returns the value of a specified position in the bit string.
The format for the $ZBITGET function is:
$ZBITGET(expr,intexpr)
The expression specifies the bit string to examine.
The integer argument specifies the position in the string for which the value is requested. If the integer argument is negative, zero, or exceeds the length of the bit string, it is rejected with a run-time error. $ZBIT functions count the first bit as position one (1).
Returns the length of a bit string, in bits.
The format for the $ZBITLEN function is:
$ZBITLEN(expr)
The expression specifies the bit string to examine.
Returns a copy of the bit string with each input bit position inverted.
The format for the $ZBITNOT function is:
$ZBITNOT(expr)
The expression specifies the bit string whose inverted bit pattern becomes the result of the function.
Performs a bitwise logical OR on two bit strings, and returns a bit string equal in length to the longer of the two arguments (containing set bits in those positions where either or both of the input strings have set bits). Positions that correspond to positions where neither input string has a set bit have cleared bits in the resulting string.
The format for the $ZBITOR function is:
$ZBITOR(expr1,expr2)
The first expression specifies one of the bit strings that is input to the OR operation.
The second expression specifies the other bit string that is input to the OR operation.
GTM>set BITSTRINGA=$zbitset($zbitset($zbitstr(8,0),2,1),8,1) ; The binary representation of A is 01000001 GTM>set BITSTRINGB=$zbitset($zbitset($zbitstr(8,0),2,1),7,1) ; The binary representation of B is 01000010 GTM>set BITSTRINGC=$zbitor(BITSTRINGA,BITSTRINGB) ; A OR B=01000011 GTM>write BITSTRINGC C GTM>
This example displays the result of BITSTRINGA bitwise ORed with BITSTRINGB.
Returns an edited copy of the input bit string with a specified bit set to the value of the truth-valued expression.
The format for the $ZBITSET function is:
$ZBITSET(expr,intexpr,tvexpr)
The expression specifies the input bit string.
The integer expression specifies the position of the bit to manipulate. Arguments that are negative, zero, or exceed the length of the bit string produce a run-time error. $ZBIT functions count the first bit as position one (1).
The truth-valued expression specifies the value to which to set the specified bit (0 or 1).
Returns a bit string of a specified length with all bit positions initially set to either zero or one.
The format for the $ZBITSTR function is:
$ZBITSTR(intexpr[,tvexpr])
The integer expression specifies the length of the bit string to return; arguments that exceed the maximum length of 253,952 produce a run-time error.
The optional truth-valued expression specifies the value to which all bit positions should initially be set (0 or 1). If this argument is missing, the bits are set to zero.
Performs a bitwise exclusive OR on two bit strings, and returns a bit string equal in length to the shorter of the two arguments (containing set bits in those position where either but not both of the input strings have set bits). Positions that correspond to positions where neither or both input string has a set bit have cleared bits in the resulting string.
The format for the $ZBITXOR function is:
$ZBITXOR(expr1,expr2)
The first expression specifies one of the bit strings that is input to the XOR operation.
The second expression specifies the other bit string that is input to the XOR operation.
GTM>set BITSTRINGA=$zbitset($zbitset($zbitstr(8,0),2,1),8,1) ; The binary representation of A is 01000001 GTM>set BITSTRINGB=$zbitset($zbitset($zbitstr(8,0),2,1),7,1); The binary representation of B is 01000010 GTM>set BITSTRINGC=$zbitor(BITSTRINGA,BITSTRINGB) ; A XOR B=00000011 GTM>for I=1:1:8 write $zbitget(BITSTRINGC,I) 00000011 GTM>
This example displays the result of the bitwise XOR of A and B.
Example:
ZCRC(X)
new R,I,J,B,X1,K
set R=$zbitstr(8,0)
for I=1:1:$length(X) Set R=$zbitxor(R,$$bitin($A(X,I)))
quit $$bitout(R)
bitin(X) ;CONVERT A BYTE TO A BIT STRING
set X1=$zbitstr(8,0)
for J=1:1:8 set B=X#2,X=X\2 if B set X1=$zbitset(X1,J,1)
quit X1
bitout(X) ; CONVERT A BITSTRING TO A NUMBER
set X1=0
for K=1:1:8 I $zbitget(X,K) set X1=X1+(2**(K-1))
quit X1
This uses several $ZBIT functions to turn a character into a bit stream and return a coded value.
While this example illustrates the use of several of the $ZBIT functions, the following example produces identical results if you need to code the function illustrated above for production.
ZCRC(X)
new R,I,J,B,X1,K
set R=$zbitstr(8,0)
for I=1:1:$length(X) Set R=$zbitxor(R,$char(0)_$extract(X,I))
quit $ascii(R,2)
This example illustrates the use of $Char() to specify the number of invalid bits that exist at the end of the character string. In this case there are zero invalid bits.