WHERE

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:

; Use /NULL, if no elements match then array will not be modified:

array[WHERE(array GT 5, /NULL)] = 5

or,

; Use Count to get the number of nonzero elements:

index = WHERE(array GT 5, count)

; Only subscript the array if it is safe:

IF count NE 0 THEN array[index] = 5

Examples

See Additional Examples for more information on using WHERE.

Example 1

; Create an integer array 0,1,2,...9

array = INDGEN(10)

PRINT, 'array = ', array

; Find the subscripts of all elements that are 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

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

; Create an integer array 0,1,2,...9

array = INDGEN(10)

; Change all elements that are greater than 5 to 5

array[WHERE(array GT 5, /NULL)] = 5

PRINT, array

; Change all elements that are greater than 10 to 10.

; Since there are none, WHERE will return !NULL and array will be unchanged:

array[WHERE(array GT 10, /NULL)] = 10

PRINT, array