DATAMANIP commands


PROGRAM NAME

kbitxor - Output = Input 1 XOR (Input 2 or Constant)

DESCRIPTION

The bitwise XOR operator performs a bitwise Exclusive OR between each point in Input 1 and either Input 2 or the Constant value, which ever is specified by the user.

Data Type - Single Input The data type of the output object is the same as the input object's data type. Internally, the data is processed using one of the following: unsigned byte, long, unsigned long, double, or double complex. Data will not be cast to a lower type for processing.

Data Type - Two Input Objects The data type of the output object's data is cast to the highest order data type of the input objects' data. Internally, the data is processed using one of the following: unsigned byte, long, unsigned long, double, or double complex. Data is not cast to a lower type for processing.

The bitwise operators will not operate on float or complex data types.

Map Data The bitwise operations have not been written to be fully polymorphic yet. They does not check for map data, and will therefore always operate on the value data, even if a map exists. This will most likely corrupt indexing into the map.

In the case of a single input, it is recommended to use the Copy to Value (kcptoval) segment operator to temporarily move the map data into the value segment, run the bitwise operation on the data, then move it back to the map with the Copy from Value (kcpfromval) operator.

When operating with two input objects, where at least one of the objects contains map data, data should be mapped prior to running the bitwise operator. The Map Data operator (kmapdata) can be used to perform the mapping operation.

Validity Mask - Single Input If there is a validity mask associated with the input object, the mask is transferred to the output object. To decrease processing time, the operation will still be performed on those data that have corresponding mask values equal to zero. If the data under the mask is genuinely fInotfP processable, such as NaN or infinity, the user can specify that a value be substituted in place of the original value when it is accessed. The masked data substitution attributes for a data object can be explicitly set and stored using the fISet AttributefP operator, DATAMANIP::ksetdattr.

Validity Mask - Two Input Objects Masking has not been implemented yet for the bitwise operators. Therefore, only the mask from the first input object will be transferred to the output.

Input Objects of Different Sizes The input objects can be of different sizes. If the sizes are different, the size of the output object's data will be the maximum of the data sizes of the input objects. When resizing, the input data are padded with a constant value that is defined internally by the operation being performed. If the input objects have map data as well as value data, the maximum data size is determined after mapping.

The subobject position for each source object that has value or mask data is used to determine the minimum common subobject position between them. This minimum position, along with the individual subobject positions, is used when calculating the final destination object size. Size and offsets are calculated so that the subobject positions of the source objects are aligned. These changes are applied before the operation is performed.

The resulting subobject position attribute of the destination object will be be the minimum common subobject position described above.

The subobject position attribute of a data object defines the coordinates at which that subobject was located in its parent data object. This attribute may be automatically set by programs such as the Extract operator (DATAMANIP::kextract), or it can be explicitly set by using the Set Data Attributes operator (DATAMANIP::ksetdattr). The subobject position coordinates can be printed using the Print File Information operator (DATAMANIP::kfileinfo).

The value used to pad the data when the input files are not the same size is zero.

Explicit Location and Time Data - Single Input If the input object has time data or location data, it is transferred to the output object.

Explicit Location and Time Data - Two Input Objects The bitwise operations have not been extended to understand location and time data. Therefore, only location and time data present in the first input object will be transferred to the output.

Executing XOR runs the program kbitwise with the -xor flag.

REQUIRED ARGUMENTS

-i1
type: infile
desc: First input data object
-o
type: outfile
desc: Resulting output data object

Mutually Exclusive Group; you must specify ONE of:

-i2
type: infile
desc: Second input data object
default: {none}
OR
-real
type: integer
desc: Constant value
default: 0
bounds: no range checking

OPTIONAL ARGUMENTS

none

EXAMPLES

SEE ALSO

DATAMANIP::kbitwise

RESTRICTIONS

THIS ROUTINE is still under development, and has not been modified to fully support the polymorphic data model. See paragraphs above for discussions concerning the polymorphic data segments.

All processing is currently performed as UNSIGNED long, so the operations may not work properly on negative values.

The bitwise operators will not operate on float or complex data types.

REFERENCES

COPYRIGHT

Copyright (C) 1993 - 1997, Khoral Research, Inc. ("KRI") All rights reserved.