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