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