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

;+
;
; 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 names = [ 'Alfred','Anton','Peter','John','Mary']
;           index = MAKE_SELECTION(names,['Peter','Mary'])
;           print,index
;           ; prints  2  4
;
;           vals = indgen(20)
;           index = MAKE_SELECTION(vals,[9,-5,8,7,7,8,9])
;           print,index
;           ; prints  9  -1  8  7  7  8  9
;
;           index = MAKE_SELECTION(vals,[9,-5,8,7,7,8,9],/ONLY_VALID)
;           print,index
;           ; prints  9  8  7  7  8  9
;
;           index = MAKE_SELECTION(vals,[9,-5,8,7,7,8,9],/REQUIRED)
;           print,index
;           ; prints  -1
;
; @history mgs, 28 Aug 1998: VERSION 1.00
;          mgs, 29 Aug 1998: - changed behavior and added ONLY_VALID keyword
;
; @version $Id$
;
;-
; 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"
;-------------------------------------------------------------


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