[2] | 1 | ;+ |
---|
| 2 | ; |
---|
[223] | 3 | ; @file_comments |
---|
[133] | 4 | ; Convert an array of selected values to an index |
---|
[223] | 5 | ; array that identifies the selected values in a list or data array. |
---|
[2] | 6 | ; |
---|
[223] | 7 | ; @categories |
---|
| 8 | ; tools |
---|
[2] | 9 | ; |
---|
[223] | 10 | ; @param NAMES {in}{required} |
---|
| 11 | ; A list or array of values to choose from |
---|
[2] | 12 | ; |
---|
[223] | 13 | ; @param SELNAMES {in}{required} |
---|
| 14 | ; A list of selected values |
---|
[2] | 15 | ; |
---|
[223] | 16 | ; @keyword ONLY_VALID |
---|
| 17 | ; Return only indexes of found values. Values not |
---|
| 18 | ; found are skipped. Default is to return 1 index value for |
---|
| 19 | ; each SELNAME, which is -1 if SELNAME is not contained in |
---|
| 20 | ; NAMES. If ONLY_VALID is set, the -1 values will be deleted, |
---|
| 21 | ; and a value of -1 indicates that no SELNAME has been found |
---|
| 22 | ; at all. |
---|
[2] | 23 | ; |
---|
[223] | 24 | ; @keyword REQUIRED |
---|
| 25 | ; Normally, MAKE_SELECTION will return indexes for |
---|
| 26 | ; all values that are found, simply ignoring the selected |
---|
| 27 | ; values that are not in the NAMES array (although an error |
---|
| 28 | ; message is displayed). Set this keyword to return with |
---|
| 29 | ; -1 as soon as a selected value is not found. |
---|
[2] | 30 | ; |
---|
[223] | 31 | ; @keyword QUIET |
---|
| 32 | ; Suppress printing of the error message if a |
---|
| 33 | ; selected value is not found (the error condition will |
---|
| 34 | ; still be set). |
---|
[2] | 35 | ; |
---|
[223] | 36 | ; @returns |
---|
| 37 | ; A (long) array with indexes to reference the selected values |
---|
| 38 | ; in the NAMES array. |
---|
[2] | 39 | ; |
---|
[223] | 40 | ; @restrictions |
---|
| 41 | ; If the NAMES array contains multiple entries of the same value, |
---|
| 42 | ; only the index to the first entry will be returned. |
---|
[2] | 43 | ; |
---|
[223] | 44 | ; A selection can contain multiple instances of the same value. |
---|
| 45 | ; The index array will contain one entry per selected item |
---|
| 46 | ; (See example below) |
---|
| 47 | ; |
---|
| 48 | ; @examples |
---|
| 49 | ; names = [ 'Alfred','Anton','Peter','John','Mary'] |
---|
[133] | 50 | ; index = MAKE_SELECTION(names,['Peter','Mary']) |
---|
| 51 | ; print,index |
---|
| 52 | ; ; prints 2 4 |
---|
[2] | 53 | ; |
---|
[133] | 54 | ; vals = indgen(20) |
---|
| 55 | ; index = MAKE_SELECTION(vals,[9,-5,8,7,7,8,9]) |
---|
| 56 | ; print,index |
---|
| 57 | ; ; prints 9 -1 8 7 7 8 9 |
---|
[2] | 58 | ; |
---|
[133] | 59 | ; index = MAKE_SELECTION(vals,[9,-5,8,7,7,8,9],/ONLY_VALID) |
---|
| 60 | ; print,index |
---|
| 61 | ; ; prints 9 8 7 7 8 9 |
---|
[2] | 62 | ; |
---|
[133] | 63 | ; index = MAKE_SELECTION(vals,[9,-5,8,7,7,8,9],/REQUIRED) |
---|
| 64 | ; print,index |
---|
| 65 | ; ; prints -1 |
---|
[2] | 66 | ; |
---|
[223] | 67 | ; @history |
---|
| 68 | ; mgs, 28 Aug 1998: VERSION 1.00 |
---|
| 69 | ; mgs, 29 Aug 1998: - changed behavior and added ONLY_VALID keyword |
---|
[2] | 70 | ; Copyright (C) 1998, Martin Schultz, Harvard University |
---|
| 71 | ; This software is provided as is without any warranty |
---|
| 72 | ; whatsoever. It may be freely used, copied or distributed |
---|
| 73 | ; for non-commercial purposes. This copyright notice must be |
---|
| 74 | ; kept with any copy of this software. If this software shall |
---|
| 75 | ; be used commercially or sold as part of a larger package, |
---|
| 76 | ; please contact the author to arrange payment. |
---|
[232] | 77 | ; Bugs and comments should be directed to mgs\@io.harvard.edu |
---|
[2] | 78 | ; with subject "IDL routine make_selection" |
---|
[231] | 79 | ; |
---|
| 80 | ; @version |
---|
| 81 | ; $Id$ |
---|
| 82 | ; |
---|
| 83 | ;- |
---|
| 84 | ; |
---|
[262] | 85 | FUNCTION make_selection, names, selnames, $ |
---|
| 86 | ONLY_VALID=only_valid, REQUIRED=required, $ |
---|
| 87 | QUIET=quiet |
---|
[114] | 88 | ; |
---|
| 89 | compile_opt idl2, strictarrsubs |
---|
| 90 | ; |
---|
[223] | 91 | ; return an index array with a number for each element in |
---|
[2] | 92 | ; selnames that is found in names. |
---|
| 93 | ; Set the REQUIRED keyword to return -1 if one element is |
---|
[223] | 94 | ; not found, otherwise -1 will only be returned, if no |
---|
[2] | 95 | ; element is found. |
---|
[223] | 96 | |
---|
[2] | 97 | ; reset error state to 0 |
---|
| 98 | message,/reset |
---|
[223] | 99 | |
---|
[2] | 100 | quiet = keyword_set(quiet) |
---|
| 101 | result = -1L |
---|
[223] | 102 | |
---|
[2] | 103 | for i=0,n_elements(selnames)-1 do begin |
---|
| 104 | test = where(names eq selnames[i]) |
---|
[223] | 105 | result = [ result, test[0] ] |
---|
[2] | 106 | if (test[0] lt 0) then begin |
---|
| 107 | if (keyword_set(ONLY_VALID) OR keyword_set(REQUIRED)) then $ |
---|
| 108 | message,'Selected name not found in names array ('+ $ |
---|
| 109 | strtrim(selnames[i],2)+')!',/CONT,NOPRINT=quiet |
---|
| 110 | if (keyword_set(required)) then return,-1L |
---|
| 111 | endif |
---|
| 112 | endfor |
---|
[223] | 113 | |
---|
[2] | 114 | if (n_elements(result) gt 1) then result = result[1:*] |
---|
| 115 | |
---|
| 116 | if (keyword_set(only_valid)) then begin |
---|
| 117 | ind = where(result ge 0) |
---|
| 118 | if (ind[0] ge 0) then result = result[ind] $ |
---|
| 119 | else result = -1L |
---|
| 120 | endif |
---|
[223] | 121 | |
---|
[2] | 122 | return,result |
---|
[223] | 123 | |
---|
[2] | 124 | end |
---|