[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 |
---|
[2] | 49 | ; |
---|
[372] | 50 | ; IDL> names = [ 'Alfred','Anton','Peter','John','Mary'] |
---|
| 51 | ; IDL> index = MAKE_SELECTION(names,['Peter','Mary']) |
---|
| 52 | ; IDL> print,index |
---|
| 53 | ; 2 4 |
---|
[2] | 54 | ; |
---|
[372] | 55 | ; IDL> vals = indgen(20) |
---|
| 56 | ; IDL> index = MAKE_SELECTION(vals,[9,-5,8,7,7,8,9]) |
---|
| 57 | ; IDL> print,index |
---|
| 58 | ; 9 -1 8 7 7 8 9 |
---|
[2] | 59 | ; |
---|
[372] | 60 | ; IDL> index = MAKE_SELECTION(vals,[9,-5,8,7,7,8,9],/ONLY_VALID) |
---|
| 61 | ; IDL> print,index |
---|
| 62 | ; 9 8 7 7 8 9 |
---|
[2] | 63 | ; |
---|
[372] | 64 | ; IDL> index = MAKE_SELECTION(vals,[9,-5,8,7,7,8,9],/REQUIRED) |
---|
| 65 | ; IDL> print,index |
---|
| 66 | ; -1 |
---|
| 67 | ; |
---|
| 68 | ; IDL> index = MAKE_SELECTION(vals,[9,-5,8,7,7,8,9],/REQUIRED,/QUIET) |
---|
| 69 | ; % MAKE_SELECTION: Selected name not found in names array (-5)! |
---|
| 70 | ; IDL> print,index |
---|
| 71 | ; -1 |
---|
| 72 | ; |
---|
[223] | 73 | ; @history |
---|
| 74 | ; mgs, 28 Aug 1998: VERSION 1.00 |
---|
| 75 | ; mgs, 29 Aug 1998: - changed behavior and added ONLY_VALID keyword |
---|
[2] | 76 | ; Copyright (C) 1998, Martin Schultz, Harvard University |
---|
| 77 | ; This software is provided as is without any warranty |
---|
| 78 | ; whatsoever. It may be freely used, copied or distributed |
---|
| 79 | ; for non-commercial purposes. This copyright notice must be |
---|
| 80 | ; kept with any copy of this software. If this software shall |
---|
| 81 | ; be used commercially or sold as part of a larger package, |
---|
| 82 | ; please contact the author to arrange payment. |
---|
[232] | 83 | ; Bugs and comments should be directed to mgs\@io.harvard.edu |
---|
[2] | 84 | ; with subject "IDL routine make_selection" |
---|
[231] | 85 | ; |
---|
| 86 | ; @version |
---|
| 87 | ; $Id$ |
---|
| 88 | ; |
---|
| 89 | ;- |
---|
[262] | 90 | FUNCTION make_selection, names, selnames, $ |
---|
| 91 | ONLY_VALID=only_valid, REQUIRED=required, $ |
---|
| 92 | QUIET=quiet |
---|
[114] | 93 | ; |
---|
| 94 | compile_opt idl2, strictarrsubs |
---|
| 95 | ; |
---|
[223] | 96 | ; return an index array with a number for each element in |
---|
[2] | 97 | ; selnames that is found in names. |
---|
| 98 | ; Set the REQUIRED keyword to return -1 if one element is |
---|
[223] | 99 | ; not found, otherwise -1 will only be returned, if no |
---|
[2] | 100 | ; element is found. |
---|
[223] | 101 | |
---|
[2] | 102 | ; reset error state to 0 |
---|
| 103 | message,/reset |
---|
[223] | 104 | |
---|
[2] | 105 | quiet = keyword_set(quiet) |
---|
| 106 | result = -1L |
---|
[223] | 107 | |
---|
[2] | 108 | for i=0,n_elements(selnames)-1 do begin |
---|
| 109 | test = where(names eq selnames[i]) |
---|
[223] | 110 | result = [ result, test[0] ] |
---|
[2] | 111 | if (test[0] lt 0) then begin |
---|
| 112 | if (keyword_set(ONLY_VALID) OR keyword_set(REQUIRED)) then $ |
---|
| 113 | message,'Selected name not found in names array ('+ $ |
---|
| 114 | strtrim(selnames[i],2)+')!',/CONT,NOPRINT=quiet |
---|
| 115 | if (keyword_set(required)) then return,-1L |
---|
| 116 | endif |
---|
| 117 | endfor |
---|
[223] | 118 | |
---|
[2] | 119 | if (n_elements(result) gt 1) then result = result[1:*] |
---|
| 120 | |
---|
| 121 | if (keyword_set(only_valid)) then begin |
---|
| 122 | ind = where(result ge 0) |
---|
| 123 | if (ind[0] ge 0) then result = result[ind] $ |
---|
| 124 | else result = -1L |
---|
| 125 | endif |
---|
[223] | 126 | |
---|
[2] | 127 | return,result |
---|
[223] | 128 | |
---|
[2] | 129 | end |
---|