The WHERE function returns a vector that contains the one-dimensional subscripts of the nonzero elements of Array_Expression. The length of the resulting vector is equal to the number of nonzero elements in Array_Expression. Frequently the result of WHERE is used as a vector subscript to select elements of an array using given criteria.
If all the elements of Array_Expression are zero, WHERE returns a scalar integer with a value of -1. Attempting to use this result as an index into another array results in a "subscripts out of bounds" error. In situations where this is possible, code similar to the following can be used to avoid errors:
; Use Count to get the number of nonzero elements: index = WHERE(array, count) ; Only subscript the array if it's safe: IF count NE 0 THEN result = array[index]
Result = WHERE( Array_Expression [, Count] [, COMPLEMENT=variable] [, /L64] [, NCOMPLEMENT=variable] )
Returns a longword vector containing the subscripts of non-zero array elements matching the specified conditions.
The array to be searched. Both the real and imaginary parts of a complex number must be zero for the number to be considered zero.
A named variable that will receive the number of nonzero elements found in Array_Expression. This value is returned as a longword integer.
Set this keyword to a named variable that receives the subscripts of the zero elements of Array_Expression. These are the subscripts that are not returned in Result. Together, Result and COMPLEMENT specify every subscript in Array_Expression. If there are no zero elements in Array_Expression, COMPLEMENT returns a scalar integer with the value -1.
By default, the result of WHERE is 32-bit integer when possible, and 64-bit integer if the number of elements being processed requires it. Set L64 to force 64-bit integers to be returned in all cases.
Set this keyword to a named variable that receives the number of zero elements found in Array_Expression. This value is the number of subscripts that will be returned via the COMPLEMENT keyword if it is specified.
This routine is written to make use of IDL's thread pool, which can increase execution speed on systems with multiple CPUs. The values stored in the
; Create a 10-element integer array where each element is ; set to the value of its subscript: array = INDGEN(10) PRINT, 'array = ', array ; Find the subscripts of all the elements in the array that have ; a value greater than 5: B = WHERE(array GT 5, count, COMPLEMENT=B_C, NCOMPLEMENT=count_c) ; Print how many and which elements met the search criteria: PRINT, 'Number of elements > 5: ', count PRINT, 'Subscripts of elements > 5: ', B PRINT, 'Number of elements <= 5: ', count_c PRINT, 'Subscripts of elements <= 5: ', B_C
array = 0 1 2 3 4 5 6 7 8 9 Number of elements > 5: 4 Subscripts of elements > 5: 6 7 8 9 Number of elements <= 5: 6 Subscripts of elements <= 5: 0 1 2 3 4 5
The WHERE function behaves differently with different kinds of array expressions. For instance, if a relational operator is used to compare an array, A, with a scalar, B, then every element of A is searched for B. However, if a relational operator is used to compare two arrays, C and D, then a comparison is made between each corresponding element (i.e. Ci & Di, Ci+1 & Di+1, etc) of the two arrays. If the two arrays have different lengths then a comparison is only made up to the number of elements for the shorter array. The following example illustrates this behavior:
; Compare array, a, and scalar, b: a = [1,2,3,4,5,5,4,3,2,1] b = 5 PRINT, 'a = ', a PRINT, 'b = ', b result=WHERE(a EQ b) PRINT,'Subscripts of a that equal b: ', result ; Now compare two arrays of different lengths: c = [1,2,3,4,5,5,4,3,2,1] d = [0,2,4] PRINT, 'c = ', c PRINT, 'd = ', d result=WHERE(c EQ d) PRINT, 'Subscripts of c that equal d: ', result
a = 1 2 3 4 5 5 4 3 2 1 b = 5 Subscripts of a that equal b: 4 5 c = 1 2 3 4 5 5 4 3 2 1 d = 0 2 4 Subscripts of c that equal d: 1
Note that WHERE found only one element in the array d that equals an element in array c. This is because only the first three elements of c were searched, since d has only three elements.