spv-file-format: Fix typo.
[pspp] / doc / expressions.texi
1 @c Use @func when refering to a function.
2 @c Use @deftypefn for their definitions 
3 @macro func{NAME}
4 @code{/NAME/}
5 @end macro
6
7 @node Expressions
8 @chapter Mathematical Expressions
9 @cindex expressions, mathematical
10 @cindex mathematical expressions
11
12 Expressions share a common syntax each place they appear in @pspp{}
13 commands.  Expressions are made up of @dfn{operands}, which can be
14 numbers, strings, or variable names, separated by @dfn{operators}.
15 There are five types of operators: grouping, arithmetic, logical,
16 relational, and functions.
17
18 Every operator takes one or more operands as input and yields exactly
19 one result as output.  Depending on the operator, operands accept
20 strings or numbers as operands.  With few exceptions, operands may be
21 full-fledged expressions in themselves.
22
23 @menu
24 * Boolean Values::                 Boolean values
25 * Missing Values in Expressions::  Using missing values in expressions
26 * Grouping Operators::             parentheses
27 * Arithmetic Operators::           add sub mul div pow
28 * Logical Operators::              AND NOT OR
29 * Relational Operators::           EQ GE GT LE LT NE
30 * Functions::                      More-sophisticated operators
31 * Order of Operations::            Operator precedence
32 @end menu
33
34 @node Boolean Values
35 @section Boolean Values
36 @cindex Boolean
37 @cindex values, Boolean
38
39 Some @pspp{} operators and expressions work with Boolean values, which
40 represent true/false conditions.  Booleans have only three possible
41 values: 0 (false), 1 (true), and system-missing (unknown).
42 System-missing is neither true nor false and indicates that the true
43 value is unknown.
44
45 Boolean-typed operands or function arguments must take on one of these
46 three values.  Other values are considered false, but provoke a warning
47 when the expression is evaluated.
48
49 Strings and Booleans are not compatible, and neither may be used in
50 place of the other.
51
52 @node Missing Values in Expressions
53 @section Missing Values in Expressions
54
55 Most numeric operators yield system-missing when given any
56 system-missing operand.  A string operator given any system-missing
57 operand typically results in the empty string.  Exceptions are listed
58 under particular operator descriptions.
59
60 String user-missing values are not treated specially in expressions.
61
62 User-missing values for numeric variables are always transformed into
63 the system-missing value, except inside the arguments to the
64 @code{VALUE} and @code{SYSMIS} functions.
65
66 The missing-value functions can be used to precisely control how missing
67 values are treated in expressions.  @xref{Missing Value Functions}, for
68 more details.
69
70 @node Grouping Operators
71 @section Grouping Operators
72 @cindex parentheses
73 @cindex @samp{(  )}
74 @cindex grouping operators
75 @cindex operators, grouping
76
77 Parentheses (@samp{()}) are the grouping operators.  Surround an
78 expression with parentheses to force early evaluation.
79
80 Parentheses also surround the arguments to functions, but in that
81 situation they act as punctuators, not as operators.
82
83 @node Arithmetic Operators
84 @section Arithmetic Operators
85 @cindex operators, arithmetic
86 @cindex arithmetic operators
87
88 The arithmetic operators take numeric operands and produce numeric
89 results.
90
91 @table @code
92 @cindex @samp{+}
93 @cindex addition
94 @item @var{a} + @var{b}
95 Yields the sum of @var{a} and @var{b}.
96
97 @cindex @samp{-}
98 @cindex subtraction
99 @item @var{a} - @var{b}
100 Subtracts @var{b} from @var{a} and yields the difference.
101
102 @cindex @samp{*}
103 @cindex multiplication
104 @item @var{a} * @var{b}
105 Yields the product of @var{a} and @var{b}.  If either @var{a} or
106 @var{b} is 0, then the result is 0, even if the other operand is
107 missing.
108
109 @cindex @samp{/}
110 @cindex division
111 @item @var{a} / @var{b}
112 Divides @var{a} by @var{b} and yields the quotient.  If @var{a} is 0,
113 then the result is 0, even if @var{b} is missing.  If @var{b} is zero,
114 the result is system-missing.
115
116 @cindex @samp{**}
117 @cindex exponentiation
118 @item @var{a} ** @var{b}
119 Yields the result of raising @var{a} to the power @var{b}.  If
120 @var{a} is negative and @var{b} is not an integer, the result is
121 system-missing.  The result of @code{0**0} is system-missing as well.
122
123 @cindex @samp{-}
124 @cindex negation
125 @item - @var{a}
126 Reverses the sign of @var{a}.  
127 @end table
128
129 @node Logical Operators
130 @section Logical Operators
131 @cindex logical operators
132 @cindex operators, logical
133
134 @cindex true
135 @cindex false
136 @cindex Boolean
137 @cindex values, system-missing
138 @cindex system-missing
139 The logical operators take logical operands and produce logical
140 results, meaning ``true or false.''  Logical operators are
141 not true Boolean operators because they may also result in a
142 system-missing value.  @xref{Boolean Values}, for more information.
143
144 @table @code
145 @cindex @code{AND}
146 @cindex @samp{&}
147 @cindex intersection, logical
148 @cindex logical intersection
149 @item @var{a} AND @var{b}
150 @itemx @var{a} & @var{b}
151 True if both @var{a} and @var{b} are true, false otherwise.  If one
152 operand is false, the result is false even if the other is missing.  If
153 both operands are missing, the result is missing.
154
155 @cindex @code{OR}
156 @cindex @samp{|}
157 @cindex union, logical
158 @cindex logical union
159 @item @var{a} OR @var{b}
160 @itemx @var{a} | @var{b}
161 True if at least one of @var{a} and @var{b} is true.  If one operand is
162 true, the result is true even if the other operand is missing.  If both
163 operands are missing, the result is missing.
164
165 @cindex @code{NOT}
166 @cindex @samp{~}
167 @cindex inversion, logical
168 @cindex logical inversion
169 @item NOT @var{a}
170 @itemx ~ @var{a}
171 True if @var{a} is false.  If the operand is missing, then the result
172 is missing.
173 @end table
174
175 @node Relational Operators
176 @section Relational Operators
177
178 The relational operators take numeric or string operands and produce Boolean
179 results.
180
181 Strings cannot be compared to numbers.  When strings of different
182 lengths are compared, the shorter string is right-padded with spaces
183 to match the length of the longer string.
184
185 The results of string comparisons, other than tests for equality or
186 inequality, depend on the character set in use.  String comparisons
187 are case-sensitive.
188
189 @table @code
190 @cindex equality, testing
191 @cindex testing for equality
192 @cindex @code{EQ}
193 @cindex @samp{=}
194 @item @var{a} EQ @var{b}
195 @itemx @var{a} = @var{b}
196 True if @var{a} is equal to @var{b}.
197
198 @cindex less than or equal to
199 @cindex @code{LE}
200 @cindex @code{<=}
201 @item @var{a} LE @var{b}
202 @itemx @var{a} <= @var{b}
203 True if @var{a} is less than or equal to @var{b}.
204
205 @cindex less than
206 @cindex @code{LT}
207 @cindex @code{<}
208 @item @var{a} LT @var{b}
209 @itemx @var{a} < @var{b}
210 True if @var{a} is less than @var{b}.
211
212 @cindex greater than or equal to
213 @cindex @code{GE}
214 @cindex @code{>=}
215 @item @var{a} GE @var{b}
216 @itemx @var{a} >= @var{b}
217 True if @var{a} is greater than or equal to @var{b}.
218
219 @cindex greater than
220 @cindex @code{GT}
221 @cindex @samp{>}
222 @item @var{a} GT @var{b}
223 @itemx @var{a} > @var{b}
224 True if @var{a} is greater than @var{b}.
225
226 @cindex inequality, testing
227 @cindex testing for inequality
228 @cindex @code{NE}
229 @cindex @code{~=}
230 @cindex @code{<>}
231 @item @var{a} NE @var{b}
232 @itemx @var{a} ~= @var{b}
233 @itemx @var{a} <> @var{b}
234 True if @var{a} is not equal to @var{b}.
235 @end table
236
237 @node Functions
238 @section Functions
239 @cindex functions
240
241 @cindex mathematics
242 @cindex operators
243 @cindex parentheses
244 @cindex @code{(}
245 @cindex @code{)}
246 @cindex names, of functions
247 @pspp{} functions provide mathematical abilities above and beyond
248 those possible using simple operators.  Functions have a common
249 syntax: each is composed of a function name followed by a left
250 parenthesis, one or more arguments, and a right parenthesis.
251
252 Function names are not reserved.  Their names are specially treated
253 only when followed by a left parenthesis, so that @samp{EXP(10)}
254 refers to the constant value @math{e} raised to the 10th power, but
255 @samp{EXP} by itself refers to the value of a variable called @code{EXP}.
256
257 The sections below describe each function in detail.
258
259 @menu
260 * Mathematics::                 EXP LG10 LN LNGAMMA SQRT
261 * Miscellaneous Mathematics::   ABS MOD MOD10 RND TRUNC
262 * Trigonometry::                ACOS ARCOS ARSIN ARTAN ASIN ATAN COS SIN TAN
263 * Missing Value Functions::     MISSING NMISS NVALID SYSMIS VALUE
264 * Set Membership::              ANY RANGE
265 * Statistical Functions::       CFVAR MAX MEAN MIN SD SUM VARIANCE
266 * String Functions::            CONCAT INDEX LENGTH LOWER LPAD LTRIM NUMBER 
267                                 RINDEX RPAD RTRIM STRING SUBSTR UPCASE
268 * Time and Date::               CTIME.xxx DATE.xxx TIME.xxx XDATE.xxx
269                                 DATEDIFF DATESUM
270 * Miscellaneous Functions::     LAG YRMODA VALUELABEL
271 * Statistical Distribution Functions::  PDF CDF SIG IDF RV NPDF NCDF
272 @end menu
273
274 @node Mathematics
275 @subsection Mathematical Functions
276 @cindex mathematics, advanced
277
278 Advanced mathematical functions take numeric arguments and produce
279 numeric results.
280
281 @deftypefn {Function} {} EXP (@var{exponent})
282 Returns @math{e} (approximately 2.71828) raised to power @var{exponent}.
283 @end deftypefn
284
285 @cindex logarithms
286 @deftypefn {Function} {} LG10 (@var{number})
287 Takes the base-10 logarithm of @var{number}.  If @var{number} is
288 not positive, the result is system-missing.
289 @end deftypefn
290
291 @deftypefn {Function} {} LN (@var{number})
292 Takes the base-@math{e} logarithm of @var{number}.  If @var{number} is
293 not positive, the result is system-missing.
294 @end deftypefn
295
296 @deftypefn {Function} {} LNGAMMA (@var{number})
297 Yields the base-@math{e} logarithm of the complete gamma of @var{number}.
298 If @var{number} is a negative integer, the result is system-missing.
299 @end deftypefn
300
301 @cindex square roots
302 @deftypefn {Function} {} SQRT (@var{number})
303 Takes the square root of @var{number}.  If @var{number} is negative,
304 the result is system-missing.
305 @end deftypefn
306
307 @node Miscellaneous Mathematics
308 @subsection Miscellaneous Mathematical Functions
309 @cindex mathematics, miscellaneous
310
311 Miscellaneous mathematical functions take numeric arguments and produce
312 numeric results.
313
314 @cindex absolute value
315 @deftypefn {Function} {} ABS (@var{number})
316 Results in the absolute value of @var{number}.
317 @end deftypefn
318
319 @cindex modulus
320 @deftypefn {Function} {} MOD (@var{numerator}, @var{denominator})
321 Returns the remainder (modulus) of @var{numerator} divided by
322 @var{denominator}.  If @var{numerator} is 0, then the result is 0,
323 even if @var{denominator} is missing.  If @var{denominator} is 0, the
324 result is system-missing.
325 @end deftypefn
326
327 @cindex modulus, by 10
328 @deftypefn {Function} {} MOD10 (@var{number})
329 Returns the remainder when @var{number} is divided by 10.  If
330 @var{number} is negative, MOD10(@var{number}) is negative or zero.
331 @end deftypefn
332
333 @cindex rounding
334 @deftypefn {Function} {} RND (@var{number} [, @var{mult}[, @var{fuzzbits}]])
335 Rounds @var{number} and rounds it to a multiple of @var{mult} (by
336 default 1).  Halves are rounded away from zero, as are values that
337 fall short of halves by less than @var{fuzzbits} of errors in the
338 least-significant bits of @var{number}.  If @var{fuzzbits} is not
339 specified then the default is taken from SET FUZZBITS (@pxref{SET
340 FUZZBITS}), which is 6 unless overridden.
341 @end deftypefn
342
343 @cindex truncation
344 @deftypefn {Function} {} TRUNC (@var{number})
345 Discards the fractional part of @var{number}; that is, rounds
346 @var{number} towards zero.
347 @end deftypefn
348
349 @node Trigonometry
350 @subsection Trigonometric Functions
351 @cindex trigonometry
352
353 Trigonometric functions take numeric arguments and produce numeric
354 results.
355
356 @cindex arccosine
357 @cindex inverse cosine
358 @deftypefn {Function} {} ARCOS (@var{number})
359 @deftypefnx {Function} {} ACOS (@var{number})
360 Takes the arccosine, in radians, of @var{number}.  Results in
361 system-missing if @var{number} is not between -1 and 1 inclusive.
362 This function is a @pspp{} extension.
363 @end deftypefn
364
365 @cindex arcsine
366 @cindex inverse sine
367 @deftypefn {Function} {} ARSIN (@var{number})
368 @deftypefnx {Function} {} ASIN (@var{number})
369 Takes the arcsine, in radians, of @var{number}.  Results in
370 system-missing if @var{number} is not between -1 and 1 inclusive.
371 @end deftypefn
372
373 @cindex arctangent
374 @cindex inverse tangent
375 @deftypefn {Function} {} ARTAN (@var{number})
376 @deftypefnx {Function} {} ATAN (@var{number})
377 Takes the arctangent, in radians, of @var{number}.
378 @end deftypefn
379
380 @cindex cosine
381 @deftypefn {Function} {} COS (@var{angle})
382 Takes the cosine of @var{angle} which should be in radians.
383 @end deftypefn
384
385 @cindex sine
386 @deftypefn {Function} {} SIN (@var{angle})
387 Takes the sine of @var{angle} which should be in radians.
388 @end deftypefn
389
390 @cindex tangent
391 @deftypefn {Function} {} TAN (@var{angle})
392 Takes the tangent of @var{angle} which should be in radians.
393 Results in system-missing at values
394 of @var{angle} that are too close to odd multiples of @math{\pi/2}.
395 Portability: none.
396 @end deftypefn
397
398 @node Missing Value Functions
399 @subsection Missing-Value Functions
400 @cindex missing values
401 @cindex values, missing
402 @cindex functions, missing-value
403
404 Missing-value functions take various numeric arguments and yield
405 various types of results.  Except where otherwise stated below, the
406 normal rules of evaluation apply within expression arguments to these
407 functions.  In particular, user-missing values for numeric variables
408 are converted to system-missing values.
409
410 @deftypefn {Function} {} MISSING (@var{expr})
411 Returns 1 if @var{expr} has the system-missing value, 0 otherwise.
412 @end deftypefn
413
414 @deftypefn {Function} {} NMISS (@var{expr} [, @var{expr}]@dots{})
415 Each argument must be a numeric expression.  Returns the number of
416 system-missing values in the list, which may include variable ranges
417 using the @code{@var{var1} TO @var{var2}} syntax.
418 @end deftypefn
419
420 @deftypefn {Function} {} NVALID (@var{expr} [, @var{expr}]@dots{})
421 Each argument must be a numeric expression.  Returns the number of
422 values in the list that are not system-missing.  The list may include
423 variable ranges using the @code{@var{var1} TO @var{var2}} syntax.
424 @end deftypefn
425
426 @deftypefn {Function} {} SYSMIS (@var{expr})
427 When @var{expr} is simply the name of a numeric variable, returns 1 if
428 the variable has the system-missing value, 0 if it is user-missing or
429 not missing.  If given @var{expr} takes another form, results in 1 if
430 the value is system-missing, 0 otherwise.
431 @end deftypefn
432
433 @deftypefn {Function} {} VALUE (@var{variable})
434 Prevents the user-missing values of @var{variable} from being
435 transformed into system-missing values, and always results in the
436 actual value of @var{variable}, whether it is valid, user-missing, or
437 system-missing.
438 @end deftypefn
439
440 @node Set Membership
441 @subsection Set-Membership Functions
442 @cindex set membership
443 @cindex membership, of set
444
445 Set membership functions determine whether a value is a member of a set.
446 They take a set of numeric arguments or a set of string arguments, and
447 produce Boolean results.
448
449 String comparisons are performed according to the rules given in
450 @ref{Relational Operators}.
451
452 @deftypefn {Function} {} ANY (@var{value}, @var{set} [, @var{set}]@dots{})
453 Results in true if @var{value} is equal to any of the @var{set}
454 values.  Otherwise, results in false.  If @var{value} is
455 system-missing, returns system-missing.  System-missing values in
456 @var{set} do not cause @func{ANY} to return system-missing.
457 @end deftypefn
458
459 @deftypefn {Function} {} RANGE (@var{value}, @var{low}, @var{high} [, @var{low}, @var{high}]@dots{})
460 Results in true if @var{value} is in any of the intervals bounded by
461 @var{low} and @var{high} inclusive.  Otherwise, results in false.
462 Each @var{low} must be less than or equal to its corresponding
463 @var{high} value.  @var{low} and @var{high} must be given in pairs.
464 If @var{value} is system-missing, returns system-missing.
465 System-missing values in @var{set} do not cause @func{RANGE} to return
466 system-missing.
467 @end deftypefn
468
469 @node Statistical Functions
470 @subsection Statistical Functions
471 @cindex functions, statistical
472 @cindex statistics
473
474 Statistical functions compute descriptive statistics on a list of
475 values.  Some statistics can be computed on numeric or string values;
476 other can only be computed on numeric values.  Their results have the
477 same type as their arguments.  The current case's weighting factor
478 (@pxref{WEIGHT}) has no effect on statistical functions.
479
480 These functions' argument lists may include entire ranges of variables
481 using the @code{@var{var1} TO @var{var2}} syntax.
482
483 @cindex arguments, minimum valid
484 @cindex minimum valid number of arguments
485 Unlike most functions, statistical functions can return non-missing
486 values even when some of their arguments are missing.  Most
487 statistical functions, by default, require only 1 non-missing value to
488 have a non-missing return, but @func{CFVAR}, @func{SD}, and @func {VARIANCE} require 2.
489 These defaults can be increased (but not decreased) by appending a dot
490 and the minimum number of valid arguments to the function name.  For
491 example, @subcmd{MEAN.3(X, Y, Z)} would only return non-missing if all
492 of @samp{X}, @samp{Y}, and @samp{Z} were valid.
493
494 @cindex coefficient of variation
495 @cindex variation, coefficient of
496 @deftypefn {Function} {} CFVAR (@var{number}, @var{number}[, @dots{}])
497 Results in the coefficient of variation of the values of @var{number}.
498 (The coefficient of variation is the standard deviation divided by the
499 mean.)
500 @end deftypefn
501
502 @cindex maximum
503 @deftypefn {Function} {} MAX (@var{value}, @var{value}[, @dots{}])
504 Results in the value of the greatest @var{value}.  The @var{value}s may
505 be numeric or string.
506 @end deftypefn
507
508 @cindex mean
509 @deftypefn {Function} {} MEAN (@var{number}, @var{number}[, @dots{}])
510 Results in the mean of the values of @var{number}.
511 @end deftypefn
512
513 @cindex minimum
514 @deftypefn {Function} {} MIN (@var{number}, @var{number}[, @dots{}])
515 Results in the value of the least @var{value}.  The @var{value}s may
516 be numeric or string.
517 @end deftypefn
518
519 @cindex standard deviation
520 @cindex deviation, standard
521 @deftypefn {Function} {} SD (@var{number}, @var{number}[, @dots{}])
522 Results in the standard deviation of the values of @var{number}.
523 @end deftypefn
524
525 @cindex sum
526 @deftypefn {Function} {} SUM (@var{number}, @var{number}[, @dots{}])
527 Results in the sum of the values of @var{number}.
528 @end deftypefn
529
530 @cindex variance
531 @deftypefn {Function} {} VARIANCE (@var{number}, @var{number}[, @dots{}])
532 Results in the variance of the values of @var{number}.
533 @end deftypefn
534
535 @node String Functions
536 @subsection String Functions
537 @cindex functions, string
538 @cindex string functions
539
540 String functions take various arguments and return various results.
541
542 @cindex concatenation
543 @cindex strings, concatenation of
544 @deftypefn {Function} {} CONCAT (@var{string}, @var{string}[, @dots{}])
545 Returns a string consisting of each @var{string} in sequence.
546 @code{CONCAT("abc", "def", "ghi")} has a value of @code{"abcdefghi"}.
547 The resultant string is truncated to a maximum of 255 characters.
548 @end deftypefn
549
550 @cindex searching strings
551 @deftypefn {Function} {} INDEX (@var{haystack}, @var{needle})
552 Returns a positive integer indicating the position of the first
553 occurrence of @var{needle} in @var{haystack}.  Returns 0 if @var{haystack}
554 does not contain @var{needle}.  Returns system-missing if @var{needle}
555 is an empty string.
556 @end deftypefn
557
558 @deftypefn {Function} {} INDEX (@var{haystack}, @var{needles}, @var{needle_len})
559 Divides @var{needles} into one or more needles, each with length
560 @var{needle_len}.
561 Searches @var{haystack} for the first occurrence of each needle, and
562 returns the smallest value.  Returns 0 if @var{haystack} does not
563 contain any part in @var{needle}.  It is an error if @var{needle_len}
564 does not evenly divide the length of @var{needles}.  Returns
565 system-missing if @var{needles} is an empty string.
566 @end deftypefn
567
568 @cindex strings, finding length of
569 @deftypefn {Function} {} LENGTH (@var{string})
570 Returns the number of characters in @var{string}.
571 @end deftypefn
572
573 @cindex strings, case of
574 @deftypefn {Function} {} LOWER (@var{string})
575 Returns a string identical to @var{string} except that all uppercase
576 letters are changed to lowercase letters.  The definitions of
577 ``uppercase'' and ``lowercase'' are system-dependent.
578 @end deftypefn
579
580 @cindex strings, padding
581 @deftypefn {Function} {} LPAD (@var{string}, @var{length})
582 If @var{string} is at least @var{length} characters in length, returns
583 @var{string} unchanged.  Otherwise, returns @var{string} padded with
584 spaces on the left side to length @var{length}.  Returns an empty string
585 if @var{length} is system-missing, negative, or greater than 255.
586 @end deftypefn
587
588 @deftypefn {Function} {} LPAD (@var{string}, @var{length}, @var{padding})
589 If @var{string} is at least @var{length} characters in length, returns
590 @var{string} unchanged.  Otherwise, returns @var{string} padded with
591 @var{padding} on the left side to length @var{length}.  Returns an empty
592 string if @var{length} is system-missing, negative, or greater than 255, or
593 if @var{padding} does not contain exactly one character.
594 @end deftypefn
595
596 @cindex strings, trimming
597 @cindex white space, trimming
598 @deftypefn {Function} {} LTRIM (@var{string})
599 Returns @var{string}, after removing leading spaces.  Other white space,
600 such as tabs, carriage returns, line feeds, and vertical tabs, is not
601 removed.
602 @end deftypefn
603
604 @deftypefn {Function} {} LTRIM (@var{string}, @var{padding})
605 Returns @var{string}, after removing leading @var{padding} characters.
606 If @var{padding} does not contain exactly one character, returns an
607 empty string.
608 @end deftypefn
609
610 @cindex numbers, converting from strings
611 @cindex strings, converting to numbers
612 @deftypefn {Function} {} NUMBER (@var{string}, @var{format})
613 Returns the number produced when @var{string} is interpreted according
614 to format specifier @var{format}.  If the format width @var{w} is less
615 than the length of @var{string}, then only the first @var{w}
616 characters in @var{string} are used, e.g.@: @code{NUMBER("123", F3.0)}
617 and @code{NUMBER("1234", F3.0)} both have value 123.  If @var{w} is
618 greater than @var{string}'s length, then it is treated as if it were
619 right-padded with spaces.  If @var{string} is not in the correct
620 format for @var{format}, system-missing is returned.
621 @end deftypefn
622
623 @cindex strings, searching backwards
624 @deftypefn {Function} {} RINDEX (@var{haystack}, @var{needle})
625 Returns a positive integer indicating the position of the last
626 occurrence of @var{needle} in @var{haystack}.  Returns 0 if
627 @var{haystack} does not contain @var{needle}.  Returns system-missing if
628 @var{needle} is an empty string.
629 @end deftypefn
630
631 @deftypefn {Function} {} RINDEX (@var{haystack}, @var{needle}, @var{needle_len})
632 Divides @var{needle} into parts, each with length @var{needle_len}.
633 Searches @var{haystack} for the last occurrence of each part, and
634 returns the largest value.  Returns 0 if @var{haystack} does not contain
635 any part in @var{needle}.  It is an error if @var{needle_len} does not
636 evenly divide the length of @var{needle}.  Returns system-missing
637 if @var{needle} is an empty string or if needle_len is less than 1.
638 @end deftypefn
639
640 @cindex padding strings
641 @cindex strings, padding
642 @deftypefn {Function} {} RPAD (@var{string}, @var{length})
643 If @var{string} is at least @var{length} characters in length, returns
644 @var{string} unchanged.  Otherwise, returns @var{string} padded with
645 spaces on the right to length @var{length}.  Returns an empty string if
646 @var{length} is system-missing, negative, or greater than 255.
647 @end deftypefn
648
649 @deftypefn {Function} {} RPAD (@var{string}, @var{length}, @var{padding})
650 If @var{string} is at least @var{length} characters in length, returns
651 @var{string} unchanged.  Otherwise, returns @var{string} padded with
652 @var{padding} on the right to length @var{length}.  Returns an empty
653 string if @var{length} is system-missing, negative, or greater than 255,
654 or if @var{padding} does not contain exactly one character.
655 @end deftypefn
656
657 @cindex strings, trimming
658 @cindex white space, trimming
659 @deftypefn {Function} {} RTRIM (@var{string})
660 Returns @var{string}, after removing trailing spaces.  Other types of
661 white space are not removed.
662 @end deftypefn
663
664 @deftypefn {Function} {} RTRIM (@var{string}, @var{padding})
665 Returns @var{string}, after removing trailing @var{padding} characters.
666 If @var{padding} does not contain exactly one character, returns an
667 empty string.
668 @end deftypefn
669
670 @cindex strings, converting from numbers
671 @cindex numbers, converting to strings
672 @deftypefn {Function} {} STRING (@var{number}, @var{format})
673 Returns a string corresponding to @var{number} in the format given by
674 format specifier @var{format}.  For example, @code{STRING(123.56, F5.1)}
675 has the value @code{"123.6"}.
676 @end deftypefn
677
678 @cindex substrings
679 @cindex strings, taking substrings of
680 @deftypefn {Function} {} SUBSTR (@var{string}, @var{start})
681 Returns a string consisting of the value of @var{string} from position
682 @var{start} onward.  Returns an empty string if @var{start} is system-missing,
683 less than 1, or greater than the length of @var{string}.
684 @end deftypefn
685
686 @deftypefn {Function} {} SUBSTR (@var{string}, @var{start}, @var{count})
687 Returns a string consisting of the first @var{count} characters from
688 @var{string} beginning at position @var{start}.  Returns an empty string
689 if @var{start} or @var{count} is system-missing, if @var{start} is less
690 than 1 or greater than the number of characters in @var{string}, or if
691 @var{count} is less than 1.  Returns a string shorter than @var{count}
692 characters if @var{start} + @var{count} - 1 is greater than the number
693 of characters in @var{string}.  Examples: @code{SUBSTR("abcdefg", 3, 2)}
694 has value @code{"cd"}; @code{SUBSTR("nonsense", 4, 10)} has the value
695 @code{"sense"}.
696 @end deftypefn
697
698 @cindex case conversion
699 @cindex strings, case of
700 @deftypefn {Function} {} UPCASE (@var{string})
701 Returns @var{string}, changing lowercase letters to uppercase letters.
702 @end deftypefn
703
704 @node Time and Date
705 @subsection Time & Date Functions
706 @cindex functions, time & date
707 @cindex times
708 @cindex dates
709
710 @cindex dates, valid
711 For compatibility, @pspp{} considers dates before 15 Oct 1582 invalid.
712 Most time and date functions will not accept earlier dates.
713
714 @menu
715 * Time and Date Concepts::      How times & dates are defined and represented
716 * Time Construction::           TIME.@{DAYS HMS@}
717 * Time Extraction::             CTIME.@{DAYS HOURS MINUTES SECONDS@}
718 * Date Construction::           DATE.@{DMY MDY MOYR QYR WKYR YRDAY@}
719 * Date Extraction::             XDATE.@{DATE HOUR JDAY MDAY MINUTE MONTH
720                                        QUARTER SECOND TDAY TIME WEEK
721                                        WKDAY YEAR@}
722 * Time and Date Arithmetic::    DATEDIFF DATESUM
723 @end menu
724
725 @node Time and Date Concepts
726 @subsubsection How times & dates are defined and represented
727
728 @cindex time, concepts
729 @cindex time, intervals
730 Times and dates are handled by @pspp{} as single numbers.  A
731 @dfn{time} is an interval.  @pspp{} measures times in seconds.
732 Thus, the following intervals correspond with the numeric values given:
733                 
734 @example
735           10 minutes                        600
736           1 hour                          3,600
737           1 day, 3 hours, 10 seconds     97,210
738           40 days                     3,456,000
739 @end example
740
741 @cindex dates, concepts
742 @cindex time, instants of
743 A @dfn{date}, on the other hand, is a particular instant in the past
744 or the future.  @pspp{} represents a date as a number of seconds since
745 midnight preceding 14 Oct 1582.  Because midnight preceding the dates
746 given below correspond with the numeric @pspp{} dates given:
747
748 @example
749               15 Oct 1582                86,400
750                4 Jul 1776         6,113,318,400
751                1 Jan 1900        10,010,390,400
752                1 Oct 1978        12,495,427,200
753               24 Aug 1995        13,028,601,600
754 @end example
755
756 @node Time Construction
757 @subsubsection Functions that Produce Times
758 @cindex times, constructing
759 @cindex constructing times
760
761 These functions take numeric arguments and return numeric values that
762 represent times.
763
764 @cindex days
765 @cindex time, in days
766 @deftypefn {Function} {} TIME.DAYS (@var{ndays})
767 Returns a time corresponding to @var{ndays} days.
768 @end deftypefn
769
770 @cindex hours-minutes-seconds
771 @cindex time, in hours-minutes-seconds
772 @deftypefn {Function} {} TIME.HMS (@var{nhours}, @var{nmins}, @var{nsecs})
773 Returns a time corresponding to @var{nhours} hours, @var{nmins}
774 minutes, and @var{nsecs} seconds.  The arguments may not have mixed
775 signs: if any of them are positive, then none may be negative, and
776 vice versa.  
777 @end deftypefn
778
779 @node Time Extraction
780 @subsubsection Functions that Examine Times
781 @cindex extraction, of time
782 @cindex time examination
783 @cindex examination, of times
784 @cindex time, lengths of
785
786 These functions take numeric arguments in @pspp{} time format and
787 give numeric results.
788
789 @cindex days
790 @cindex time, in days
791 @deftypefn {Function} {} CTIME.DAYS (@var{time})
792 Results in the number of days and fractional days in @var{time}.
793 @end deftypefn
794
795 @cindex hours
796 @cindex time, in hours
797 @deftypefn {Function} {} CTIME.HOURS (@var{time})
798 Results in the number of hours and fractional hours in @var{time}.
799 @end deftypefn
800
801 @cindex minutes
802 @cindex time, in minutes
803 @deftypefn {Function} {} CTIME.MINUTES (@var{time})
804 Results in the number of minutes and fractional minutes in @var{time}.
805 @end deftypefn
806
807 @cindex seconds
808 @cindex time, in seconds
809 @deftypefn {Function} {} CTIME.SECONDS (@var{time})
810 Results in the number of seconds and fractional seconds in @var{time}.
811 (@code{CTIME.SECONDS} does nothing; @code{CTIME.SECONDS(@var{x})} is
812 equivalent to @code{@var{x}}.)
813 @end deftypefn
814
815 @node Date Construction
816 @subsubsection Functions that Produce Dates
817 @cindex dates, constructing
818 @cindex constructing dates
819
820 @cindex arguments, of date construction functions
821 These functions take numeric arguments and give numeric results that
822 represent dates.  Arguments taken by these functions are:
823
824 @table @var
825 @item day
826 Refers to a day of the month between 1 and 31.  Day 0 is also accepted
827 and refers to the final day of the previous month.  Days 29, 30, and
828 31 are accepted even in months that have fewer days and refer to a day
829 near the beginning of the following month.
830
831 @item month
832 Refers to a month of the year between 1 and 12.  Months 0 and 13 are
833 also accepted and refer to the last month of the preceding year and
834 the first month of the following year, respectively.
835
836 @item quarter
837 Refers to a quarter of the year between 1 and 4.  The quarters of the
838 year begin on the first day of months 1, 4, 7, and 10.
839
840 @item week
841 Refers to a week of the year between 1 and 53.
842
843 @item yday
844 Refers to a day of the year between 1 and 366.
845
846 @item year
847 Refers to a year, 1582 or greater.  Years between 0 and 99 are treated
848 according to the epoch set on SET EPOCH, by default beginning 69 years
849 before the current date (@pxref{SET EPOCH}).
850 @end table
851
852 @cindex arguments, invalid
853 If these functions' arguments are out-of-range, they are correctly
854 normalized before conversion to date format.  Non-integers are rounded
855 toward zero.
856
857 @cindex day-month-year
858 @cindex dates, day-month-year
859 @deftypefn {Function} {} DATE.DMY (@var{day}, @var{month}, @var{year})
860 @deftypefnx {Function} {} DATE.MDY (@var{month}, @var{day}, @var{year})
861 Results in a date value corresponding to the midnight before day
862 @var{day} of month @var{month} of year @var{year}.
863 @end deftypefn
864
865 @cindex month-year
866 @cindex dates, month-year
867 @deftypefn {Function} {} DATE.MOYR (@var{month}, @var{year})
868 Results in a date value corresponding to the midnight before the first
869 day of month @var{month} of year @var{year}.
870 @end deftypefn
871
872 @cindex quarter-year
873 @cindex dates, quarter-year
874 @deftypefn {Function} {} DATE.QYR (@var{quarter}, @var{year})
875 Results in a date value corresponding to the midnight before the first
876 day of quarter @var{quarter} of year @var{year}.
877 @end deftypefn
878
879 @cindex week-year
880 @cindex dates, week-year
881 @deftypefn {Function} {} DATE.WKYR (@var{week}, @var{year})
882 Results in a date value corresponding to the midnight before the first
883 day of week @var{week} of year @var{year}.
884 @end deftypefn
885
886 @cindex year-day
887 @cindex dates, year-day
888 @deftypefn {Function} {} DATE.YRDAY (@var{year}, @var{yday})
889 Results in a date value corresponding to the day
890 @var{yday} of year @var{year}.
891 @end deftypefn
892
893 @node Date Extraction
894 @subsubsection Functions that Examine Dates
895 @cindex extraction, of dates
896 @cindex date examination
897
898 @cindex arguments, of date extraction functions
899 These functions take numeric arguments in @pspp{} date or time
900 format and give numeric results.  These names are used for arguments:
901
902 @table @var
903 @item date
904 A numeric value in @pspp{} date format.
905
906 @item time
907 A numeric value in @pspp{} time format.
908
909 @item time-or-date
910 A numeric value in @pspp{} time or date format.
911 @end table
912
913 @cindex days
914 @cindex dates, in days
915 @cindex time, in days
916 @deftypefn {Function} {} XDATE.DATE (@var{time-or-date})
917 For a time, results in the time corresponding to the number of whole
918 days @var{date-or-time} includes.  For a date, results in the date
919 corresponding to the latest midnight at or before @var{date-or-time};
920 that is, gives the date that @var{date-or-time} is in.
921 @end deftypefn
922
923 @cindex hours
924 @cindex dates, in hours
925 @cindex time, in hours
926 @deftypefn {Function} {} XDATE.HOUR (@var{time-or-date})
927 For a time, results in the number of whole hours beyond the number of
928 whole days represented by @var{date-or-time}.  For a date, results in
929 the hour (as an integer between 0 and 23) corresponding to
930 @var{date-or-time}.  
931 @end deftypefn
932
933 @cindex day of the year
934 @cindex dates, day of the year
935 @deftypefn {Function} {} XDATE.JDAY (@var{date})
936 Results in the day of the year (as an integer between 1 and 366)
937 corresponding to @var{date}.
938 @end deftypefn
939
940 @cindex day of the month
941 @cindex dates, day of the month
942 @deftypefn {Function} {} XDATE.MDAY (@var{date})
943 Results in the day of the month (as an integer between 1 and 31)
944 corresponding to @var{date}.
945 @end deftypefn
946
947 @cindex minutes
948 @cindex dates, in minutes
949 @cindex time, in minutes
950 @deftypefn {Function} {} XDATE.MINUTE (@var{time-or-date})
951 Results in the number of minutes (as an integer between 0 and 59) after
952 the last hour in @var{time-or-date}. 
953 @end deftypefn
954
955 @cindex months
956 @cindex dates, in months
957 @deftypefn {Function} {} XDATE.MONTH (@var{date})
958 Results in the month of the year (as an integer between 1 and 12)
959 corresponding to @var{date}.
960 @end deftypefn
961
962 @cindex quarters
963 @cindex dates, in quarters
964 @deftypefn {Function} {} XDATE.QUARTER (@var{date})
965 Results in the quarter of the year (as an integer between 1 and 4)
966 corresponding to @var{date}.
967 @end deftypefn
968
969 @cindex seconds
970 @cindex dates, in seconds
971 @cindex time, in seconds
972 @deftypefn {Function} {} XDATE.SECOND (@var{time-or-date})
973 Results in the number of whole seconds after the last whole minute (as
974 an integer between 0 and 59) in @var{time-or-date}.
975 @end deftypefn
976
977 @cindex days
978 @cindex times, in days
979 @deftypefn {Function} {} XDATE.TDAY (@var{date})
980 Results in the number of whole days from 14 Oct 1582 to @var{date}.
981 @end deftypefn
982
983 @cindex time
984 @cindex dates, time of day
985 @deftypefn {Function} {} XDATE.TIME (@var{date})
986 Results in the time of day at the instant corresponding to @var{date},
987 as a time value.  This is the number of seconds since
988 midnight on the day corresponding to @var{date}.
989 @end deftypefn
990
991 @cindex week
992 @cindex dates, in weeks
993 @deftypefn {Function} {} XDATE.WEEK (@var{date})
994 Results in the week of the year (as an integer between 1 and 53)
995 corresponding to @var{date}.
996 @end deftypefn
997
998 @cindex day of the week
999 @cindex weekday
1000 @cindex dates, day of the week
1001 @cindex dates, in weekdays
1002 @deftypefn {Function} {} XDATE.WKDAY (@var{date})
1003 Results in the day of week (as an integer between 1 and 7) corresponding
1004 to @var{date}, where 1 represents Sunday.
1005 @end deftypefn
1006
1007 @cindex years
1008 @cindex dates, in years
1009 @deftypefn {Function} {} XDATE.YEAR (@var{date})
1010 Returns the year (as an integer 1582 or greater) corresponding to
1011 @var{date}.
1012 @end deftypefn
1013
1014 @node Time and Date Arithmetic
1015 @subsubsection Time and Date Arithmetic
1016
1017 @cindex time, mathematical properties of
1018 @cindex mathematics, applied to times & dates
1019 @cindex dates, mathematical properties of
1020 @noindent
1021 Ordinary arithmetic operations on dates and times often produce
1022 sensible results.  Adding a time to, or subtracting one from, a date
1023 produces a new date that much earlier or later.  The difference of two
1024 dates yields the time between those dates.  Adding two times produces
1025 the combined time.  Multiplying a time by a scalar produces a time
1026 that many times longer.  Since times and dates are just numbers, the
1027 ordinary addition and subtraction operators are employed for these
1028 purposes.
1029
1030 Adding two dates does not produce a useful result.
1031
1032 Dates and times may have very large values.  Thus,
1033 it is not a good idea to take powers of these values; also, the
1034 accuracy of some procedures may be affected.  If necessary, convert
1035 times or dates in seconds to some other unit, like days or years,
1036 before performing analysis.
1037
1038 @pspp{} supplies a few functions for date arithmetic:
1039
1040 @deftypefn {Function} {} DATEDIFF (@var{date2}, @var{date1}, @var{unit})
1041 Returns the span of time from @var{date1} to @var{date2} in terms of
1042 @var{unit}, which must be a quoted string, one of @samp{years},
1043 @samp{quarters}, @samp{months}, @samp{weeks}, @samp{days},
1044 @samp{hours}, @samp{minutes}, and @samp{seconds}.  The result is an
1045 integer, truncated toward zero.
1046
1047 One year is considered to span from a given date to the same month,
1048 day, and time of day the next year.  Thus, from Jan.@tie{}1 of one
1049 year to Jan.@tie{}1 the next year is considered to be a full year, but
1050 Feb.@tie{}29 of a leap year to the following Feb.@tie{}28 is not.
1051 Similarly, one month spans from a given day of the month to the same
1052 day of the following month.  Thus, there is never a full month from
1053 Jan.@tie{}31 of a given year to any day in the following February.
1054 @end deftypefn
1055
1056 @deftypefn {Function} {} DATESUM (@var{date}, @var{quantity}, @var{unit}[, @var{method}])
1057 Returns @var{date} advanced by the given @var{quantity} of the
1058 specified @var{unit}, which must be one of the strings @samp{years},
1059 @samp{quarters}, @samp{months}, @samp{weeks}, @samp{days},
1060 @samp{hours}, @samp{minutes}, and @samp{seconds}.
1061
1062 When @var{unit} is @samp{years}, @samp{quarters}, or @samp{months},
1063 only the integer part of @var{quantity} is considered.  Adding one of
1064 these units can cause the day of the month to exceed the number of
1065 days in the month.  In this case, the @var{method} comes into
1066 play: if it is omitted or specified as @samp{closest} (as a quoted
1067 string), then the resulting day is the last day of the month;
1068 otherwise, if it is specified as @samp{rollover}, then the extra days
1069 roll over into the following month.
1070
1071 When @var{unit} is @samp{weeks}, @samp{days}, @samp{hours},
1072 @samp{minutes}, or @samp{seconds}, the @var{quantity} is not rounded
1073 to an integer and @var{method}, if specified, is ignored.
1074 @end deftypefn
1075
1076 @node Miscellaneous Functions
1077 @subsection Miscellaneous Functions
1078 @cindex functions, miscellaneous
1079
1080 @cindex cross-case function
1081 @cindex function, cross-case
1082 @deftypefn {Function} {} LAG (@var{variable}[, @var{n}])
1083 @anchor{LAG}
1084
1085 @var{variable} must be a numeric or string variable name.  @code{LAG}
1086 yields the value of that variable for the case @var{n} before the
1087 current one.  Results in system-missing (for numeric variables) or
1088 blanks (for string variables) for the first @var{n} cases.
1089
1090 @code{LAG} obtains values from the cases that become the new active
1091 dataset
1092 after a procedure executes.  Thus, @code{LAG} will not return values
1093 from cases dropped by transformations such as @cmd{SELECT IF}, and
1094 transformations like @cmd{COMPUTE} that modify data will change the
1095 values returned by @code{LAG}.  These are both the case whether these
1096 transformations precede or follow the use of @code{LAG}.
1097
1098 If @code{LAG} is used before @cmd{TEMPORARY}, then the values it returns
1099 are those in cases just before @cmd{TEMPORARY}.  @code{LAG} may not be
1100 used after @cmd{TEMPORARY}.
1101
1102 If omitted, @var{ncases} defaults to 1.  Otherwise, @var{ncases} must
1103 be a small positive constant integer.  There is no explicit limit, but
1104 use of a large value will increase memory consumption.
1105 @end deftypefn
1106
1107 @cindex date, Julian
1108 @cindex Julian date
1109 @deftypefn {Function} {} YRMODA (@var{year}, @var{month}, @var{day})
1110 @var{year} is a year, either between 0 and 99 or at least 1582.
1111 Unlike other @pspp{} date functions, years between 0 and 99 always
1112 correspond to 1900 through 1999.  @var{month} is a month between 1 and
1113 13.  @var{day} is a day between 0 and 31.  A @var{day} of 0 refers to
1114 the last day of the previous month, and a @var{month} of 13 refers to
1115 the first month of the next year.  @var{year} must be in range.
1116 @var{year}, @var{month}, and @var{day} must all be integers.
1117
1118 @code{YRMODA} results in the number of days between 15 Oct 1582 and
1119 the date specified, plus one.  The date passed to @code{YRMODA} must be
1120 on or after 15 Oct 1582.  15 Oct 1582 has a value of 1.
1121 @end deftypefn
1122
1123 @cindex value label
1124 @deftypefn {Function} VALUELABEL (@var{variable})
1125 Returns a string matching the label associated with the current value
1126 of @var{variable}.  If the current value of @var{variable} has no
1127 associated label, then this function returns the empty string.
1128 @var{variable} may be a numeric or string variable.
1129 @end deftypefn
1130
1131 @node Statistical Distribution Functions
1132 @subsection Statistical Distribution Functions
1133
1134 @pspp{} can calculate several functions of standard statistical
1135 distributions.  These functions are named systematically based on the
1136 function and the distribution.  The table below describes the
1137 statistical distribution functions in general:
1138
1139 @table @asis
1140 @item PDF.@var{dist} (@var{x}[, @var{param}@dots{}])
1141 Probability density function for @var{dist}.  The domain of @var{x}
1142 depends on @var{dist}.  For continuous distributions, the result is
1143 the density of the probability function at @var{x}, and the range is
1144 nonnegative real numbers.  For discrete distributions, the result is
1145 the probability of @var{x}.
1146
1147 @item CDF.@var{dist} (@var{x}[, @var{param}@dots{}])
1148 Cumulative distribution function for @var{dist}, that is, the
1149 probability that a random variate drawn from the distribution is less
1150 than @var{x}.  The domain of @var{x} depends @var{dist}.  The result is
1151 a probability.
1152
1153 @item SIG.@var{dist} (@var{x}[, @var{param}@dots{})
1154 Tail probability function for @var{dist}, that is, the probability
1155 that a random variate drawn from the distribution is greater than
1156 @var{x}.  The domain of @var{x} depends @var{dist}.  The result is a
1157 probability.  Only a few distributions include an @func{SIG} function.
1158
1159 @item IDF.@var{dist} (@var{p}[, @var{param}@dots{}])
1160 Inverse distribution function for @var{dist}, the value of @var{x} for
1161 which the CDF would yield @var{p}.  The value of @var{p} is a
1162 probability.  The range depends on @var{dist} and is identical to the
1163 domain for the corresponding CDF.
1164
1165 @item RV.@var{dist} ([@var{param}@dots{}])
1166 Random variate function for @var{dist}.  The range depends on the
1167 distribution.
1168
1169 @item NPDF.@var{dist} (@var{x}[, @var{param}@dots{}])
1170 Noncentral probability density function.  The result is the density of
1171 the given noncentral distribution at @var{x}.  The domain of @var{x}
1172 depends on @var{dist}.  The range is nonnegative real numbers.  Only a
1173 few distributions include an @func{NPDF} function.
1174
1175 @item NCDF.@var{dist} (@var{x}[, @var{param}@dots{}])
1176 Noncentral cumulative distribution function for @var{dist}, that is,
1177 the probability that a random variate drawn from the given noncentral
1178 distribution is less than @var{x}.  The domain of @var{x} depends
1179 @var{dist}.  The result is a probability.  Only a few distributions
1180 include an NCDF function.
1181 @end table
1182
1183 The individual distributions are described individually below.
1184
1185 @menu
1186 * Continuous Distributions::    
1187 * Discrete Distributions::      
1188 @end menu
1189
1190 @node Continuous Distributions
1191 @subsubsection Continuous Distributions
1192
1193 The following continuous distributions are available:
1194
1195 @deftypefn {Function} {} PDF.BETA (@var{x})
1196 @deftypefnx {Function} {} CDF.BETA (@var{x}, @var{a}, @var{b})
1197 @deftypefnx {Function} {} IDF.BETA (@var{p}, @var{a}, @var{b})
1198 @deftypefnx {Function} {} RV.BETA (@var{a}, @var{b})
1199 @deftypefnx {Function} {} NPDF.BETA (@var{x}, @var{a}, @var{b}, @var{lambda})
1200 @deftypefnx {Function} {} NCDF.BETA (@var{x}, @var{a}, @var{b}, @var{lambda})
1201 Beta distribution with shape parameters @var{a} and @var{b}.  The
1202 noncentral distribution takes an additional parameter @var{lambda}.
1203 Constraints: @var{a} > 0, @var{b} > 0, @var{lambda} >= 0, 0 <= @var{x}
1204 <= 1, 0 <= @var{p} <= 1.
1205 @end deftypefn
1206
1207 @deftypefn {Function} {} PDF.BVNOR (@var{x0}, @var{x1}, @var{rho})
1208 @deftypefnx {Function} {} CDF.VBNOR (@var{x0}, @var{x1}, @var{rho})
1209 Bivariate normal distribution of two standard normal variables with
1210 correlation coefficient @var{rho}.  Two variates @var{x0} and @var{x1}
1211 must be provided.  Constraints: 0 <= @var{rho} <= 1, 0 <= @var{p} <= 1.
1212 @end deftypefn
1213
1214 @deftypefn {Function} {} PDF.CAUCHY (@var{x}, @var{a}, @var{b})
1215 @deftypefnx {Function} {} CDF.CAUCHY (@var{x}, @var{a}, @var{b})
1216 @deftypefnx {Function} {} IDF.CAUCHY (@var{p}, @var{a}, @var{b})
1217 @deftypefnx {Function} {} RV.CAUCHY (@var{a}, @var{b})
1218 Cauchy distribution with location parameter @var{a} and scale
1219 parameter @var{b}.  Constraints: @var{b} > 0, 0 < @var{p} < 1.
1220 @end deftypefn
1221
1222 @c @deftypefn {Function} {} PDF.CHISQ (@var{x}, @var{df})
1223 @deftypefn {Function} {} CDF.CHISQ (@var{x}, @var{df})
1224 @deftypefnx {Function} {} SIG.CHISQ (@var{x}, @var{df})
1225 @deftypefnx {Function} {} IDF.CHISQ (@var{p}, @var{df})
1226 @deftypefnx {Function} {} RV.CHISQ (@var{df})
1227 @c @deftypefnx {Function} {} NPDF.CHISQ (@var{x}, @var{df}, @var{lambda})
1228 @deftypefnx {Function} {} NCDF.CHISQ (@var{x}, @var{df}, @var{lambda})
1229 Chi-squared distribution with @var{df} degrees of freedom.  The
1230 noncentral distribution takes an additional parameter @var{lambda}.
1231 Constraints: @var{df} > 0, @var{lambda} > 0, @var{x} >= 0, 0 <=
1232 @var{p} < 1.
1233 @end deftypefn
1234
1235 @deftypefn {Function} {} PDF.EXP (@var{x}, @var{a})
1236 @deftypefnx {Function} {} CDF.EXP (@var{x}, @var{a})
1237 @deftypefnx {Function} {} IDF.EXP (@var{p}, @var{a})
1238 @deftypefnx {Function} {} RV.EXP (@var{a})
1239 Exponential distribution with scale parameter @var{a}.  The inverse of
1240 @var{a} represents the rate of decay.  Constraints: @var{a} > 0,
1241 @var{x} >= 0, 0 <= @var{p} < 1.
1242 @end deftypefn
1243
1244 @deftypefn {Function} {} PDF.XPOWER (@var{x}, @var{a}, @var{b})
1245 @deftypefnx {Function} {} RV.XPOWER (@var{a}, @var{b})
1246 Exponential power distribution with positive scale parameter @var{a}
1247 and nonnegative power parameter @var{b}.  Constraints: @var{a} > 0,
1248 @var{b} >= 0, @var{x} >= 0, 0 <= @var{p} <= 1.  This distribution is a
1249 @pspp{} extension.
1250 @end deftypefn
1251
1252 @deftypefn {Function} {} PDF.F (@var{x}, @var{df1}, @var{df2})
1253 @deftypefnx {Function} {} CDF.F (@var{x}, @var{df1}, @var{df2})
1254 @deftypefnx {Function} {} SIG.F (@var{x}, @var{df1}, @var{df2})
1255 @deftypefnx {Function} {} IDF.F (@var{p}, @var{df1}, @var{df2})
1256 @deftypefnx {Function} {} RV.F (@var{df1}, @var{df2})
1257 @c @deftypefnx {Function} {} NPDF.F (@var{x}, @var{df1}, @var{df2}, @var{lambda})
1258 @c @deftypefnx {Function} {} NCDF.F (@var{x}, @var{df1}, @var{df2}, @var{lambda})
1259 F-distribution of two chi-squared deviates with @var{df1} and
1260 @var{df2} degrees of freedom.  The noncentral distribution takes an
1261 additional parameter @var{lambda}.  Constraints: @var{df1} > 0,
1262 @var{df2} > 0, @var{lambda} >= 0, @var{x} >= 0, 0 <= @var{p} < 1.
1263 @end deftypefn
1264
1265 @deftypefn {Function} {} PDF.GAMMA (@var{x}, @var{a}, @var{b})
1266 @deftypefnx {Function} {} CDF.GAMMA (@var{x}, @var{a}, @var{b})
1267 @deftypefnx {Function} {} IDF.GAMMA (@var{p}, @var{a}, @var{b})
1268 @deftypefnx {Function} {} RV.GAMMA (@var{a}, @var{b})
1269 Gamma distribution with shape parameter @var{a} and scale parameter
1270 @var{b}.  Constraints: @var{a} > 0, @var{b} > 0, @var{x} >= 0, 0 <=
1271 @var{p} < 1.
1272 @end deftypefn
1273
1274 @c @deftypefn {Function} {} PDF.HALFNRM (@var{x}, @var{a}, @var{b})
1275 @c @deftypefnx {Function} {} CDF.HALFNRM (@var{x}, @var{a}, @var{b})
1276 @c @deftypefnx {Function} {} IDF.HALFNRM (@var{p}, @var{a}, @var{b})
1277 @c @deftypefnx {Function} {} RV.HALFNRM (@var{a}, @var{b})
1278 @c Half-normal distribution with location parameter @var{a} and shape
1279 @c parameter @var{b}.  Constraints: @var{b} > 0, 0 < @var{p} < 1.
1280 @c @end deftypefn
1281
1282 @c @deftypefn {Function} {} PDF.IGAUSS (@var{x}, @var{a}, @var{b})
1283 @c @deftypefnx {Function} {} CDF.IGAUSS (@var{x}, @var{a}, @var{b})
1284 @c @deftypefnx {Function} {} IDF.IGAUSS (@var{p}, @var{a}, @var{b})
1285 @c @deftypefnx {Function} {} RV.IGAUSS (@var{a}, @var{b})
1286 @c Inverse Gaussian distribution with parameters @var{a} and @var{b}.
1287 @c Constraints: @var{a} > 0, @var{b} > 0, @var{x} > 0, 0 <= @var{p} < 1.
1288 @c @end deftypefn
1289
1290 @deftypefn {Function} {} PDF.LANDAU (@var{x})
1291 @deftypefnx {Function} {} RV.LANDAU ()
1292 Landau distribution.
1293 @end deftypefn
1294
1295 @deftypefn {Function} {} PDF.LAPLACE (@var{x}, @var{a}, @var{b})
1296 @deftypefnx {Function} {} CDF.LAPLACE (@var{x}, @var{a}, @var{b})
1297 @deftypefnx {Function} {} IDF.LAPLACE (@var{p}, @var{a}, @var{b})
1298 @deftypefnx {Function} {} RV.LAPLACE (@var{a}, @var{b})
1299 Laplace distribution with location parameter @var{a} and scale
1300 parameter @var{b}.  Constraints: @var{b} > 0, 0 < @var{p} < 1.
1301 @end deftypefn
1302
1303 @deftypefn {Function} {} RV.LEVY (@var{c}, @var{alpha})
1304 Levy symmetric alpha-stable distribution with scale @var{c} and
1305 exponent @var{alpha}.  Constraints: 0 < @var{alpha} <= 2.
1306 @end deftypefn
1307
1308 @deftypefn {Function} {} RV.LVSKEW (@var{c}, @var{alpha}, @var{beta})
1309 Levy skew alpha-stable distribution with scale @var{c}, exponent
1310 @var{alpha}, and skewness parameter @var{beta}.  Constraints: 0 <
1311 @var{alpha} <= 2, -1 <= @var{beta} <= 1.
1312 @end deftypefn
1313
1314 @deftypefn {Function} {} PDF.LOGISTIC (@var{x}, @var{a}, @var{b})
1315 @deftypefnx {Function} {} CDF.LOGISTIC (@var{x}, @var{a}, @var{b})
1316 @deftypefnx {Function} {} IDF.LOGISTIC (@var{p}, @var{a}, @var{b})
1317 @deftypefnx {Function} {} RV.LOGISTIC (@var{a}, @var{b})
1318 Logistic distribution with location parameter @var{a} and scale
1319 parameter @var{b}.  Constraints: @var{b} > 0, 0 < @var{p} < 1.
1320 @end deftypefn
1321
1322 @deftypefn {Function} {} PDF.LNORMAL (@var{x}, @var{a}, @var{b})
1323 @deftypefnx {Function} {} CDF.LNORMAL (@var{x}, @var{a}, @var{b})
1324 @deftypefnx {Function} {} IDF.LNORMAL (@var{p}, @var{a}, @var{b})
1325 @deftypefnx {Function} {} RV.LNORMAL (@var{a}, @var{b})
1326 Lognormal distribution with parameters @var{a} and @var{b}.
1327 Constraints: @var{a} > 0, @var{b} > 0, @var{x} >= 0, 0 <= @var{p} < 1.
1328 @end deftypefn
1329
1330 @deftypefn {Function} {} PDF.NORMAL (@var{x}, @var{mu}, @var{sigma})
1331 @deftypefnx {Function} {} CDF.NORMAL (@var{x}, @var{mu}, @var{sigma})
1332 @deftypefnx {Function} {} IDF.NORMAL (@var{p}, @var{mu}, @var{sigma})
1333 @deftypefnx {Function} {} RV.NORMAL (@var{mu}, @var{sigma})
1334 Normal distribution with mean @var{mu} and standard deviation
1335 @var{sigma}.  Constraints: @var{b} > 0, 0 < @var{p} < 1.  Three
1336 additional functions are available as shorthand:
1337
1338 @deftypefn {Function} {} CDFNORM (@var{x})
1339 Equivalent to CDF.NORMAL(@var{x}, 0, 1).
1340 @end deftypefn
1341
1342 @deftypefn {Function} {} PROBIT (@var{p})
1343 Equivalent to IDF.NORMAL(@var{p}, 0, 1).
1344 @end deftypefn
1345
1346 @deftypefn {Function} {} NORMAL (@var{sigma})
1347 Equivalent to RV.NORMAL(0, @var{sigma}).
1348 @end deftypefn
1349 @end deftypefn
1350
1351 @deftypefn {Function} {} PDF.NTAIL (@var{x}, @var{a}, @var{sigma})
1352 @deftypefnx {Function} {} RV.NTAIL (@var{a}, @var{sigma})
1353 Normal tail distribution with lower limit @var{a} and standard
1354 deviation @var{sigma}.  This distribution is a @pspp{} extension.
1355 Constraints: @var{a} > 0, @var{x} > @var{a}, 0 < @var{p} < 1.
1356 @end deftypefn
1357
1358 @deftypefn {Function} {} PDF.PARETO (@var{x}, @var{a}, @var{b})
1359 @deftypefnx {Function} {} CDF.PARETO (@var{x}, @var{a}, @var{b})
1360 @deftypefnx {Function} {} IDF.PARETO (@var{p}, @var{a}, @var{b})
1361 @deftypefnx {Function} {} RV.PARETO (@var{a}, @var{b})
1362 Pareto distribution with threshold parameter @var{a} and shape
1363 parameter @var{b}.  Constraints: @var{a} > 0, @var{b} > 0, @var{x} >=
1364 @var{a}, 0 <= @var{p} < 1.
1365 @end deftypefn
1366
1367 @deftypefn {Function} {} PDF.RAYLEIGH (@var{x}, @var{sigma})
1368 @deftypefnx {Function} {} CDF.RAYLEIGH (@var{x}, @var{sigma})
1369 @deftypefnx {Function} {} IDF.RAYLEIGH (@var{p}, @var{sigma})
1370 @deftypefnx {Function} {} RV.RAYLEIGH (@var{sigma})
1371 Rayleigh distribution with scale parameter @var{sigma}.  This
1372 distribution is a @pspp{} extension.  Constraints: @var{sigma} > 0,
1373 @var{x} > 0.
1374 @end deftypefn
1375
1376 @deftypefn {Function} {} PDF.RTAIL (@var{x}, @var{a}, @var{sigma})
1377 @deftypefnx {Function} {} RV.RTAIL (@var{a}, @var{sigma})
1378 Rayleigh tail distribution with lower limit @var{a} and scale
1379 parameter @var{sigma}.  This distribution is a @pspp{} extension.
1380 Constraints: @var{a} > 0, @var{sigma} > 0, @var{x} > @var{a}.
1381 @end deftypefn
1382
1383 @c @deftypefn {Function} {} CDF.SMOD (@var{x}, @var{a}, @var{b})
1384 @c @deftypefnx {Function} {} IDF.SMOD (@var{p}, @var{a}, @var{b})
1385 @c Studentized maximum modulus distribution with parameters @var{a} and
1386 @c @var{b}.  Constraints: @var{a} > 0, @var{b} > 0, @var{x} > 0, 0 <=
1387 @c @var{p} < 1.
1388 @c @end deftypefn
1389
1390 @c @deftypefn {Function} {} CDF.SRANGE (@var{x}, @var{a}, @var{b})
1391 @c @deftypefnx {Function} {} IDF.SRANGE (@var{p}, @var{a}, @var{b})
1392 @c Studentized range distribution with parameters @var{a} and @var{b}.
1393 @c Constraints:  @var{a} >= 1, @var{b} >= 1, @var{x} > 0, 0 <= @var{p} <
1394 @c 1.
1395 @c @end deftypefn
1396
1397 @deftypefn {Function} {} PDF.T (@var{x}, @var{df})
1398 @deftypefnx {Function} {} CDF.T (@var{x}, @var{df})
1399 @deftypefnx {Function} {} IDF.T (@var{p}, @var{df})
1400 @deftypefnx {Function} {} RV.T (@var{df})
1401 @c @deftypefnx {Function} {} NPDF.T (@var{x}, @var{df}, @var{lambda})
1402 @c @deftypefnx {Function} {} NCDF.T (@var{x}, @var{df}, @var{lambda})
1403 T-distribution with @var{df} degrees of freedom.  The noncentral
1404 distribution takes an additional parameter @var{lambda}.  Constraints:
1405 @var{df} > 0, 0 < @var{p} < 1.
1406 @end deftypefn
1407
1408 @deftypefn {Function} {} PDF.T1G (@var{x}, @var{a}, @var{b})
1409 @deftypefnx {Function} {} CDF.T1G (@var{x}, @var{a}, @var{b})
1410 @deftypefnx {Function} {} IDF.T1G (@var{p}, @var{a}, @var{b})
1411 Type-1 Gumbel distribution with parameters @var{a} and @var{b}.  This
1412 distribution is a @pspp{} extension.  Constraints: 0 < @var{p} < 1.
1413 @end deftypefn
1414
1415 @deftypefn {Function} {} PDF.T2G (@var{x}, @var{a}, @var{b})
1416 @deftypefnx {Function} {} CDF.T2G (@var{x}, @var{a}, @var{b})
1417 @deftypefnx {Function} {} IDF.T2G (@var{p}, @var{a}, @var{b})
1418 Type-2 Gumbel distribution with parameters @var{a} and @var{b}.  This
1419 distribution is a @pspp{} extension.  Constraints: @var{x} > 0, 0 <
1420 @var{p} < 1.
1421 @end deftypefn
1422
1423 @deftypefn {Function} {} PDF.UNIFORM (@var{x}, @var{a}, @var{b})
1424 @deftypefnx {Function} {} CDF.UNIFORM (@var{x}, @var{a}, @var{b})
1425 @deftypefnx {Function} {} IDF.UNIFORM (@var{p}, @var{a}, @var{b})
1426 @deftypefnx {Function} {} RV.UNIFORM (@var{a}, @var{b})
1427 Uniform distribution with parameters @var{a} and @var{b}.
1428 Constraints: @var{a} <= @var{x} <= @var{b}, 0 <= @var{p} <= 1.  An
1429 additional function is available as shorthand:
1430
1431 @deftypefn {Function} {} UNIFORM (@var{b})
1432 Equivalent to RV.UNIFORM(0, @var{b}).
1433 @end deftypefn
1434 @end deftypefn
1435
1436 @deftypefn {Function} {} PDF.WEIBULL (@var{x}, @var{a}, @var{b})
1437 @deftypefnx {Function} {} CDF.WEIBULL (@var{x}, @var{a}, @var{b})
1438 @deftypefnx {Function} {} IDF.WEIBULL (@var{p}, @var{a}, @var{b})
1439 @deftypefnx {Function} {} RV.WEIBULL (@var{a}, @var{b})
1440 Weibull distribution with parameters @var{a} and @var{b}.
1441 Constraints: @var{a} > 0, @var{b} > 0, @var{x} >= 0, 0 <= @var{p} < 1.
1442 @end deftypefn
1443
1444 @node Discrete Distributions
1445 @subsubsection Discrete Distributions
1446
1447 The following discrete distributions are available:
1448
1449 @deftypefn {Function} {} PDF.BERNOULLI (@var{x})
1450 @deftypefnx {Function} {} CDF.BERNOULLI (@var{x}, @var{p})
1451 @deftypefnx {Function} {} RV.BERNOULLI (@var{p})
1452 Bernoulli distribution with probability of success @var{p}.
1453 Constraints: @var{x} = 0 or 1, 0 <= @var{p} <= 1.
1454 @end deftypefn
1455
1456 @deftypefn {Function} {} PDF.BINOM (@var{x}, @var{n}, @var{p})
1457 @deftypefnx {Function} {} CDF.BINOM (@var{x}, @var{n}, @var{p})
1458 @deftypefnx {Function} {} RV.BINOM (@var{n}, @var{p})
1459 Binomial distribution with @var{n} trials and probability of success
1460 @var{p}.  Constraints: integer @var{n} > 0, 0 <= @var{p} <= 1, integer
1461 @var{x} <= @var{n}.
1462 @end deftypefn
1463
1464 @deftypefn {Function} {} PDF.GEOM (@var{x}, @var{n}, @var{p})
1465 @deftypefnx {Function} {} CDF.GEOM (@var{x}, @var{n}, @var{p})
1466 @deftypefnx {Function} {} RV.GEOM (@var{n}, @var{p})
1467 Geometric distribution with probability of success @var{p}.
1468 Constraints: 0 <= @var{p} <= 1, integer @var{x} > 0.
1469 @end deftypefn
1470
1471 @deftypefn {Function} {} PDF.HYPER (@var{x}, @var{a}, @var{b}, @var{c})
1472 @deftypefnx {Function} {} CDF.HYPER (@var{x}, @var{a}, @var{b}, @var{c})
1473 @deftypefnx {Function} {} RV.HYPER (@var{a}, @var{b}, @var{c})
1474 Hypergeometric distribution when @var{b} objects out of @var{a} are
1475 drawn and @var{c} of the available objects are distinctive.
1476 Constraints: integer @var{a} > 0, integer @var{b} <= @var{a}, integer
1477 @var{c} <= @var{a}, integer @var{x} >= 0.
1478 @end deftypefn
1479
1480 @deftypefn {Function} {} PDF.LOG (@var{x}, @var{p})
1481 @deftypefnx {Function} {} RV.LOG (@var{p})
1482 Logarithmic distribution with probability parameter @var{p}.
1483 Constraints: 0 <= @var{p} < 1, @var{x} >= 1.
1484 @end deftypefn
1485
1486 @deftypefn {Function} {} PDF.NEGBIN (@var{x}, @var{n}, @var{p})
1487 @deftypefnx {Function} {} CDF.NEGBIN (@var{x}, @var{n}, @var{p})
1488 @deftypefnx {Function} {} RV.NEGBIN (@var{n}, @var{p})
1489 Negative binomial distribution with number of successes parameter
1490 @var{n} and probability of success parameter @var{p}.  Constraints:
1491 integer @var{n} >= 0, 0 < @var{p} <= 1, integer @var{x} >= 1.
1492 @end deftypefn
1493
1494 @deftypefn {Function} {} PDF.POISSON (@var{x}, @var{mu})
1495 @deftypefnx {Function} {} CDF.POISSON (@var{x}, @var{mu})
1496 @deftypefnx {Function} {} RV.POISSON (@var{mu})
1497 Poisson distribution with mean @var{mu}.  Constraints: @var{mu} > 0,
1498 integer @var{x} >= 0.
1499 @end deftypefn
1500
1501 @node Order of Operations
1502 @section Operator Precedence
1503 @cindex operator precedence
1504 @cindex precedence, operator
1505 @cindex order of operations
1506 @cindex operations, order of
1507
1508 The following table describes operator precedence.  Smaller-numbered
1509 levels in the table have higher precedence.  Within a level,
1510 operations are always performed from left to right.  The first
1511 occurrence of @samp{-} represents unary negation, the second binary
1512 subtraction.
1513
1514 @enumerate
1515 @item
1516 @code{(  )}
1517 @item
1518 @code{**}
1519 @item
1520 @code{-}
1521 @item
1522 @code{*  /}
1523 @item
1524 @code{+  -}
1525 @item
1526 @code{EQ  GE  GT  LE  LT  NE}
1527 @item
1528 @code{AND  NOT  OR}
1529 @end enumerate