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.

### 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`

IDL prints:

0 1 2 3 4 5 5 5 5 5

0 1 2 3 4 5 5 5 5 5

## Version History

8.0 |
Added NULL keyword. |