|
7017
|
1 @c Copyright (C) 1996, 1997, 1999, 2002, 2004, 2005, 2007 John W. Eaton |
|
7018
|
2 @c |
|
|
3 @c This file is part of Octave. |
|
|
4 @c |
|
|
5 @c Octave is free software; you can redistribute it and/or modify it |
|
|
6 @c under the terms of the GNU General Public License as published by the |
|
|
7 @c Free Software Foundation; either version 3 of the License, or (at |
|
|
8 @c your option) any later version. |
|
|
9 @c |
|
|
10 @c Octave is distributed in the hope that it will be useful, but WITHOUT |
|
|
11 @c ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
|
|
12 @c FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License |
|
|
13 @c for more details. |
|
|
14 @c |
|
|
15 @c You should have received a copy of the GNU General Public License |
|
|
16 @c along with Octave; see the file COPYING. If not, see |
|
|
17 @c <http://www.gnu.org/licenses/>. |
|
3294
|
18 |
|
4167
|
19 @node Tips |
|
3294
|
20 @appendix Tips and Standards |
|
|
21 @cindex tips |
|
|
22 @cindex standards of coding style |
|
|
23 @cindex coding standards |
|
|
24 |
|
|
25 This chapter describes no additional features of Octave. Instead it |
|
|
26 gives advice on making effective use of the features described in the |
|
|
27 previous chapters. |
|
|
28 |
|
|
29 @menu |
|
|
30 * Style Tips:: Writing clean and robust programs. |
|
|
31 * Coding Tips:: Making code run faster. |
|
|
32 * Comment Tips:: Conventions for writing comments. |
|
|
33 * Function Headers:: Standard headers for functions. |
|
6574
|
34 * Documentation Tips:: Writing readable documentation strings. |
|
3294
|
35 @end menu |
|
|
36 |
|
4167
|
37 @node Style Tips |
|
3294
|
38 @section Writing Clean Octave Programs |
|
|
39 |
|
|
40 Here are some tips for avoiding common errors in writing Octave code |
|
|
41 intended for widespread use: |
|
|
42 |
|
|
43 @itemize @bullet |
|
|
44 @item |
|
|
45 Since all global variables share the same name space, and all functions |
|
|
46 share another name space, you should choose a short word to distinguish |
|
|
47 your program from other Octave programs. Then take care to begin the |
|
|
48 names of all global variables, constants, and functions with the chosen |
|
|
49 prefix. This helps avoid name conflicts. |
|
|
50 |
|
|
51 If you write a function that you think ought to be added to Octave under |
|
|
52 a certain name, such as @code{fiddle_matrix}, don't call it by that name |
|
|
53 in your program. Call it @code{mylib_fiddle_matrix} in your program, |
|
5041
|
54 and send mail to @email{maintainers@@octave.org} suggesting that it |
|
3294
|
55 be added to Octave. If and when it is, the name can be changed easily |
|
|
56 enough. |
|
|
57 |
|
|
58 If one prefix is insufficient, your package may use two or three |
|
|
59 alternative common prefixes, so long as they make sense. |
|
|
60 |
|
|
61 Separate the prefix from the rest of the symbol name with an underscore |
|
|
62 @samp{_}. This will be consistent with Octave itself and with most |
|
|
63 Octave programs. |
|
|
64 |
|
|
65 @item |
|
|
66 When you encounter an error condition, call the function @code{error} |
|
|
67 (or @code{usage}). The @code{error} and @code{usage} functions do not |
|
|
68 return. |
|
|
69 @xref{Errors}. |
|
|
70 |
|
|
71 @item |
|
|
72 Please put a copyright notice on the file if you give copies to anyone. |
|
|
73 Use the same lines that appear at the top of the function files |
|
|
74 distributed with Octave. If you have not signed papers to assign the |
|
|
75 copyright to anyone else, then place your name in the copyright notice. |
|
|
76 @end itemize |
|
|
77 |
|
4167
|
78 @node Coding Tips |
|
3294
|
79 @section Tips for Making Code Run Faster. |
|
|
80 @cindex execution speed |
|
|
81 @cindex speedups |
|
|
82 |
|
|
83 Here are some ways of improving the execution speed of Octave programs. |
|
|
84 |
|
|
85 @itemize @bullet |
|
|
86 @item |
|
|
87 Avoid looping wherever possible. |
|
|
88 |
|
|
89 @item |
|
|
90 Use iteration rather than recursion whenever possible. |
|
|
91 Function calls are slow in Octave. |
|
|
92 |
|
|
93 @item |
|
|
94 Avoid resizing matrices unnecessarily. When building a single result |
|
|
95 matrix from a series of calculations, set the size of the result matrix |
|
|
96 first, then insert values into it. Write |
|
|
97 |
|
|
98 @example |
|
|
99 @group |
|
|
100 result = zeros (big_n, big_m) |
|
|
101 for i = over:and_over |
|
|
102 r1 = @dots{} |
|
|
103 r2 = @dots{} |
|
|
104 result (r1, r2) = new_value (); |
|
|
105 endfor |
|
|
106 @end group |
|
|
107 @end example |
|
|
108 |
|
|
109 @noindent |
|
|
110 instead of |
|
|
111 |
|
|
112 @example |
|
|
113 @group |
|
|
114 result = []; |
|
|
115 for i = ever:and_ever |
|
|
116 result = [ result, new_value() ]; |
|
|
117 endfor |
|
|
118 @end group |
|
|
119 @end example |
|
|
120 |
|
|
121 @item |
|
|
122 Avoid calling @code{eval} or @code{feval} whenever possible, because |
|
|
123 they require Octave to parse input or look up the name of a function in |
|
|
124 the symbol table. |
|
|
125 |
|
|
126 If you are using @code{eval} as an exception handling mechanism and not |
|
|
127 because you need to execute some arbitrary text, use the @code{try} |
|
|
128 statement instead. @xref{The try Statement}. |
|
|
129 |
|
|
130 @item |
|
|
131 If you are calling lots of functions but none of them will need to |
|
|
132 change during your run, set the variable |
|
|
133 @code{ignore_function_time_stamp} to @code{"all"} so that Octave doesn't |
|
|
134 waste a lot of time checking to see if you have updated your function |
|
|
135 files. |
|
|
136 @end itemize |
|
|
137 |
|
4167
|
138 @node Comment Tips |
|
3294
|
139 @section Tips on Writing Comments |
|
|
140 |
|
|
141 Here are the conventions to follow when writing comments. |
|
|
142 |
|
|
143 @table @samp |
|
|
144 @item # |
|
|
145 Comments that start with a single sharp-sign, @samp{#}, should all be |
|
|
146 aligned to the same column on the right of the source code. Such |
|
|
147 comments usually explain how the code on the same line does its job. In |
|
|
148 the Emacs mode for Octave, the @kbd{M-;} (@code{indent-for-comment}) |
|
|
149 command automatically inserts such a @samp{#} in the right place, or |
|
|
150 aligns such a comment if it is already present. |
|
|
151 |
|
|
152 @item ## |
|
|
153 Comments that start with two semicolons, @samp{##}, should be aligned to |
|
|
154 the same level of indentation as the code. Such comments usually |
|
|
155 describe the purpose of the following lines or the state of the program |
|
|
156 at that point. |
|
|
157 @end table |
|
|
158 |
|
|
159 @noindent |
|
|
160 The indentation commands of the Octave mode in Emacs, such as @kbd{M-;} |
|
|
161 (@code{indent-for-comment}) and @kbd{TAB} (@code{octave-indent-line}) |
|
|
162 automatically indent comments according to these conventions, |
|
|
163 depending on the number of semicolons. @xref{Comments,, |
|
|
164 Manipulating Comments, emacs, The GNU Emacs Manual}. |
|
|
165 |
|
4167
|
166 @node Function Headers |
|
3294
|
167 @section Conventional Headers for Octave Functions |
|
|
168 @cindex header comments |
|
|
169 |
|
|
170 Octave has conventions for using special comments in function files |
|
|
171 to give information such as who wrote them. This section explains these |
|
|
172 conventions. |
|
|
173 |
|
|
174 The top of the file should contain a copyright notice, followed by a |
|
|
175 block of comments that can be used as the help text for the function. |
|
|
176 Here is an example: |
|
|
177 |
|
|
178 @example |
|
6778
|
179 ## Copyright (C) 1996, 1997, 2007 John W. Eaton |
|
3294
|
180 ## |
|
|
181 ## This file is part of Octave. |
|
|
182 ## |
|
|
183 ## Octave is free software; you can redistribute it and/or |
|
|
184 ## modify it under the terms of the GNU General Public |
|
|
185 ## License as published by the Free Software Foundation; |
|
7016
|
186 ## either version 3 of the License, or (at your option) any later |
|
|
187 ## version. |
|
3294
|
188 ## |
|
|
189 ## Octave is distributed in the hope that it will be useful, |
|
|
190 ## but WITHOUT ANY WARRANTY; without even the implied |
|
|
191 ## warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR |
|
|
192 ## PURPOSE. See the GNU General Public License for more |
|
|
193 ## details. |
|
|
194 ## |
|
|
195 ## You should have received a copy of the GNU General Public |
|
|
196 ## License along with Octave; see the file COPYING. If not, |
|
7016
|
197 ## see <http://www.gnu.org/licenses/>. |
|
3294
|
198 |
|
|
199 ## usage: [IN, OUT, PID] = popen2 (COMMAND, ARGS) |
|
|
200 ## |
|
|
201 ## Start a subprocess with two-way communication. COMMAND |
|
|
202 ## specifies the name of the command to start. ARGS is an |
|
|
203 ## array of strings containing options for COMMAND. IN and |
|
|
204 ## OUT are the file ids of the input and streams for the |
|
|
205 ## subprocess, and PID is the process id of the subprocess, |
|
|
206 ## or -1 if COMMAND could not be executed. |
|
|
207 ## |
|
|
208 ## Example: |
|
|
209 ## |
|
|
210 ## [in, out, pid] = popen2 ("sort", "-nr"); |
|
|
211 ## fputs (in, "these\nare\nsome\nstrings\n"); |
|
|
212 ## fclose (in); |
|
|
213 ## while (isstr (s = fgets (out))) |
|
|
214 ## fputs (stdout, s); |
|
|
215 ## endwhile |
|
|
216 ## fclose (out); |
|
|
217 @end example |
|
|
218 |
|
|
219 Octave uses the first block of comments in a function file that do not |
|
|
220 appear to be a copyright notice as the help text for the file. For |
|
|
221 Octave to recognize the first comment block as a copyright notice, it |
|
6530
|
222 must start with the word `Copyright' after stripping the leading |
|
|
223 comment characters. |
|
3294
|
224 |
|
|
225 After the copyright notice and help text come several @dfn{header |
|
|
226 comment} lines, each beginning with @samp{## @var{header-name}:}. For |
|
|
227 example, |
|
|
228 |
|
|
229 @example |
|
|
230 @group |
|
|
231 ## Author: jwe |
|
|
232 ## Keywords: subprocesses input-output |
|
|
233 ## Maintainer: jwe |
|
|
234 @end group |
|
|
235 @end example |
|
|
236 |
|
|
237 Here is a table of the conventional possibilities for @var{header-name}: |
|
|
238 |
|
|
239 @table @samp |
|
|
240 @item Author |
|
|
241 This line states the name and net address of at least the principal |
|
|
242 author of the library. |
|
|
243 |
|
6670
|
244 @example |
|
3294
|
245 ## Author: John W. Eaton <jwe@@bevo.che.wisc.edu> |
|
6670
|
246 @end example |
|
3294
|
247 |
|
|
248 @item Maintainer |
|
|
249 This line should contain a single name/address as in the Author line, or |
|
|
250 an address only, or the string @samp{jwe}. If there is no maintainer |
|
|
251 line, the person(s) in the Author field are presumed to be the |
|
|
252 maintainers. The example above is mildly bogus because the maintainer |
|
|
253 line is redundant. |
|
|
254 |
|
|
255 The idea behind the @samp{Author} and @samp{Maintainer} lines is to make |
|
|
256 possible a function to ``send mail to the maintainer'' without |
|
|
257 having to mine the name out by hand. |
|
|
258 |
|
|
259 Be sure to surround the network address with @samp{<@dots{}>} if |
|
|
260 you include the person's full name as well as the network address. |
|
|
261 |
|
|
262 @item Created |
|
|
263 This optional line gives the original creation date of the |
|
|
264 file. For historical interest only. |
|
|
265 |
|
|
266 @item Version |
|
|
267 If you wish to record version numbers for the individual Octave program, |
|
|
268 put them in this line. |
|
|
269 |
|
|
270 @item Adapted-By |
|
|
271 In this header line, place the name of the person who adapted the |
|
|
272 library for installation (to make it fit the style conventions, for |
|
|
273 example). |
|
|
274 |
|
|
275 @item Keywords |
|
|
276 This line lists keywords. Eventually, it will be used by an apropos |
|
|
277 command to allow people will find your package when they're looking for |
|
|
278 things by topic area. To separate the keywords, you can use spaces, |
|
|
279 commas, or both. |
|
|
280 @end table |
|
|
281 |
|
|
282 Just about every Octave function ought to have the @samp{Author} and |
|
|
283 @samp{Keywords} header comment lines. Use the others if they are |
|
|
284 appropriate. You can also put in header lines with other header |
|
|
285 names---they have no standard meanings, so they can't do any harm. |
|
6574
|
286 |
|
|
287 @node Documentation Tips |
|
|
288 @section Tips for Documentation Strings |
|
|
289 |
|
|
290 As noted above, documentation is typically in a commented header block |
|
|
291 on an Octave function following the copyright statement. The help string |
|
7001
|
292 shown above is an unformatted string and will be displayed as is by |
|
6574
|
293 Octave. Here are some tips for the writing of documentation strings. |
|
|
294 |
|
|
295 @itemize @bullet |
|
|
296 @item |
|
|
297 Every command, function, or variable intended for users to know about |
|
|
298 should have a documentation string. |
|
|
299 |
|
|
300 @item |
|
|
301 An internal variable or subroutine of an Octave program might as well have |
|
|
302 a documentation string. |
|
|
303 |
|
|
304 @item |
|
|
305 The first line of the documentation string should consist of one or two |
|
|
306 complete sentences that stand on their own as a summary. |
|
|
307 |
|
|
308 The documentation string can have additional lines that expand on the |
|
|
309 details of how to use the function or variable. The additional lines |
|
|
310 should also be made up of complete sentences. |
|
|
311 |
|
|
312 @item |
|
|
313 For consistency, phrase the verb in the first sentence of a |
|
|
314 documentation string as an infinitive with ``to'' omitted. For |
|
|
315 instance, use ``Return the frob of A and B.'' in preference to ``Returns |
|
|
316 the frob of A and B@.'' Usually it looks good to do likewise for the |
|
|
317 rest of the first paragraph. Subsequent paragraphs usually look better |
|
|
318 if they have proper subjects. |
|
|
319 |
|
|
320 @item |
|
|
321 Write documentation strings in the active voice, not the passive, and in |
|
|
322 the present tense, not the future. For instance, use ``Return a list |
|
|
323 containing A and B.'' instead of ``A list containing A and B will be |
|
|
324 returned.'' |
|
|
325 |
|
|
326 @item |
|
|
327 Avoid using the word ``cause'' (or its equivalents) unnecessarily. |
|
|
328 Instead of, ``Cause Octave to display text in boldface,'' write just |
|
|
329 ``Display text in boldface.'' |
|
|
330 |
|
|
331 @item |
|
|
332 Do not start or end a documentation string with whitespace. |
|
|
333 |
|
|
334 @item |
|
|
335 Format the documentation string so that it fits in an Emacs window on an |
|
|
336 80-column screen. It is a good idea for most lines to be no wider than |
|
|
337 60 characters. |
|
|
338 |
|
|
339 However, rather than simply filling the entire documentation string, you |
|
|
340 can make it much more readable by choosing line breaks with care. |
|
|
341 Use blank lines between topics if the documentation string is long. |
|
|
342 |
|
|
343 @item |
|
|
344 @strong{Do not} indent subsequent lines of a documentation string so |
|
|
345 that the text is lined up in the source code with the text of the first |
|
|
346 line. This looks nice in the source code, but looks bizarre when users |
|
|
347 view the documentation. Remember that the indentation before the |
|
|
348 starting double-quote is not part of the string! |
|
|
349 |
|
|
350 @item |
|
|
351 The documentation string for a variable that is a yes-or-no flag should |
|
|
352 start with words such as ``Nonzero means@dots{}'', to make it clear that |
|
|
353 all nonzero values are equivalent and indicate explicitly what zero and |
|
|
354 nonzero mean. |
|
|
355 |
|
|
356 @item |
|
|
357 When a function's documentation string mentions the value of an argument |
|
|
358 of the function, use the argument name in capital letters as if it were |
|
|
359 a name for that value. Thus, the documentation string of the operator |
|
|
360 @code{/} refers to its second argument as @samp{DIVISOR}, because the |
|
|
361 actual argument name is @code{divisor}. |
|
|
362 |
|
|
363 Also use all caps for meta-syntactic variables, such as when you show |
|
|
364 the decomposition of a list or vector into subunits, some of which may |
|
|
365 vary. |
|
|
366 @end itemize |
|
|
367 |
|
|
368 Octave also allows extensive formatting of the help string of functions |
|
|
369 using Texinfo. The effect on the online documentation is relatively |
|
|
370 small, but makes the help string of functions conform to the help of |
|
|
371 Octave's own functions. However, the effect on the appearance of printed |
|
|
372 or online documentation will be greatly improved. |
|
|
373 |
|
|
374 The fundamental building block of Texinfo documentation strings is the |
|
|
375 Texinfo-macro @code{@@deftypefn}, which takes three arguments: The class |
|
|
376 the function is in, its output arguments, and the function's |
|
|
377 signature. Typical classes for functions include @code{Function File} |
|
|
378 for standard Octave functions, and @code{Loadable Function} for |
|
|
379 dynamically linked functions. A skeletal Texinfo documentation string |
|
|
380 therefore looks like this |
|
|
381 |
|
|
382 @example |
|
|
383 @group |
|
|
384 -*- texinfo -*- |
|
|
385 @@deftypefn@{Function File@} @{@@var@{return_value@} = @} function_name (@dots{}) |
|
|
386 @@cindex index term |
|
|
387 Help text in Texinfo format. Code samples should be marked like |
|
|
388 @@code@{sample of code@} and variables should be marked as |
|
|
389 @@var@{variable@}. |
|
|
390 @@seealso@{function2@} |
|
|
391 @@end deftypefn |
|
|
392 @end group |
|
|
393 @end example |
|
|
394 |
|
|
395 This help string must be commented in user functions, or in the help |
|
|
396 string of the @code{DEFUN_DLD} macro for dynamically loadable |
|
|
397 functions. The important aspects of the documentation string are |
|
|
398 |
|
|
399 @table @asis |
|
|
400 @item -*- texinfo -*- |
|
|
401 This string signals Octave that the follow text is in Texinfo format, |
|
|
402 and should be the first part of any help string in Texinfo format. |
|
|
403 @item @@deftypefn@{class@} @dots{} @@end deftypefn |
|
|
404 The entire help string should be enclosed within the block defined by |
|
|
405 deftypefn. |
|
|
406 @item @@cindex index term |
|
|
407 This generates an index entry, and can be useful when the function is |
|
|
408 included as part of a larger piece of documentation. It is ignored |
|
|
409 within Octave's help viewer. |
|
|
410 @item @@var@{variable@} |
|
|
411 All variables should be marked with this macro. The markup of variables |
|
|
412 is then changed appropriately for display. |
|
|
413 @item @@code@{sample of code@} |
|
|
414 All samples of code should be marked with this macro for the same |
|
|
415 reasons as the @@var macro. |
|
|
416 @item @@seealso@{function2@} |
|
|
417 This is a comma separated list of function names that allows cross |
|
|
418 referencing from one function documentation string to another. |
|
|
419 @end table |
|
|
420 |
|
|
421 Texinfo format has been designed to generate output for online viewing |
|
|
422 with text-terminals as well as generating high-quality printed output. |
|
|
423 To these ends, Texinfo has commands which control the diversion of parts |
|
|
424 of the document into a particular output processor. Three formats are |
|
|
425 of importance: info, html and TeX. These are selected with |
|
|
426 |
|
|
427 @example |
|
|
428 @group |
|
|
429 @@ifinfo |
|
|
430 Text area for info only |
|
|
431 @@end ifinfo |
|
|
432 @end group |
|
|
433 @end example |
|
|
434 |
|
|
435 @example |
|
|
436 @group |
|
|
437 @@ifhtml |
|
|
438 Text area for html only |
|
|
439 @@end ifhtml |
|
|
440 @end group |
|
|
441 @end example |
|
|
442 |
|
|
443 @example |
|
|
444 @group |
|
|
445 @@iftex |
|
|
446 @@tex |
|
|
447 text for TeX only |
|
|
448 @@end tex |
|
|
449 @@end iftex |
|
|
450 @end group |
|
|
451 @end example |
|
|
452 |
|
|
453 Note that often TeX output can be used in html documents and so often |
|
|
454 the @code{@@ifhtml} blocks are unnecessary. If no specific output |
|
|
455 processor is chosen, by default, the text goes into all output |
|
|
456 processors. It is usual to have the above blocks in pairs to allow the |
|
|
457 same information to be conveyed in all output formats, but with a |
|
|
458 different markup. |
|
|
459 |
|
|
460 Another important feature of Texinfo that is often used in Octave help |
|
|
461 strings is the @code{@@example} environment. An example of its use is |
|
|
462 |
|
|
463 @example |
|
|
464 @group |
|
|
465 @@example |
|
|
466 @@group |
|
|
467 @@code@{2 * 2@} |
|
|
468 @@result@{@} 4 |
|
|
469 @@end group |
|
|
470 @@end example |
|
|
471 @end group |
|
|
472 @end example |
|
|
473 |
|
|
474 which produces |
|
|
475 |
|
|
476 @example |
|
|
477 @group |
|
|
478 @code{2 * 2} |
|
|
479 @result{} 4 |
|
|
480 @end group |
|
|
481 @end example |
|
|
482 |
|
|
483 The @code{@@group} block prevents the example from being split across a |
|
|
484 page boundary, while the @code{@@result@{@}} macro produces a right |
|
|
485 arrow signifying the result of a command. |
|
|
486 |
|
|
487 In many cases a function has multiple means in which it can be called, |
|
|
488 and the @code{@@deftypefnx} macro can be used to give alternatives. For |
|
|
489 example |
|
|
490 |
|
|
491 @example |
|
|
492 @group |
|
|
493 -*- texinfo -*- |
|
|
494 @@deftypefn@{Function File@} @{@@var@{a@} = @} function_name (@@var@{x@}, @dots{}) |
|
|
495 @@deftypefnx@{Function File@} @{@@var@{a@} = @} function_name (@@var@{y@}, @dots{}) |
|
|
496 Help text in Texinfo format. |
|
|
497 @@end deftypefn |
|
|
498 @end group |
|
|
499 @end example |
|
|
500 |
|
|
501 Many complete examples of Texinfo documentation can be taken from the |
|
|
502 help strings for the Octave functions themselves. A relatively complete |
|
|
503 example of which is the @code{nchoosek} function. The Texinfo |
|
|
504 documentation string of @code{nchoosek} is |
|
|
505 |
|
|
506 @example |
|
|
507 @group |
|
|
508 -*- texinfo -*- |
|
|
509 @@deftypefn @{Function File@} @{@@var@{c@} =@} nchoosek (@@var@{n@}, @@var@{k@}) |
|
|
510 |
|
|
511 Compute the binomial coefficient or all combinations of @@var@{n@}. |
|
|
512 If @@var@{n@} is a scalar then, calculate the binomial coefficient |
|
|
513 of @@var@{n@} and @@var@{k@}, defined as |
|
|
514 |
|
|
515 @@iftex |
|
|
516 @@tex |
|
|
517 $$ |
|
|
518 @{n \choose k@} = @{n (n-1) (n-2) \cdots (n-k+1) \over k!@} |
|
|
519 $$ |
|
|
520 @@end tex |
|
|
521 @@end iftex |
|
|
522 @@ifinfo |
|
|
523 |
|
|
524 @@example |
|
|
525 @@group |
|
|
526 / \ |
|
|
527 | n | n (n-1) (n-2) ... (n-k+1) |
|
|
528 | | = ------------------------- |
|
|
529 | k | k! |
|
|
530 \ / |
|
|
531 @@end group |
|
|
532 @@end example |
|
|
533 @@end ifinfo |
|
|
534 |
|
7001
|
535 If @@var@{n@} is a vector, this generates all combinations of the elements |
|
6574
|
536 of @@var@{n@}, taken @@var@{k@} at a time, one row per combination. The |
|
|
537 resulting @@var@{c@} has size @@code@{[nchoosek (length (@@var@{n@}), |
|
|
538 @@var@{k@}), @@var@{k@}]@}. |
|
|
539 |
|
|
540 @@seealso@{bincoeff@} |
|
|
541 @@end deftypefn |
|
|
542 @end group |
|
|
543 @end example |
|
|
544 |
|
|
545 which demonstrates most of the concepts discussed above. |
|
|
546 @iftex |
|
|
547 This documentation string renders as |
|
|
548 |
|
|
549 @c Note actually use the output of info below rather than try and |
|
|
550 @c reproduce it here to prevent it looking different than how it would |
|
|
551 @c appear with info. |
|
|
552 @example |
|
|
553 @group |
|
|
554 -- Function File: C = nchoosek (N, K) |
|
|
555 Compute the binomial coefficient or all combinations of N. If N |
|
|
556 is a scalar then, calculate the binomial coefficient of N and K, |
|
|
557 defined as |
|
|
558 |
|
|
559 / \ |
|
|
560 | n | n (n-1) (n-2) ... (n-k+1) |
|
|
561 | | = ------------------------- |
|
|
562 | k | k! |
|
|
563 \ / |
|
|
564 |
|
|
565 If N is a vector generate all combinations of the elements of N, |
|
|
566 taken K at a time, one row per combination. The resulting C has |
|
|
567 size `[nchoosek (length (N), K), K]'. |
|
|
568 |
|
|
569 |
|
|
570 See also: bincoeff. |
|
|
571 @end group |
|
|
572 @end example |
|
|
573 |
|
|
574 using info, whereas in a printed documentation using TeX it will appear |
|
|
575 as |
|
|
576 |
|
|
577 @deftypefn {Function File} {@var{c} =} nchoosek (@var{n}, @var{k}) |
|
|
578 |
|
6576
|
579 Compute the binomial coefficient or all combinations of @var{n}. |
|
6574
|
580 If @var{n} is a scalar then, calculate the binomial coefficient |
|
|
581 of @var{n} and @var{k}, defined as |
|
|
582 |
|
|
583 @tex |
|
|
584 $$ |
|
|
585 {n \choose k} = {n (n-1) (n-2) \cdots (n-k+1) \over k!} |
|
|
586 $$ |
|
|
587 @end tex |
|
|
588 |
|
|
589 If @var{n} is a vector generate all combinations of the elements |
|
|
590 of @var{n}, taken @var{k} at a time, one row per combination. The |
|
|
591 resulting @var{c} has size @code{[nchoosek (length (@var{n}), |
|
|
592 @var{k}), @var{k}]}. |
|
|
593 |
|
|
594 @seealso{bincoeff} |
|
|
595 @end deftypefn |
|
|
596 |
|
|
597 @end iftex |
