source: trunk/SRC/Matrix/make_selection.pro @ 378

;+
;
; @file_comments
; Convert an array of selected values to an index
; array that identifies the selected values in a list or data array.
;
; @categories
; tools
;
; @param NAMES {in}{required}
; A list or array of values to choose from
;
; @param SELNAMES {in}{required}
; A list of selected values
;
; @keyword ONLY_VALID
; Return only indexes of found values. Values not
; found are skipped. Default is to return 1 index value for
; each SELNAME, which is -1 if SELNAME is not contained in
; NAMES. If ONLY_VALID is set, the -1 values will be deleted,
; and a value of -1 indicates that no SELNAME has been found
; at all.
;
; @keyword REQUIRED
; Normally, MAKE_SELECTION will return indexes for
; all values that are found, simply ignoring the selected
; values that are not in the NAMES array (although an error
; message is displayed). Set this keyword to return with
; -1 as soon as a selected value is not found.
;
; @keyword QUIET
; Suppress printing of the error message if a
; selected value is not found (the error condition will
; still be set).
;
; @returns
; A (long) array with indexes to reference the selected values
; in the NAMES array.
;
; @restrictions
; If the NAMES array contains multiple entries of the same value,
; only the index to the first entry will be returned.
;
; A selection can contain multiple instances of the same value.
; The index array will contain one entry per selected item
; (See example below)
;
; @examples
;
;   IDL> names = [ 'Alfred','Anton','Peter','John','Mary']
;   IDL> index = MAKE_SELECTION(names,['Peter','Mary'])
;   IDL> print,index
;   2  4
;
;   IDL> vals = indgen(20)
;   IDL> index = MAKE_SELECTION(vals,[9,-5,8,7,7,8,9])
;   IDL> print,index
;   9  -1  8  7  7  8  9
;
;   IDL> index = MAKE_SELECTION(vals,[9,-5,8,7,7,8,9],/ONLY_VALID)
;   IDL> print,index
;   9  8  7  7  8  9
;
;   IDL> index = MAKE_SELECTION(vals,[9,-5,8,7,7,8,9],/REQUIRED)
;   IDL> print,index
;   -1
;
;   IDL> index = MAKE_SELECTION(vals,[9,-5,8,7,7,8,9],/REQUIRED,/QUIET)
;   % MAKE_SELECTION: Selected name not found in names array (-5)!
;   IDL> print,index
;   -1
;
; @history
; mgs, 28 Aug 1998: VERSION 1.00
; mgs, 29 Aug 1998: - changed behavior and added ONLY_VALID keyword
; Copyright (C) 1998, Martin Schultz, Harvard University
; This software is provided as is without any warranty
; whatsoever. It may be freely used, copied or distributed
; for non-commercial purposes. This copyright notice must be
; kept with any copy of this software. If this software shall
; be used commercially or sold as part of a larger package,
; please contact the author to arrange payment.
; Bugs and comments should be directed to mgs\@io.harvard.edu
; with subject "IDL routine make_selection"
;
; @version
; $Id$
;
;-
FUNCTION make_selection, names, selnames,  $
            ONLY_VALID=only_valid, REQUIRED=required,  $
            QUIET=quiet
;
  compile_opt idl2, strictarrsubs
;
    ; return an index array with a number for each element in
    ; selnames that is found in names.
    ; Set the REQUIRED keyword to return -1 if one element is
    ; not found, otherwise -1 will only be returned, if no
    ; element is found.

    ; reset error state to 0
    message,/reset

    quiet = keyword_set(quiet)
    result = -1L

    for i=0,n_elements(selnames)-1 do begin
       test = where(names eq selnames[i])
       result = [ result, test[0] ]
       if (test[0] lt 0) then begin
           if (keyword_set(ONLY_VALID) OR keyword_set(REQUIRED)) then $
              message,'Selected name not found in names array ('+ $
                      strtrim(selnames[i],2)+')!',/CONT,NOPRINT=quiet
           if (keyword_set(required)) then return,-1L
       endif
    endfor

    if (n_elements(result) gt 1) then result = result[1:*]

    if (keyword_set(only_valid)) then begin
        ind = where(result ge 0)
        if (ind[0] ge 0) then result = result[ind] $
        else result = -1L
    endif

    return,result

end