:bit_struct

1. Overview

bit_struct: splits each value into several parts for a field of the INT_ARRAY type and performs specific operations on the several parts.

2. Syntax

bit_struct(doc_field,"$struct_definition", operation,...)

3. Parameters

• doc_field: a field of the INT_ARRAY type.

• $struct_definition: the information about bit positions used to split each 64-bit integer in an array into multiple parts. Each part represents a dimension. You can specify the start bit position and end bit position of each part. The start bit position and end bit position are separated by a hyphen (-). For a 64-bit integer, the bits from the leftmost bit to the rightmost bit are numbered from 0 to 63. The end bit position of a part cannot exceed 63. Separate multiple parts with commas (,). The parts are numbered from 1. For example, you want to split a 64-bit integer into three parts, with each part representing a dimension. The bits from Bit 0 to Bit 9 indicate a value that is represented by $1. The bits from Bit 10 to Bit 48 indicate a value that is represented by $2. The bits from Bit 49 to Bit 60 indicate a value that is represented by $3. Then, you can set the $struct_definition parameter to "0-9,10-48,49-60".

• operation: the operations to be performed on the parts. You can specify one to five operations. Operations are numbered after the parts that are specified by the $struct_definition parameter, and the numbers of operations increase. When you specify multiple operations and an operation may reference the return value of a preceding operation, you can use the number of the preceding operation. The bit_struct function supports the following operations:

  • "equal,$m,$n": determines whether the value represented by $m equals the value represented by $n. If so, true is returned. If not, false is returned.

  • "overlap,$m,$n,$k,$p": determines whether the ranges defined by ($m,$n) and ($k,$p) intersect. If so, true is returned. If not, false is returned.

  • "and,$m,$n,…": performs the AND logical operation on specified values, such as $m and &n. Take note that the specified values of the preceding operations can be integers. Example: "equal,$1,1".

4. Return value

The return value is a 64-bit integer that indicates the subscript of the array element for which the last operation returns true. The subscripts of array elements start from 0. If no array elements for which the last operation returns true exist in the field specified by the doc_field parameter, the bit_struct function returns -1.

5. Usage notes

• The field that you reference in the parameters of this function must be configured as an attribute field.

• Search for stores that are open in a specific period of time.

For example, your document has the open_time field of the INT_ARRAY type, and each 64-bit integer in the array indicates the business hours of a store. The first 32 bits of an integer indicate the opening time of a store, and the last 32 bits of the integer indicate the closing time of the store. If you want to search for stores that are open from 14:00 to 15:30, you can first convert each of the start time and end time to the number of minutes that have elapsed from 00:00 on the same day. In this example, 14:00 is converted to 840, and 15:30 is converted to 930. Then, you can use the following filter clause:

filter=bit_struct(open_time, "0-31,32-63","overlap,$1,$2,840,930")!=-1

• Search for stores that can serve customers to have breakfast, lunch, or dinner. The number of customers that can be served is specified by using a range with the minimum value and maximum value.

For example, your document has the book_info field of the INT_ARRAY type, and each 64-bit integer in the array indicates the booking information of a store. The bits from Bit 0 to Bit 7 indicate the date. The bits from Bit 8 to Bit 15 indicate breakfast, lunch, or dinner. The bits from Bit 16 to Bit 41 indicate the minimum number of customers allowed. The bits from Bit 42 to Bit 63 indicate the maximum number of customers allowed. You can use the following filter clause to search for stores that can serve three to five customers to have dinner tomorrow. The integer 1 in the "equal,$1,1" operation represents tomorrow, and the integer 3 in the "equal,$2,3" operation represents dinner:

filter=bit_struct(book_info,"0-7,8-15,16-41,42-63",
"equal,$1,1","equal,$2,3","overlap,$3,$4,3,5","and,$5,$6,$7")!=-1
// Description:
$1 indicates the value that is represented by the bits from Bit 0 to Bit 7. 
$2 indicates the value that is represented by the bits from Bit 8 to Bit 15.
$3 indicates the value that is represented by the bits from Bit 16 to Bit 41.
$4 indicates the value that is represented by the bits from Bit 42 to Bit 63.
$5 indicates the return value of the "equal,$1,1" operation.
$6 indicates the return value of the "equal,$2,3" operation.
$7 indicates the return value of the "overlap,$3,$4,3,5" operation.
"and,$5,$6,$7" indicates that an AND logical operation is performed on the values represented by $5, $6, and $7. The return value of the bit_struct function indicates the subscript of the array element for which the "and,$5,$6,$7" operation returns true.

• Search for stores that can provide more than 10 commodities and deliver commodities from 14:00 to 15:30. 14:00 is converted to 840, and 15:30 is converted to 930.

To search for such stores, you must set filter conditions based on two fields. The bit_struct function returns an array subscript only for one field. Therefore, you can use the bit_struct function in the multi_attr function to reference two fields of an array type. The multi_attr function can return an array subscript for the other field. In this example, you can use the following query clause:

filter=multi_attr(store, bit_struct(dispatch_time,"0-31,32-63", "equal,$1,840", "equal,$2,930", "and,$3,$4"))>10
// Description:
The dispatch_time field is of the INT_ARRAY type and has multiple values. Each value is a 64-bit integer that indicates the delivery time of a store. You must first convert the time to the number of minutes that have elapsed from 00:00 on the same day. In this example, 14:00 is converted to 840, and 15:30 is converted to 930.
The store field is of the INT_ARRAY type and has multiple values. Each value is a 64-bit integer that indicates the inventory of a store. Each value of the store field corresponds to each value of the dispatch_time field.

Example

In this example, you can generate a 64-bit integer by using the dome calculator in Python. The integer indicates the time period from 08:00 to 18:00.

# Convert the start time to the number of minutes between 00:00 and 08:00.
start=8*60

# Convert the end time to the number of minutes between 00:00 and 18:00.
end=18*60

# Use the first 32 bits of the 64-bit integer to indicate the start time and the last 32 bits to indicate the end time.
# Generate the initial 64-bit integer whose first 32 bits indicate 08:00.
start=start<<32
Print ("First 32 bits",start)#2061584302080

# Generate the final 64-bit integer that uses the first 32 bits to indicate 08:00 and the last 32 bits to indicate 18:00.
result=start|end
print("Result",result)#2061584303160

Results

Principles: The following figures show how 480 and 1080 are converted to binary numbers.

Use the first 32 bits to indicate 480 by performing a left bit shift.

Replace the last 32 bits in the binary number that is generated after the left bit shift with those in the binary number of 1080.

Convert the final binary number into a decimal number. The final binary number is 0000000000000000000000011110000000000000000000000000010000111000.

The decimal number is the same as the result generated by using the dome calculator in Python.

Example:

If you want to check whether the last 32 bits of a value in an array represent a specific number, you can use the following filter clause:

bit_struct(type_arr,"0-31,32-63","equal,$2,40506")!=-1
// Description:
"0-31,32-63": the information about bit positions used to split a value into two parts.
"equal,$2,40506": the operation that checks whether the last 32 bits of a value indicate 40506.