
Caché ObjectScript Reference
$BITLOGIC



Server:docs2 
Instance:LATEST 
User:UnknownUser 


Performs bitwise operations on bitstrings.
Synopsis
$BITLOGIC(bitstring_expression,length)
$BITLOGIC evaluates a bitwise operation on one or more bitstring values, as specified by
bitstring_expression, and returns the resulting bitstring.
$BITLOGIC is incompatible with any of the legacy
$ZBIT bitstring functions, and should not be used in combination with them.
$BITLOGIC and
$ZBOOLEAN use different data formats. The results of one cannot be used as input to the other.
The most basic
$BITLOGIC operation is
$BITLOGIC(a). Seemingly, this operation does not do anything: bitstring
a is input and the same bitstring
a is output. However,
$BITLOGIC performs bitstring compression which it optimizes by selecting from several compression algorithms. Therefore, if bitstring
a has undergone substantial changes since its creation, passing it through
$BITLOGIC can result in reoptimization of the bitstring. Refer to
$BIT for further details.
For example, following a large number of delete operations an index bitstring may have become a sparse bitstring, consisting wholly or mainly of zeros. Passing this index bitstring through
$BITLOGIC may result in substantial performance improvements.
Bitstring Logical Operators
$BITLOGIC can evaluate only the bitstring operators listed in the following table:
The
bitstring_expression can contain a single bitstring (~A), two bitstrings (A&B), or more than two bitstrings (A&BC), up to the current maximum of 31 bitstrings. Evaluation is performed lefttoright. Logical operations may be grouped by parentheses within the
bitstring_expression, following standard Caché ObjectScript order of operations. If a variable used within
$BITLOGIC is undefined, it is treated as a null string ("").
$BITLOGIC treats a null string as a bitstring of indefinite length, in which all bits are set to 0’s.
Note:
When
$BITLOGIC is supplied more than two bitstring operands, it must create bitstring temporaries to hold the intermediate results. Under some extreme circumstances (many bitstrings and/or extremely large bitstrings), it can exhaust the space allocated to hold such temporaries. Bitstring pair operations do not have this limitation, and are thus preferable for large bitstring operations.
The NOT (~) operator can be used as a unary operator (for example, ~A), or can be used in combination with other operators (for example, A&~B). It performs the one’s complement operation on a string, turning all 1’s to 0’s and all 0’s to 1’s. Multiple NOT operators can be used (for example, ~~~A).
If
length is specified, it specifies the logical length of the resulting bitstring.

If
length is larger than one or more of the bitstrings in
bitstring_expression, those bitstrings are zerofilled to that length before bitstring logic operations are performed.

If
length is smaller than one or more of the bitstrings in
bitstring_expression, those bitstrings are truncated to that length before bitstring logic operations are performed.

If
length is 0, a bitstring of length 0 (a null string) is returned.
The following example creates some simple bitstrings and demonstrates the use of
$BITLOGIC on them:
// Set a to [1,1]
SET $BIT(a,1) = 1
SET $BIT(a,2) = 1
// Set b to [0,1]
SET $BIT(b,1) = 0
SET $BIT(b,2) = 1
WRITE !,"bitstring a=",$BIT(a,1),$BIT(a,2)
WRITE !,"bitstring b=",$BIT(b,1),$BIT(b,2)
SET c = $BITLOGIC(~b)
WRITE !,"The one's complement of b=",$BIT(c,1),$BIT(c,2)
// Find the intersection (AND) of a and b
SET c = $BITLOGIC(a&b) // c should be [0,1]
WRITE !,"The AND of a and b=",$BIT(c,1),$BIT(c,2)
SET c = $BITLOGIC(a&~b) // c should be [1,0]
WRITE !,"The AND of a and ~b=",$BIT(c,1),$BIT(c,2)
// Find the union (OR) of a and b
SET c = $BITLOGIC(ab) // c should be [1,1]
WRITE !,"The OR of a and b=",$BIT(c,1),$BIT(c,2)
SET c = $BITLOGIC(a^b) // c should be [1,0]
WRITE !,"The XOR of a and b=",$BIT(c,1),$BIT(c,2)
QUIT
The following example shows the results of specifying a
length greater than the input bitstring. The string is zerofilled before the logic operation is performed.
// Set a to [1,1]
SET $BIT(a,1) = 1
SET $BIT(a,2) = 1
WRITE !,"bitstring a=",$BIT(a,1),$BIT(a,2)
SET c = $BITLOGIC(~a,7)
WRITE !,"~a (length 7)="
WRITE $BIT(c,1),$BIT(c,2),$BIT(c,3),$BIT(c,4)
WRITE $BIT(c,5),$BIT(c,6),$BIT(c,7),$BIT(c,8)
Here the one’s complement (~) of
11 is
0011111. Bits 3 through 7 were set to zero before the ~ operation was performed. This example also displays an eighth bit, which is beyond the specified string length and thus unaffected by the
$BITLOGIC operation. It is, of course, displayed as 0.
The following example shows the results of specifying a
length less than the input bitstring. The bitstring is truncated to the specified length before logical operations are performed. All bits beyond the specified length default to 0.
// Set a to [1,1,1]
SET $BIT(a,1) = 1
SET $BIT(a,2) = 1
SET $BIT(a,3) = 1
WRITE !,"bitstring a=",$BIT(a,1),$BIT(a,2),$BIT(a,3)
SET c = $BITLOGIC(a,2)
WRITE !," a (length 2)="
WRITE $BIT(c,1),$BIT(c,2),$BIT(c,3),$BIT(c,4)
SET c = $BITLOGIC(~a,2)
WRITE !,"~a (length 2)="
WRITE $BIT(c,1),$BIT(c,2),$BIT(c,3),$BIT(c,4)
The following example shows that when
length is not specified, it defaults to the length of the longest bitstring. Shorter bitstrings are zerofilled before the logical operation is performed.
// Set a to [1,1,1]
SET $BIT(a,1) = 1
SET $BIT(a,2) = 1
SET $BIT(a,3) = 1
// Set b to [1,1]
SET $BIT(b,1) = 1
SET $BIT(b,2) = 1
SET c = $BITLOGIC(a&~b)
WRITE !," a&~b="
WRITE $BIT(c,1),$BIT(c,2),$BIT(c,3)
SET c = $BITLOGIC(a&~b,3)
WRITE !,"a&~b,3="
WRITE $BIT(c,1),$BIT(c,2),$BIT(c,3)
Here the two
$BITLOGIC operations (with and without a
length argument) both return the same value:
001.