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