1 | ;+ |
---|
2 | ; |
---|
3 | ; @file_comments |
---|
4 | ; Convert an array of selected values to an index |
---|
5 | ; array that identifies the selected values in a list or data array. |
---|
6 | ; |
---|
7 | ; @categories |
---|
8 | ; tools |
---|
9 | ; |
---|
10 | ; @param NAMES {in}{required} |
---|
11 | ; A list or array of values to choose from |
---|
12 | ; |
---|
13 | ; @param SELNAMES {in}{required} |
---|
14 | ; A list of selected values |
---|
15 | ; |
---|
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. |
---|
23 | ; |
---|
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. |
---|
30 | ; |
---|
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). |
---|
35 | ; |
---|
36 | ; @returns |
---|
37 | ; A (long) array with indexes to reference the selected values |
---|
38 | ; in the NAMES array. |
---|
39 | ; |
---|
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. |
---|
43 | ; |
---|
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 | ; |
---|
50 | ; IDL> names = [ 'Alfred','Anton','Peter','John','Mary'] |
---|
51 | ; IDL> index = MAKE_SELECTION(names,['Peter','Mary']) |
---|
52 | ; IDL> print,index |
---|
53 | ; 2 4 |
---|
54 | ; |
---|
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 |
---|
59 | ; |
---|
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 |
---|
63 | ; |
---|
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 | ; |
---|
73 | ; @history |
---|
74 | ; mgs, 28 Aug 1998: VERSION 1.00 |
---|
75 | ; mgs, 29 Aug 1998: - changed behavior and added ONLY_VALID keyword |
---|
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. |
---|
83 | ; Bugs and comments should be directed to mgs\@io.harvard.edu |
---|
84 | ; with subject "IDL routine make_selection" |
---|
85 | ; |
---|
86 | ; @version |
---|
87 | ; $Id$ |
---|
88 | ; |
---|
89 | ;- |
---|
90 | FUNCTION make_selection, names, selnames, $ |
---|
91 | ONLY_VALID=only_valid, REQUIRED=required, $ |
---|
92 | QUIET=quiet |
---|
93 | ; |
---|
94 | compile_opt idl2, strictarrsubs |
---|
95 | ; |
---|
96 | ; return an index array with a number for each element in |
---|
97 | ; selnames that is found in names. |
---|
98 | ; Set the REQUIRED keyword to return -1 if one element is |
---|
99 | ; not found, otherwise -1 will only be returned, if no |
---|
100 | ; element is found. |
---|
101 | |
---|
102 | ; reset error state to 0 |
---|
103 | message,/reset |
---|
104 | |
---|
105 | quiet = keyword_set(quiet) |
---|
106 | result = -1L |
---|
107 | |
---|
108 | for i=0,n_elements(selnames)-1 do begin |
---|
109 | test = where(names eq selnames[i]) |
---|
110 | result = [ result, test[0] ] |
---|
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 |
---|
118 | |
---|
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 |
---|
126 | |
---|
127 | return,result |
---|
128 | |
---|
129 | end |
---|