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.
Note: When WHERE Returns –1
If the NULL keyword is not set, and all the elements of Array_Expression are zero, then WHERE returns a scalar integer with a value of –1. If you use this result as an index into another array without checking for –1 first, then this will return the last element of the array. To avoid this problem, you should either use /NULL or check the Count argument before indexing. For example:
array[WHERE(array GT 5, /NULL)] = 5
or,
index = WHERE(array GT 5, count)
IF count NE 0 THEN array[index] = 5
Examples
See Additional Examples for more information on using WHERE.
Example 1
array = INDGEN(10)
PRINT, 'array = ', array
B = WHERE(array GT 5, count, COMPLEMENT=B_C, NCOMPLEMENT=count_c)
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
IDL prints:
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
Syntax
Result = WHERE( Array_Expression [, Count]
[, COMPLEMENT=variable]
[, /L64]
[, NCOMPLEMENT=variable]
[, /NULL] )
Return Value
Returns a longword vector containing the subscripts of non-zero array elements matching the specified conditions. If /NULL is set, and no matches are found, then WHERE returns the value !NULL.
Arguments
Array_Expression
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.
Count
A named variable that will receive the number of nonzero elements found in Array_Expression. This value is returned as a longword integer.
Note: The system variable !ERR is set to the number of nonzero elements. This effect is for compatibility with previous versions of IDL and should not be used in new code. Use the COUNT argument to return this value instead.
Keywords
COMPLEMENT
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, or the value !NULL if the NULL keyword is set.
L64
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.
Note: Only 64-bit versions of IDL are capable of creating variables requiring a 64-bit result. Check the value of !VERSION.MEMORY_BITS to see if your IDL is 64-bit or not.
NCOMPLEMENT
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.
NULL
Set this keyword to have WHERE return !NULL instead of -1 when no matches are found. Returning !NULL can be helpful if you want to use the result to index another array without having to check the number of matches.
Thread Pool Keywords
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 !CPU system variable control whether IDL uses the thread pool for a given computation. In addition, you can use the thread pool keywords TPOOL_MAX_ELTS, TPOOL_MIN_ELTS, and TPOOL_NOTHREAD to override the defaults established by !CPU for a single invocation of this routine. See Thread Pool Keywords for details.
Additional Examples
Example 2
array = INDGEN(10)
array[WHERE(array GT 5, /NULL)] = 5
PRINT, array
array[WHERE(array GT 10, /NULL)] = 10
PRINT, array
IDL prints:
0 1 2 3 4 5 5 5 5 5
0 1 2 3 4 5 5 5 5 5
Version History
See Also
ARRAY_INDICES, UNIQ, Conditionally Altering Array Elements