source: trunk/SRC/Documentation/idldoc_html_output/Matrix/cmset_op.html @ 402

Last change on this file since 402 was 402, checked in by smasson, 15 years ago

update documentation
File size: 12.5 KB
Line 
1
2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
3 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
4
5<!-- Generated by IDLdoc 2.0 -->
6
7<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
8  <head>
9    <title>cmset_op.pro (SAXO Documentation)</title>
10
11   
12    <link rel="stylesheet" type="text/css" media="all" href="./../main_files.css" />
13    <link rel="stylesheet" type="text/css" media="print" href="./../main_files_print.css" />
14   
15
16    <script type="text/javascript">
17      function setTitle() {
18        parent.document.title="cmset_op.pro (SAXO Documentation)";
19      }
20    </script>
21  </head>
22
23  <body onload="setTitle();">
24
25    <div id="navbar_title">
26  <h1>SAXO Documentation</h1>
27</div>
28
29
30<div id="main_navbar">
31
32  <table cellspacing="0">
33    <tr>
34     
35      <td><a href="./../overview.html" title="Overview of library">Overview</a></td>
36     
37
38     
39      <td >Directory</td>
40     
41
42     
43      <td><a href="./../idldoc-categories.html" title="Browse library by category">Categories</a></td>
44     
45
46     
47      <td><a href="./../idldoc-index.html" title="Index of files, routines, and parameters">Index</a></td>
48     
49
50     
51      <td><a href="./../search-page.html" title="Search library">Search</a></td>
52     
53
54      <td id="selected">File</td>
55
56     
57      <td><a href="../../../Matrix//cmset_op.pro" title="Source code of a file">Source</a></td>
58     
59
60     
61      <td><a href="./../idldoc-help.html" title="Help on IDLdoc">Help</a></td>
62     
63
64      <td >Etc</td>
65
66      <td id="flexible">Developer&nbsp;documentation</td>
67    </tr>
68  </table>
69
70</div>
71
72<div id="secondary_navbar">
73
74<a href="cmapply.html">&lt;&lt;prev file</a> | <a href="different.html">next file &gt;&gt;</a>&nbsp;&nbsp;&nbsp;&nbsp;<a href="cmset_op.html" target="_TOP">view single page</a> | <a href="./../index.html" target="_TOP">view frames</a>&nbsp;&nbsp;&nbsp;&nbsp;summary: fields | routine&nbsp;&nbsp;&nbsp;&nbsp;details: <a href="#routine_details">routine</a>
75
76</div>
77
78
79    <div id="container">
80
81      <h1 class="directory"><a href="directory-overview.html">Matrix/</a></h1>
82      <h2 class="pro_file">cmset_op.pro</h2>
83
84      <div id="file_attr">
85        <dl>
86        </dl>
87      </div>
88
89      <div id="file_comments">
90 Simplified version of CMSET_OP_UNIQ which sorts, and takes the
91 "first" value, whatever that may mean.
92
93
94 Performs an AND, OR, or XOR operation between two sets
95
96 Description: SET_OP performs three common operations between two sets. The
97 three supported functions of OP are:
98
99        OP          Meaning
100      'AND' - to find the intersection of A and B;
101      'OR'  - to find the union of A and B;
102      'XOR' - to find the those elements who are members of A or B
103              but not both;
104
105   Sets as defined here is one dimensional array composed of
106   numeric or string types. Comparisons of equality between elements
107   are done using the IDL EQ operator.
108
109   The complements of either set can be taken as well, by using the
110   NOT1 and NOT2 keywords. For example, it may be desirable to find
111   the elements in A but not B, or B but not A (they are different!).
112   The following IDL expressions achieve each of those effects:
113
114      SET = CMSET_OP(A, 'AND', /NOT2, B)   ; A but not B
115      SET = CMSET_OP(/NOT1, A, 'AND', B)   ; B but not A
116
117   Note the distinction between NOT1 and NOT2.  NOT1 refers to the
118   first set (A) and NOT2 refers to the second (B).  Their ordered
119   placement in the calling sequence is entirely optional, but the
120   above ordering makes the logical meaning explicit.
121
122   NOT1 and NOT2 can only be set for the 'AND' operator, and never
123   simultaneously. This is because the results of an operation with
124   'OR' or 'XOR' and any combination of NOTs -- or with 'AND' and
125   both NOTs -- formally cannot produce a defined result.
126
127   The implementation depends on the type of operands. For integer
128   types, a fast technique using HISTOGRAM is used. However, this
129   algorithm becomes inefficient when the dynamic range in the data
130   is large. For those cases, and for other data types, a technique
131   based on SORT() is used. Thus the compute time should scale
132   roughly as (A+B)*ALOG(A+B) or better, rather than (A*B) for the
133   brute force approach. For large arrays this is a significant
134   benefit.
135</div>
136
137     
138
139     
140
141     
142
143     
144
145      <div id="routine_details">
146       
147
148        <div class="routine_details" id="_cmset_op">
149
150          <h2><a class="top" href="#container">top</a>cmset_op <span class="categories">
151 Array
152</span></h2>
153       
154          <p class="header">
155            <span class="result">result = </span>cmset_op(<span class="result"><a href="#_cmset_op_param_a">a</a>, <a href="#_cmset_op_param_op0">op0</a>, <a href="#_cmset_op_param_b">b</a></span>, <a href="#_cmset_op_keyword_NOT1">NOT1</a>=<span class="result">NOT1</span>, <a href="#_cmset_op_keyword_NOT2">NOT2</a>=<span class="result">NOT2</span>, <a href="#_cmset_op_keyword_COUNT">COUNT</a>=<span class="result">COUNT</span>, <a href="#_cmset_op_keyword_EMPTY1">EMPTY1</a>=<span class="result">EMPTY1</span>, <a href="#_cmset_op_keyword_EMPTY2">EMPTY2</a>=<span class="result">EMPTY2</span>, <a href="#_cmset_op_keyword_MAXARRAY">MAXARRAY</a>=<span class="result">MAXARRAY</span>, <a href="#_cmset_op_keyword_INDEX">INDEX</a>=<span class="result">INDEX</span>)</p>
156       
157          <div class="comments">
158</div>
159
160          <h3>Return value</h3><div class="preformat">
161 The resulting set as a one-dimensional array. The set may be
162 represented by either an array of data values (default), or an
163 array of indexes (if INDEX is set). Duplicate elements, if any,
164 are removed, and element order may not be preserved.
165
166 The empty set is represented as a return value of -1L, and COUNT
167 is set to zero. Note that the only way to recognize the empty set
168 is to examine COUNT.
169
170 SEE ALSO:
171
172  SET_UTILS.PRO by RSI
173</div>
174
175         
176            <h3>Parameters</h3>
177       
178           
179            <h4 id="_cmset_op_param_a">a&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
180              <span class="attr">in</span>
181             
182             
183              <span class="attr">required</span>
184             
185             
186             
187             
188            </h4>
189       
190          <div class="comments">
191 The two sets to be operated on. A one dimensional array of
192 either numeric or string type. A and B must be of the same
193 type. Empty sets are permitted, and are either represented
194 as an undefined variable, or by setting EMPTY1 or EMPTY2.
195</div>
196           
197            <h4 id="_cmset_op_param_op0">op0&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
198              <span class="attr">in</span>
199             
200             
201              <span class="attr">required</span>
202             
203              <span class="attr">type:</span> <span class="value">string</span>
204             
205             
206            </h4>
207       
208          <div class="comments">
209 a string, the operation to be performed. Must be one of
210 'AND', 'OR' or 'XOR' (lower or mixed case is permitted).
211 Other operations will cause an error message to be produced.
212</div>
213           
214            <h4 id="_cmset_op_param_b">b&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
215              <span class="attr">in</span>
216             
217             
218              <span class="attr">required</span>
219             
220             
221             
222             
223            </h4>
224       
225          <div class="comments">
226 See A
227</div>
228           
229
230         
231
232         
233
234            <h3>Keywords</h3>
235           
236            <h4 id="_cmset_op_keyword_NOT1">NOT1&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
237             
238             
239             
240             
241             
242             
243             
244             
245            </h4>
246       
247            <div class="comments">
248 If set and OP is 'AND', then the complement of A (for
249 NOT1) or B (for NOT2) will be used in the operation.
250 NOT1 and NOT2 cannot be set simultaneously.
251</div>
252           
253            <h4 id="_cmset_op_keyword_NOT2">NOT2&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
254             
255             
256             
257             
258             
259             
260             
261             
262            </h4>
263       
264            <div class="comments">
265 See NOT1
266</div>
267           
268            <h4 id="_cmset_op_keyword_COUNT">COUNT&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
269             
270             
271             
272             
273             
274             
275             
276             
277            </h4>
278       
279            <div class="comments">
280 upon return, the number of elements in the result set.
281 This is only important when the result set is the empty
282 set, in which case COUNT is set to zero.
283</div>
284           
285            <h4 id="_cmset_op_keyword_EMPTY1">EMPTY1&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
286             
287             
288             
289             
290             
291             
292             
293             
294            </h4>
295       
296            <div class="comments">
297 If set, then A (for EMPTY1) or B (for EMPTY2) are
298 assumed to be the empty set. The actual values
299 passed as A or B are then ignored.
300</div>
301           
302            <h4 id="_cmset_op_keyword_EMPTY2">EMPTY2&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
303             
304             
305             
306             
307             
308             
309             
310             
311            </h4>
312       
313            <div class="comments">
314 See EMPTY1
315</div>
316           
317            <h4 id="_cmset_op_keyword_MAXARRAY">MAXARRAY&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
318             
319             
320             
321             
322             
323             
324             
325             
326            </h4>
327       
328            <div class="comments"></div>
329           
330            <h4 id="_cmset_op_keyword_INDEX">INDEX&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
331             
332             
333             
334             
335             
336             
337             
338             
339            </h4>
340       
341            <div class="comments">
342 if set, then return a list of indexes instead of the array
343 values themselves. The "slower" set operations are always
344 performed in this case.
345
346 The indexes refer to the *combined* array [A,B]. To
347 clarify, in the following call: I = CMSET_OP(..., /INDEX);
348 returned values from 0 to NA-1 refer to A[I], and values
349 from NA to NA+NB-1 refer to B[I-NA].
350</div>
351           
352         
353
354          <h3>Examples</h3><div class="preformat">
355 Utility function, similar to UNIQ, but allowing choice of taking
356 first or last unique element, or non-unique elements.
357 Unfortunately this doesn't work because of implementation dependent
358 versions of the SORT() function.
359
360 function cmset_op_uniq, a, first=first, non=non, count=ct, sort=sortit
361   if n_elements(a) LE 1 then return, 0L
362   sh = (2L*keyword_set(first)-1L)*(-2L*keyword_set(non)+1)
363
364   if keyword_set(sortit) then begin
365       ;; Sort it manually
366       ii = sort(a) & b = a[ii]
367       if keyword_set(non) then wh = where(b EQ shift(b, sh), ct) $
368       else                     wh = where(b NE shift(b, sh), ct)
369       if ct GT 0 then return, ii[wh]
370   endif else begin
371       ;; Use the user's values directly
372       if keyword_set(non) then wh = where(a EQ shift(a, sh), ct) $
373       else                     wh = where(a NE shift(a, sh), ct)
374       if ct GT 0 then return, wh
375   endelse
376
377   if keyword_set(first) then return, 0L else return, n_elements(a)-1
378 end
379
380 Simplified version of CMSET_OP_UNIQ which sorts, and takes the
381 "first" value, whatever that may mean.
382</div>
383          <h3>Version history</h3>
384         
385          <h4>Version</h4><div class="preformat">
386 $Id: cmset_op.pro 372 2008-08-08 12:31:53Z pinsard $
387</div>
388          <h4>History</h4><div class="preformat">
389 Written, CM, 23 Feb 2000
390   Added empty set capability, CM, 25 Feb 2000
391   Documentation clarification, CM 02 Mar 2000
392   Incompatible but more consistent reworking of EMPTY keywords, CM,
393     04 Mar 2000
394   Minor documentation clarifications, CM, 26 Mar 2000
395   Corrected bug in empty_arg special case, CM 06 Apr 2000
396   Add INDEX keyword, CM 31 Jul 2000
397   Clarify INDEX keyword documentation, CM 06 Sep 2000
398   Made INDEX keyword always force SLOW_SET_OP, CM 06 Sep 2000
399   Added CMSET_OP_UNIQ, and ability to select FIRST_UNIQUE or
400     LAST_UNIQUE values, CM, 18 Sep 2000
401   Removed FIRST_UNIQUE and LAST_UNIQUE, and streamlined
402     CMSET_OP_UNIQ until problems with SORT can be understood, CM, 20
403     Sep 2000 (thanks to Ben Tupper)
404   Still trying to get documentation of INDEX and NOT right, CM, 28
405     Sep 2000 (no code changes)
406   Correct bug for AND case, when input sets A and B each only have
407     one unique value, and the values are equal.  CM, 04 Mar 2004
408     (thanks to James B. jbattat at cfa dot harvard dot edu)
409   Add support for the cases where the input data types are mixed,
410      but still compatible; also, attempt to return the same data
411      type that was passed in; CM, 05 Feb 2005
412   Fix bug in type checking (thanks to "marit"), CM, 10 Dec 2005
413   Work around a stupidity in the built-in IDL HISTOGRAM routine,
414      which tries to "help" you by restricting the MIN/MAX to the
415      range of the input variable (thanks to Will Maddox), CM, 16 Jan 2006
416
417   Author: Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
418   craigm@lheamail.gsfc.nasa.gov
419</div>
420         
421         
422         
423         
424         
425         
426         
427       
428         
429         
430         
431         
432         
433         
434         
435       
436          <h3>Statistics</h3>
437          <table class="statistics">
438            <tr><td>McCabe cyclic</td><td>          62</td></tr>
439            <tr><td>McCabe essential</td><td>          12</td></tr>
440            <tr><td>McCabe modular design</td><td>           1</td></tr>
441          </table>
442         
443       
444        </div>
445       
446      </div>
447
448     
449
450      <div id="tagline">Produced by IDLdoc 2.0.</div>
451
452    </div>
453
454  </body>
455</html>
Note: See TracBrowser for help on using the repository browser.