WHERE Function

Reference Guide > W Routines > WHERE Function

WHERE Function

Returns a longword vector containing the one-dimensional subscripts of the nonzero elements of the input array.

enabled.

Usage

result = WHERE(array_expr[, count ])

Input Parameters

array_expr — The array to be searched. May be of any data type. Both the real and imaginary parts of complex numbers must be zero for the number to be considered zero.

note	To ignore the imaginary parts of complex numbers, use WHERE(FLOAT(array)) or WHERE(DOUBLE(array)).

Output Parameters

count — (optional) If present, count is converted into a longword integer containing the number of nonzero elements found in array_expr. Must be a named variable.

Returned Value

result — A longword vector containing the one-dimensional subscripts of the nonzero elements of array_expr. The length is equal to the number of nonzero elements in array_expr.

Keywords

None.

Discussion

Frequently the result of WHERE is used as a vector subscript to select elements of an array using given criteria.

As a side effect, the system variable !Err is set to the number of nonzero elements. This is for compatibility with previous versions of PV‑WAVE. Therefore, it is recommended that the Count keyword be used in all new programs, rather than !Err.

Example 1

The WHERE function can be used to select a range of values in an array. For example:

; Create an array with 250 elements.

array = INDGEN(50, 5)

; Get the subscripts of those elements greater than 50 and less

; than 100.

index = WHERE((array GT 50) AND (array LT 100))

; Put the selected values into result.

result = array(index)

Example 2

If all the elements of array_expr are zero, WHERE returns a scalar integer with a value of –1. If you attempt to use this result as an index into another array, you will get an error message about the subscripts being out of bounds. In some situations, code similar to the following can be used to avoid errors:

; Create an array.

array = INDGEN(7, 4)

PM, array

; PV-WAVE prints:

;       0       7      14      21

;       1       8      15      22

;       2       9      16      23

;       3      10      17      24

;       4      11      18      25

;       5      12      19      26

;       6      13      20      27

; Use count to get the number of nonzero elements greater or

; equal to 22.5.

index = WHERE(array GE 22.5, count)

; Only subscript the array if it's safe to do so.

IF (count GT 0) THEN array = array(index)

PM, array

; PV-WAVE prints:

;      23

;      24

;      25

;      26

;      27

Example 3

You can use WHERE to determine where an array of strings matches a specific pattern, or where the array of strings is non-NULL.

s = ['this', 'is', 'an', 'Where', 'of', 'strings']

PRINT, WHERE(s eq 'an')

; PV-WAVE prints: 2

s = ['this', '', '', 'Where', '', 'strings']

PRINT, WHERE(s)

; PV-WAVE prints: 0    3    5