FUNCTION bitwise_and, bit_pattern_data, status, danidl_cppcode
; Description: This function performs a bit-wise AND operation between all elements of the input set
; of integers "bit_pattern_data", where each integer represents a pattern of bits that
; are set (or the equivalent binary number). The function returns an integer number
; representing the bit-pattern result. The input parameter "bit_pattern_data" may be a
; scalar, vector, or array.
; This function will use C++ code if possible to achieve a faster execution than the
; default IDL code. The C++ code can be up to ~14.5 times faster than the IDL code in
; this case.
;
; Input Parameters:
;
; bit_pattern_data - BYTE/INTEGER/LONG SCALAR/VECTOR/ARRAY - The set of bit-pattern values, stored
; as integer numbers, that are to be
; combined using the bit-wise AND
; operation.
; status - ANY - A variable which will be used to contain the output status of the function on
; returning (see output parameters below).
; danidl_cppcode - STRING - The full directory path indicating where the DanIDL C++ code is
; installed. The shared library of DanIDL C++ routines should exist
; as "/dist/libDanIDL.so" within the installation.
;
; Output Parameters:
;
; status - INTEGER - If the function successfully processed the input value(s), then "status" is
; returned with a value of "1", otherwise it is returned with a value of "0".
;
; Return Value:
;
; The return value is a SCALAR of the same number type as the input parameter "bit_pattern_data"
; that is the result of performing a bit-wise AND operation between all the elements of
; "bit_pattern_data".
;
; Author: Dan Bramich (dan.bramich@hotmail.co.uk)
;
; History:
;
; 26/11/2011 - Module created (dmb).
;Set the default output parameter values
;Check that "bit_pattern_data" contains numbers of the correct type
;If the input parameter "bit_pattern_data" has only one element, then set the return value of this
;function to the value of the single element of "bit_pattern_data"
;Determine if the shared library of DanIDL C++ routines is installed
;If the shared library of DanIDL C++ routines is installed, then use the C++ code to speed up the
;calculation
;Combine the elements of "bit_pattern_data" using the bit-wise AND operator
;If the shared library of DanIDL C++ routines is not installed, then use the default IDL code
;Use an iterative algorithm employing as many vector operations as possible (for maximum
;calculation efficiency) to combine the elements of "bit_pattern_data" using the bit-wise AND
;operator
;If at least one of the elements still to be combined using the bit-wise AND operator is zero,
;then the result of the combination is also guaranteed to be zero, so break out of the loop
;If the current number of elements still to be combined using the bit-wise AND operator is odd
;Perform a bit-wise AND operation between the first and last element of the current set
;of elements still to be combined
;Perform a bit-wise AND operation between each remaining pair of elements still to be combined
;by employing a vector operation
;If the current number of elements still to be combined using the bit-wise AND operator is even
;Perform a bit-wise AND operation between each pair of elements still to be combined by
;employing a vector operation
;Update the number of elements still to be combined using the bit-wise AND operator
;Extract the bit-pattern result as a scalar value
;Set "status" to "1"
;Return the bit-pattern result