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