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