better tests
[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 Prevents the user-missing values of @var{variable} from being
451 transformed into system-missing values, and always results in the
452 actual value of @var{variable}, whether it is valid, user-missing, or
453 system-missing.
454 @end deftypefn
455
456 @node Set Membership
457 @subsection Set-Membership Functions
458 @cindex set membership
459 @cindex membership, of set
460
461 Set membership functions determine whether a value is a member of a set.
462 They take a set of numeric arguments or a set of string arguments, and
463 produce Boolean results.
464
465 String comparisons are performed according to the rules given in
466 @ref{Relational Operators}.
467
468 @deftypefn {Function} {} ANY (@var{value}, @var{set} [, @var{set}]@dots{})
469 Results in true if @var{value} is equal to any of the @var{set}
470 values.  Otherwise, results in false.  If @var{value} is
471 system-missing, returns system-missing.  System-missing values in
472 @var{set} do not cause @func{ANY} to return system-missing.
473 @end deftypefn
474
475 @deftypefn {Function} {} RANGE (@var{value}, @var{low}, @var{high} [, @var{low}, @var{high}]@dots{})
476 Results in true if @var{value} is in any of the intervals bounded by
477 @var{low} and @var{high} inclusive.  Otherwise, results in false.
478 Each @var{low} must be less than or equal to its corresponding
479 @var{high} value.  @var{low} and @var{high} must be given in pairs.
480 If @var{value} is system-missing, returns system-missing.
481 System-missing values in @var{set} do not cause @func{RANGE} to return
482 system-missing.
483 @end deftypefn
484
485 @node Statistical Functions
486 @subsection Statistical Functions
487 @cindex functions, statistical
488 @cindex statistics
489
490 Statistical functions compute descriptive statistics on a list of
491 values.  Some statistics can be computed on numeric or string values;
492 other can only be computed on numeric values.  Their results have the
493 same type as their arguments.  The current case's weighting factor
494 (@pxref{WEIGHT}) has no effect on statistical functions.
495
496 These functions' argument lists may include entire ranges of variables
497 using the @code{@var{var1} TO @var{var2}} syntax.
498
499 @cindex arguments, minimum valid
500 @cindex minimum valid number of arguments
501 Unlike most functions, statistical functions can return non-missing
502 values even when some of their arguments are missing.  Most
503 statistical functions, by default, require only 1 non-missing value to
504 have a non-missing return, but @func{CFVAR}, @func{SD}, and @func {VARIANCE} require 2.
505 These defaults can be increased (but not decreased) by appending a dot
506 and the minimum number of valid arguments to the function name.  For
507 example, @subcmd{MEAN.3(X, Y, Z)} would only return non-missing if all
508 of @samp{X}, @samp{Y}, and @samp{Z} were valid.
509
510 @cindex coefficient of variation
511 @cindex variation, coefficient of
512 @deftypefn {Function} {} CFVAR (@var{number}, @var{number}[, @dots{}])
513 Results in the coefficient of variation of the values of @var{number}.
514 (The coefficient of variation is the standard deviation divided by the
515 mean.)
516 @end deftypefn
517
518 @cindex maximum
519 @deftypefn {Function} {} MAX (@var{value}, @var{value}[, @dots{}])
520 Results in the value of the greatest @var{value}.  The @var{value}s may
521 be numeric or string.
522 @end deftypefn
523
524 @cindex mean
525 @deftypefn {Function} {} MEAN (@var{number}, @var{number}[, @dots{}])
526 Results in the mean of the values of @var{number}.
527 @end deftypefn
528
529 @cindex median
530 @deftypefn {Function} {} MEDIAN (@var{number}, @var{number}[, @dots{}])
531 Results in the median of the values of @var{number}.  Given an even
532 number of nonmissing arguments, yields the mean of the two middle
533 values.
534 @end deftypefn
535
536 @cindex minimum
537 @deftypefn {Function} {} MIN (@var{number}, @var{number}[, @dots{}])
538 Results in the value of the least @var{value}.  The @var{value}s may
539 be numeric or string.
540 @end deftypefn
541
542 @cindex standard deviation
543 @cindex deviation, standard
544 @deftypefn {Function} {} SD (@var{number}, @var{number}[, @dots{}])
545 Results in the standard deviation of the values of @var{number}.
546 @end deftypefn
547
548 @cindex sum
549 @deftypefn {Function} {} SUM (@var{number}, @var{number}[, @dots{}])
550 Results in the sum of the values of @var{number}.
551 @end deftypefn
552
553 @cindex variance
554 @deftypefn {Function} {} VARIANCE (@var{number}, @var{number}[, @dots{}])
555 Results in the variance of the values of @var{number}.
556 @end deftypefn
557
558 @node String Functions
559 @subsection String Functions
560 @cindex functions, string
561 @cindex string functions
562
563 String functions take various arguments and return various results.
564
565 @cindex concatenation
566 @cindex strings, concatenation of
567 @deftypefn {Function} {} CONCAT (@var{string}, @var{string}[, @dots{}])
568 Returns a string consisting of each @var{string} in sequence.
569 @code{CONCAT("abc", "def", "ghi")} has a value of @code{"abcdefghi"}.
570 The resultant string is truncated to a maximum of 255 characters.
571 @end deftypefn
572
573 @cindex searching strings
574 @deftypefn {Function} {} INDEX (@var{haystack}, @var{needle})
575 Returns a positive integer indicating the position of the first
576 occurrence of @var{needle} in @var{haystack}.  Returns 0 if @var{haystack}
577 does not contain @var{needle}.  Returns system-missing if @var{needle}
578 is an empty string.
579 @end deftypefn
580
581 @deftypefn {Function} {} INDEX (@var{haystack}, @var{needles}, @var{needle_len})
582 Divides @var{needles} into one or more needles, each with length
583 @var{needle_len}.
584 Searches @var{haystack} for the first occurrence of each needle, and
585 returns the smallest value.  Returns 0 if @var{haystack} does not
586 contain any part in @var{needle}.  It is an error if @var{needle_len}
587 does not evenly divide the length of @var{needles}.  Returns
588 system-missing if @var{needles} is an empty string.
589 @end deftypefn
590
591 @cindex strings, finding length of
592 @deftypefn {Function} {} LENGTH (@var{string})
593 Returns the number of characters in @var{string}.
594 @end deftypefn
595
596 @cindex strings, case of
597 @deftypefn {Function} {} LOWER (@var{string})
598 Returns a string identical to @var{string} except that all uppercase
599 letters are changed to lowercase letters.  The definitions of
600 ``uppercase'' and ``lowercase'' are system-dependent.
601 @end deftypefn
602
603 @cindex strings, padding
604 @deftypefn {Function} {} LPAD (@var{string}, @var{length})
605 If @var{string} is at least @var{length} characters in length, returns
606 @var{string} unchanged.  Otherwise, returns @var{string} padded with
607 spaces on the left side to length @var{length}.  Returns an empty string
608 if @var{length} is system-missing, negative, or greater than 255.
609 @end deftypefn
610
611 @deftypefn {Function} {} LPAD (@var{string}, @var{length}, @var{padding})
612 If @var{string} is at least @var{length} characters in length, returns
613 @var{string} unchanged.  Otherwise, returns @var{string} padded with
614 @var{padding} on the left side to length @var{length}.  Returns an empty
615 string if @var{length} is system-missing, negative, or greater than 255, or
616 if @var{padding} does not contain exactly one character.
617 @end deftypefn
618
619 @cindex strings, trimming
620 @cindex white space, trimming
621 @deftypefn {Function} {} LTRIM (@var{string})
622 Returns @var{string}, after removing leading spaces.  Other white space,
623 such as tabs, carriage returns, line feeds, and vertical tabs, is not
624 removed.
625 @end deftypefn
626
627 @deftypefn {Function} {} LTRIM (@var{string}, @var{padding})
628 Returns @var{string}, after removing leading @var{padding} characters.
629 If @var{padding} does not contain exactly one character, returns an
630 empty string.
631 @end deftypefn
632
633 @cindex numbers, converting from strings
634 @cindex strings, converting to numbers
635 @deftypefn {Function} {} NUMBER (@var{string}, @var{format})
636 Returns the number produced when @var{string} is interpreted according
637 to format specifier @var{format}.  If the format width @var{w} is less
638 than the length of @var{string}, then only the first @var{w}
639 characters in @var{string} are used, @i{e.g.}@: @code{NUMBER("123", F3.0)}
640 and @code{NUMBER("1234", F3.0)} both have value 123.  If @var{w} is
641 greater than @var{string}'s length, then it is treated as if it were
642 right-padded with spaces.  If @var{string} is not in the correct
643 format for @var{format}, system-missing is returned.
644 @end deftypefn
645
646 @cindex strings, replacing substrings
647 @cindex replacing substrings
648 @deftypefn {Function} {} REPLACE (@var{haystack}, @var{needle}, @var{replacement}[, @var{n}])
649 Returns string @var{haystack} with instances of @var{needle} replaced
650 by @var{replacement}.  If nonnegative integer @var{n} is specified, it
651 limits the maximum number of replacements; otherwise, all instances of
652 @var{needle} are replaced.
653 @end deftypefn
654
655 @cindex strings, searching backwards
656 @deftypefn {Function} {} RINDEX (@var{haystack}, @var{needle})
657 Returns a positive integer indicating the position of the last
658 occurrence of @var{needle} in @var{haystack}.  Returns 0 if
659 @var{haystack} does not contain @var{needle}.  Returns system-missing if
660 @var{needle} is an empty string.
661 @end deftypefn
662
663 @deftypefn {Function} {} RINDEX (@var{haystack}, @var{needle}, @var{needle_len})
664 Divides @var{needle} into parts, each with length @var{needle_len}.
665 Searches @var{haystack} for the last occurrence of each part, and
666 returns the largest value.  Returns 0 if @var{haystack} does not contain
667 any part in @var{needle}.  It is an error if @var{needle_len} does not
668 evenly divide the length of @var{needle}.  Returns system-missing
669 if @var{needle} is an empty string or if needle_len is less than 1.
670 @end deftypefn
671
672 @cindex padding strings
673 @cindex strings, padding
674 @deftypefn {Function} {} RPAD (@var{string}, @var{length})
675 If @var{string} is at least @var{length} characters in length, returns
676 @var{string} unchanged.  Otherwise, returns @var{string} padded with
677 spaces on the right to length @var{length}.  Returns an empty string if
678 @var{length} is system-missing, negative, or greater than 255.
679 @end deftypefn
680
681 @deftypefn {Function} {} RPAD (@var{string}, @var{length}, @var{padding})
682 If @var{string} is at least @var{length} characters in length, returns
683 @var{string} unchanged.  Otherwise, returns @var{string} padded with
684 @var{padding} on the right to length @var{length}.  Returns an empty
685 string if @var{length} is system-missing, negative, or greater than 255,
686 or if @var{padding} does not contain exactly one character.
687 @end deftypefn
688
689 @cindex strings, trimming
690 @cindex white space, trimming
691 @deftypefn {Function} {} RTRIM (@var{string})
692 Returns @var{string}, after removing trailing spaces.  Other types of
693 white space are not removed.
694 @end deftypefn
695
696 @deftypefn {Function} {} RTRIM (@var{string}, @var{padding})
697 Returns @var{string}, after removing trailing @var{padding} characters.
698 If @var{padding} does not contain exactly one character, returns an
699 empty string.
700 @end deftypefn
701
702 @cindex strings, converting from numbers
703 @cindex numbers, converting to strings
704 @deftypefn {Function} {} STRING (@var{number}, @var{format})
705 Returns a string corresponding to @var{number} in the format given by
706 format specifier @var{format}.  For example, @code{STRING(123.56, F5.1)}
707 has the value @code{"123.6"}.
708 @end deftypefn
709
710 @cindex strings, trimming
711 @cindex strings, truncating
712 @cindex white space, trimming
713 @deftypefn {Function} {} STRUNC (@var{string}, @var{n})
714 Returns @var{string}, first trimming it to at most @var{n} bytes, then
715 removing trailing spaces.  Returns an empty string if @var{n} is
716 missing or negative.
717 @end deftypefn
718
719 @cindex substrings
720 @cindex strings, taking substrings of
721 @deftypefn {Function} {} SUBSTR (@var{string}, @var{start})
722 Returns a string consisting of the value of @var{string} from position
723 @var{start} onward.  Returns an empty string if @var{start} is system-missing,
724 less than 1, or greater than the length of @var{string}.
725 @end deftypefn
726
727 @deftypefn {Function} {} SUBSTR (@var{string}, @var{start}, @var{count})
728 Returns a string consisting of the first @var{count} characters from
729 @var{string} beginning at position @var{start}.  Returns an empty string
730 if @var{start} or @var{count} is system-missing, if @var{start} is less
731 than 1 or greater than the number of characters in @var{string}, or if
732 @var{count} is less than 1.  Returns a string shorter than @var{count}
733 characters if @var{start} + @var{count} - 1 is greater than the number
734 of characters in @var{string}.  Examples: @code{SUBSTR("abcdefg", 3, 2)}
735 has value @code{"cd"}; @code{SUBSTR("nonsense", 4, 10)} has the value
736 @code{"sense"}.
737 @end deftypefn
738
739 @cindex case conversion
740 @cindex strings, case of
741 @deftypefn {Function} {} UPCASE (@var{string})
742 Returns @var{string}, changing lowercase letters to uppercase letters.
743 @end deftypefn
744
745 @node Time and Date
746 @subsection Time & Date Functions
747 @cindex functions, time & date
748 @cindex times
749 @cindex dates
750
751 @cindex dates, valid
752 For compatibility, @pspp{} considers dates before 15 Oct 1582 invalid.
753 Most time and date functions will not accept earlier dates.
754
755 @menu
756 * Time and Date Concepts::      How times & dates are defined and represented
757 * Time Construction::           TIME.@{DAYS HMS@}
758 * Time Extraction::             CTIME.@{DAYS HOURS MINUTES SECONDS@}
759 * Date Construction::           DATE.@{DMY MDY MOYR QYR WKYR YRDAY@}
760 * Date Extraction::             XDATE.@{DATE HOUR JDAY MDAY MINUTE MONTH
761                                        QUARTER SECOND TDAY TIME WEEK
762                                        WKDAY YEAR@}
763 * Time and Date Arithmetic::    DATEDIFF DATESUM
764 @end menu
765
766 @node Time and Date Concepts
767 @subsubsection How times & dates are defined and represented
768
769 @cindex time, concepts
770 @cindex time, intervals
771 Times and dates are handled by @pspp{} as single numbers.  A
772 @dfn{time} is an interval.  @pspp{} measures times in seconds.
773 Thus, the following intervals correspond with the numeric values given:
774
775 @example
776           10 minutes                        600
777           1 hour                          3,600
778           1 day, 3 hours, 10 seconds     97,210
779           40 days                     3,456,000
780 @end example
781
782 @cindex dates, concepts
783 @cindex time, instants of
784 A @dfn{date}, on the other hand, is a particular instant in the past
785 or the future.  @pspp{} represents a date as a number of seconds since
786 midnight preceding 14 Oct 1582.  Because midnight preceding the dates
787 given below correspond with the numeric @pspp{} dates given:
788
789 @example
790               15 Oct 1582                86,400
791                4 Jul 1776         6,113,318,400
792                1 Jan 1900        10,010,390,400
793                1 Oct 1978        12,495,427,200
794               24 Aug 1995        13,028,601,600
795 @end example
796
797 @node Time Construction
798 @subsubsection Functions that Produce Times
799 @cindex times, constructing
800 @cindex constructing times
801
802 These functions take numeric arguments and return numeric values that
803 represent times.
804
805 @cindex days
806 @cindex time, in days
807 @deftypefn {Function} {} TIME.DAYS (@var{ndays})
808 Returns a time corresponding to @var{ndays} days.
809 @end deftypefn
810
811 @cindex hours-minutes-seconds
812 @cindex time, in hours-minutes-seconds
813 @deftypefn {Function} {} TIME.HMS (@var{nhours}, @var{nmins}, @var{nsecs})
814 Returns a time corresponding to @var{nhours} hours, @var{nmins}
815 minutes, and @var{nsecs} seconds.  The arguments may not have mixed
816 signs: if any of them are positive, then none may be negative, and
817 vice versa.
818 @end deftypefn
819
820 @node Time Extraction
821 @subsubsection Functions that Examine Times
822 @cindex extraction, of time
823 @cindex time examination
824 @cindex examination, of times
825 @cindex time, lengths of
826
827 These functions take numeric arguments in @pspp{} time format and
828 give numeric results.
829
830 @cindex days
831 @cindex time, in days
832 @deftypefn {Function} {} CTIME.DAYS (@var{time})
833 Results in the number of days and fractional days in @var{time}.
834 @end deftypefn
835
836 @cindex hours
837 @cindex time, in hours
838 @deftypefn {Function} {} CTIME.HOURS (@var{time})
839 Results in the number of hours and fractional hours in @var{time}.
840 @end deftypefn
841
842 @cindex minutes
843 @cindex time, in minutes
844 @deftypefn {Function} {} CTIME.MINUTES (@var{time})
845 Results in the number of minutes and fractional minutes in @var{time}.
846 @end deftypefn
847
848 @cindex seconds
849 @cindex time, in seconds
850 @deftypefn {Function} {} CTIME.SECONDS (@var{time})
851 Results in the number of seconds and fractional seconds in @var{time}.
852 (@code{CTIME.SECONDS} does nothing; @code{CTIME.SECONDS(@var{x})} is
853 equivalent to @code{@var{x}}.)
854 @end deftypefn
855
856 @node Date Construction
857 @subsubsection Functions that Produce Dates
858 @cindex dates, constructing
859 @cindex constructing dates
860
861 @cindex arguments, of date construction functions
862 These functions take numeric arguments and give numeric results that
863 represent dates.  Arguments taken by these functions are:
864
865 @table @var
866 @item day
867 Refers to a day of the month between 1 and 31.  Day 0 is also accepted
868 and refers to the final day of the previous month.  Days 29, 30, and
869 31 are accepted even in months that have fewer days and refer to a day
870 near the beginning of the following month.
871
872 @item month
873 Refers to a month of the year between 1 and 12.  Months 0 and 13 are
874 also accepted and refer to the last month of the preceding year and
875 the first month of the following year, respectively.
876
877 @item quarter
878 Refers to a quarter of the year between 1 and 4.  The quarters of the
879 year begin on the first day of months 1, 4, 7, and 10.
880
881 @item week
882 Refers to a week of the year between 1 and 53.
883
884 @item yday
885 Refers to a day of the year between 1 and 366.
886
887 @item year
888 Refers to a year, 1582 or greater.  Years between 0 and 99 are treated
889 according to the epoch set on SET EPOCH, by default beginning 69 years
890 before the current date (@pxref{SET EPOCH}).
891 @end table
892
893 @cindex arguments, invalid
894 If these functions' arguments are out-of-range, they are correctly
895 normalized before conversion to date format.  Non-integers are rounded
896 toward zero.
897
898 @cindex day-month-year
899 @cindex dates, day-month-year
900 @deftypefn {Function} {} DATE.DMY (@var{day}, @var{month}, @var{year})
901 @deftypefnx {Function} {} DATE.MDY (@var{month}, @var{day}, @var{year})
902 Results in a date value corresponding to the midnight before day
903 @var{day} of month @var{month} of year @var{year}.
904 @end deftypefn
905
906 @cindex month-year
907 @cindex dates, month-year
908 @deftypefn {Function} {} DATE.MOYR (@var{month}, @var{year})
909 Results in a date value corresponding to the midnight before the first
910 day of month @var{month} of year @var{year}.
911 @end deftypefn
912
913 @cindex quarter-year
914 @cindex dates, quarter-year
915 @deftypefn {Function} {} DATE.QYR (@var{quarter}, @var{year})
916 Results in a date value corresponding to the midnight before the first
917 day of quarter @var{quarter} of year @var{year}.
918 @end deftypefn
919
920 @cindex week-year
921 @cindex dates, week-year
922 @deftypefn {Function} {} DATE.WKYR (@var{week}, @var{year})
923 Results in a date value corresponding to the midnight before the first
924 day of week @var{week} of year @var{year}.
925 @end deftypefn
926
927 @cindex year-day
928 @cindex dates, year-day
929 @deftypefn {Function} {} DATE.YRDAY (@var{year}, @var{yday})
930 Results in a date value corresponding to the day
931 @var{yday} of year @var{year}.
932 @end deftypefn
933
934 @node Date Extraction
935 @subsubsection Functions that Examine Dates
936 @cindex extraction, of dates
937 @cindex date examination
938
939 @cindex arguments, of date extraction functions
940 These functions take numeric arguments in @pspp{} date or time
941 format and give numeric results.  These names are used for arguments:
942
943 @table @var
944 @item date
945 A numeric value in @pspp{} date format.
946
947 @item time
948 A numeric value in @pspp{} time format.
949
950 @item time-or-date
951 A numeric value in @pspp{} time or date format.
952 @end table
953
954 @cindex days
955 @cindex dates, in days
956 @cindex time, in days
957 @deftypefn {Function} {} XDATE.DATE (@var{time-or-date})
958 For a time, results in the time corresponding to the number of whole
959 days @var{date-or-time} includes.  For a date, results in the date
960 corresponding to the latest midnight at or before @var{date-or-time};
961 that is, gives the date that @var{date-or-time} is in.
962 @end deftypefn
963
964 @cindex hours
965 @cindex dates, in hours
966 @cindex time, in hours
967 @deftypefn {Function} {} XDATE.HOUR (@var{time-or-date})
968 For a time, results in the number of whole hours beyond the number of
969 whole days represented by @var{date-or-time}.  For a date, results in
970 the hour (as an integer between 0 and 23) corresponding to
971 @var{date-or-time}.
972 @end deftypefn
973
974 @cindex day of the year
975 @cindex dates, day of the year
976 @deftypefn {Function} {} XDATE.JDAY (@var{date})
977 Results in the day of the year (as an integer between 1 and 366)
978 corresponding to @var{date}.
979 @end deftypefn
980
981 @cindex day of the month
982 @cindex dates, day of the month
983 @deftypefn {Function} {} XDATE.MDAY (@var{date})
984 Results in the day of the month (as an integer between 1 and 31)
985 corresponding to @var{date}.
986 @end deftypefn
987
988 @cindex minutes
989 @cindex dates, in minutes
990 @cindex time, in minutes
991 @deftypefn {Function} {} XDATE.MINUTE (@var{time-or-date})
992 Results in the number of minutes (as an integer between 0 and 59) after
993 the last hour in @var{time-or-date}.
994 @end deftypefn
995
996 @cindex months
997 @cindex dates, in months
998 @deftypefn {Function} {} XDATE.MONTH (@var{date})
999 Results in the month of the year (as an integer between 1 and 12)
1000 corresponding to @var{date}.
1001 @end deftypefn
1002
1003 @cindex quarters
1004 @cindex dates, in quarters
1005 @deftypefn {Function} {} XDATE.QUARTER (@var{date})
1006 Results in the quarter of the year (as an integer between 1 and 4)
1007 corresponding to @var{date}.
1008 @end deftypefn
1009
1010 @cindex seconds
1011 @cindex dates, in seconds
1012 @cindex time, in seconds
1013 @deftypefn {Function} {} XDATE.SECOND (@var{time-or-date})
1014 Results in the number of whole seconds after the last whole minute (as
1015 an integer between 0 and 59) in @var{time-or-date}.
1016 @end deftypefn
1017
1018 @cindex days
1019 @cindex times, in days
1020 @deftypefn {Function} {} XDATE.TDAY (@var{date})
1021 Results in the number of whole days from 14 Oct 1582 to @var{date}.
1022 @end deftypefn
1023
1024 @cindex time
1025 @cindex dates, time of day
1026 @deftypefn {Function} {} XDATE.TIME (@var{date})
1027 Results in the time of day at the instant corresponding to @var{date},
1028 as a time value.  This is the number of seconds since
1029 midnight on the day corresponding to @var{date}.
1030 @end deftypefn
1031
1032 @cindex week
1033 @cindex dates, in weeks
1034 @deftypefn {Function} {} XDATE.WEEK (@var{date})
1035 Results in the week of the year (as an integer between 1 and 53)
1036 corresponding to @var{date}.
1037 @end deftypefn
1038
1039 @cindex day of the week
1040 @cindex weekday
1041 @cindex dates, day of the week
1042 @cindex dates, in weekdays
1043 @deftypefn {Function} {} XDATE.WKDAY (@var{date})
1044 Results in the day of week (as an integer between 1 and 7) corresponding
1045 to @var{date}, where 1 represents Sunday.
1046 @end deftypefn
1047
1048 @cindex years
1049 @cindex dates, in years
1050 @deftypefn {Function} {} XDATE.YEAR (@var{date})
1051 Returns the year (as an integer 1582 or greater) corresponding to
1052 @var{date}.
1053 @end deftypefn
1054
1055 @node Time and Date Arithmetic
1056 @subsubsection Time and Date Arithmetic
1057
1058 @cindex time, mathematical properties of
1059 @cindex mathematics, applied to times & dates
1060 @cindex dates, mathematical properties of
1061 @noindent
1062 Ordinary arithmetic operations on dates and times often produce
1063 sensible results.  Adding a time to, or subtracting one from, a date
1064 produces a new date that much earlier or later.  The difference of two
1065 dates yields the time between those dates.  Adding two times produces
1066 the combined time.  Multiplying a time by a scalar produces a time
1067 that many times longer.  Since times and dates are just numbers, the
1068 ordinary addition and subtraction operators are employed for these
1069 purposes.
1070
1071 Adding two dates does not produce a useful result.
1072
1073 Dates and times may have very large values.  Thus,
1074 it is not a good idea to take powers of these values; also, the
1075 accuracy of some procedures may be affected.  If necessary, convert
1076 times or dates in seconds to some other unit, like days or years,
1077 before performing analysis.
1078
1079 @pspp{} supplies a few functions for date arithmetic:
1080
1081 @deftypefn {Function} {} DATEDIFF (@var{date2}, @var{date1}, @var{unit})
1082 Returns the span of time from @var{date1} to @var{date2} in terms of
1083 @var{unit}, which must be a quoted string, one of @samp{years},
1084 @samp{quarters}, @samp{months}, @samp{weeks}, @samp{days},
1085 @samp{hours}, @samp{minutes}, and @samp{seconds}.  The result is an
1086 integer, truncated toward zero.
1087
1088 One year is considered to span from a given date to the same month,
1089 day, and time of day the next year.  Thus, from Jan.@tie{}1 of one
1090 year to Jan.@tie{}1 the next year is considered to be a full year, but
1091 Feb.@tie{}29 of a leap year to the following Feb.@tie{}28 is not.
1092 Similarly, one month spans from a given day of the month to the same
1093 day of the following month.  Thus, there is never a full month from
1094 Jan.@tie{}31 of a given year to any day in the following February.
1095 @end deftypefn
1096
1097 @deftypefn {Function} {} DATESUM (@var{date}, @var{quantity}, @var{unit}[, @var{method}])
1098 Returns @var{date} advanced by the given @var{quantity} of the
1099 specified @var{unit}, which must be one of the strings @samp{years},
1100 @samp{quarters}, @samp{months}, @samp{weeks}, @samp{days},
1101 @samp{hours}, @samp{minutes}, and @samp{seconds}.
1102
1103 When @var{unit} is @samp{years}, @samp{quarters}, or @samp{months},
1104 only the integer part of @var{quantity} is considered.  Adding one of
1105 these units can cause the day of the month to exceed the number of
1106 days in the month.  In this case, the @var{method} comes into
1107 play: if it is omitted or specified as @samp{closest} (as a quoted
1108 string), then the resulting day is the last day of the month;
1109 otherwise, if it is specified as @samp{rollover}, then the extra days
1110 roll over into the following month.
1111
1112 When @var{unit} is @samp{weeks}, @samp{days}, @samp{hours},
1113 @samp{minutes}, or @samp{seconds}, the @var{quantity} is not rounded
1114 to an integer and @var{method}, if specified, is ignored.
1115 @end deftypefn
1116
1117 @node Miscellaneous Functions
1118 @subsection Miscellaneous Functions
1119 @cindex functions, miscellaneous
1120
1121 @cindex cross-case function
1122 @cindex function, cross-case
1123 @deftypefn {Function} {} LAG (@var{variable}[, @var{n}])
1124 @anchor{LAG}
1125
1126 @var{variable} must be a numeric or string variable name.  @code{LAG}
1127 yields the value of that variable for the case @var{n} before the
1128 current one.  Results in system-missing (for numeric variables) or
1129 blanks (for string variables) for the first @var{n} cases.
1130
1131 @code{LAG} obtains values from the cases that become the new active
1132 dataset
1133 after a procedure executes.  Thus, @code{LAG} will not return values
1134 from cases dropped by transformations such as @cmd{SELECT IF}, and
1135 transformations like @cmd{COMPUTE} that modify data will change the
1136 values returned by @code{LAG}.  These are both the case whether these
1137 transformations precede or follow the use of @code{LAG}.
1138
1139 If @code{LAG} is used before @cmd{TEMPORARY}, then the values it returns
1140 are those in cases just before @cmd{TEMPORARY}.  @code{LAG} may not be
1141 used after @cmd{TEMPORARY}.
1142
1143 If omitted, @var{ncases} defaults to 1.  Otherwise, @var{ncases} must
1144 be a small positive constant integer.  There is no explicit limit, but
1145 use of a large value will increase memory consumption.
1146 @end deftypefn
1147
1148 @cindex date, Julian
1149 @cindex Julian date
1150 @deftypefn {Function} {} YRMODA (@var{year}, @var{month}, @var{day})
1151 @var{year} is a year, either between 0 and 99 or at least 1582.
1152 Unlike other @pspp{} date functions, years between 0 and 99 always
1153 correspond to 1900 through 1999.  @var{month} is a month between 1 and
1154 13.  @var{day} is a day between 0 and 31.  A @var{day} of 0 refers to
1155 the last day of the previous month, and a @var{month} of 13 refers to
1156 the first month of the next year.  @var{year} must be in range.
1157 @var{year}, @var{month}, and @var{day} must all be integers.
1158
1159 @code{YRMODA} results in the number of days between 15 Oct 1582 and
1160 the date specified, plus one.  The date passed to @code{YRMODA} must be
1161 on or after 15 Oct 1582.  15 Oct 1582 has a value of 1.
1162 @end deftypefn
1163
1164 @cindex value label
1165 @deftypefn {Function} VALUELABEL (@var{variable})
1166 Returns a string matching the label associated with the current value
1167 of @var{variable}.  If the current value of @var{variable} has no
1168 associated label, then this function returns the empty string.
1169 @var{variable} may be a numeric or string variable.
1170 @end deftypefn
1171
1172 @node Statistical Distribution Functions
1173 @subsection Statistical Distribution Functions
1174
1175 @pspp{} can calculate several functions of standard statistical
1176 distributions.  These functions are named systematically based on the
1177 function and the distribution.  The table below describes the
1178 statistical distribution functions in general:
1179
1180 @table @asis
1181 @item PDF.@var{dist} (@var{x}[, @var{param}@dots{}])
1182 Probability density function for @var{dist}.  The domain of @var{x}
1183 depends on @var{dist}.  For continuous distributions, the result is
1184 the density of the probability function at @var{x}, and the range is
1185 nonnegative real numbers.  For discrete distributions, the result is
1186 the probability of @var{x}.
1187
1188 @item CDF.@var{dist} (@var{x}[, @var{param}@dots{}])
1189 Cumulative distribution function for @var{dist}, that is, the
1190 probability that a random variate drawn from the distribution is less
1191 than @var{x}.  The domain of @var{x} depends @var{dist}.  The result is
1192 a probability.
1193
1194 @item SIG.@var{dist} (@var{x}[, @var{param}@dots{})
1195 Tail probability function for @var{dist}, that is, the probability
1196 that a random variate drawn from the distribution is greater than
1197 @var{x}.  The domain of @var{x} depends @var{dist}.  The result is a
1198 probability.  Only a few distributions include an @func{SIG} function.
1199
1200 @item IDF.@var{dist} (@var{p}[, @var{param}@dots{}])
1201 Inverse distribution function for @var{dist}, the value of @var{x} for
1202 which the CDF would yield @var{p}.  The value of @var{p} is a
1203 probability.  The range depends on @var{dist} and is identical to the
1204 domain for the corresponding CDF.
1205
1206 @item RV.@var{dist} ([@var{param}@dots{}])
1207 Random variate function for @var{dist}.  The range depends on the
1208 distribution.
1209
1210 @item NPDF.@var{dist} (@var{x}[, @var{param}@dots{}])
1211 Noncentral probability density function.  The result is the density of
1212 the given noncentral distribution at @var{x}.  The domain of @var{x}
1213 depends on @var{dist}.  The range is nonnegative real numbers.  Only a
1214 few distributions include an @func{NPDF} function.
1215
1216 @item NCDF.@var{dist} (@var{x}[, @var{param}@dots{}])
1217 Noncentral cumulative distribution function for @var{dist}, that is,
1218 the probability that a random variate drawn from the given noncentral
1219 distribution is less than @var{x}.  The domain of @var{x} depends
1220 @var{dist}.  The result is a probability.  Only a few distributions
1221 include an NCDF function.
1222 @end table
1223
1224 The individual distributions are described individually below.
1225
1226 @menu
1227 * Continuous Distributions::
1228 * Discrete Distributions::
1229 @end menu
1230
1231 @node Continuous Distributions
1232 @subsubsection Continuous Distributions
1233
1234 The following continuous distributions are available:
1235
1236 @deftypefn {Function} {} PDF.BETA (@var{x})
1237 @deftypefnx {Function} {} CDF.BETA (@var{x}, @var{a}, @var{b})
1238 @deftypefnx {Function} {} IDF.BETA (@var{p}, @var{a}, @var{b})
1239 @deftypefnx {Function} {} RV.BETA (@var{a}, @var{b})
1240 @deftypefnx {Function} {} NPDF.BETA (@var{x}, @var{a}, @var{b}, @var{lambda})
1241 @deftypefnx {Function} {} NCDF.BETA (@var{x}, @var{a}, @var{b}, @var{lambda})
1242 Beta distribution with shape parameters @var{a} and @var{b}.  The
1243 noncentral distribution takes an additional parameter @var{lambda}.
1244 Constraints: @var{a} > 0, @var{b} > 0, @var{lambda} >= 0, 0 <= @var{x}
1245 <= 1, 0 <= @var{p} <= 1.
1246 @end deftypefn
1247
1248 @deftypefn {Function} {} PDF.BVNOR (@var{x0}, @var{x1}, @var{rho})
1249 @deftypefnx {Function} {} CDF.BVNOR (@var{x0}, @var{x1}, @var{rho})
1250 Bivariate normal distribution of two standard normal variables with
1251 correlation coefficient @var{rho}.  Two variates @var{x0} and @var{x1}
1252 must be provided.  Constraints: 0 <= @var{rho} <= 1, 0 <= @var{p} <= 1.
1253 @end deftypefn
1254
1255 @deftypefn {Function} {} PDF.CAUCHY (@var{x}, @var{a}, @var{b})
1256 @deftypefnx {Function} {} CDF.CAUCHY (@var{x}, @var{a}, @var{b})
1257 @deftypefnx {Function} {} IDF.CAUCHY (@var{p}, @var{a}, @var{b})
1258 @deftypefnx {Function} {} RV.CAUCHY (@var{a}, @var{b})
1259 Cauchy distribution with location parameter @var{a} and scale
1260 parameter @var{b}.  Constraints: @var{b} > 0, 0 < @var{p} < 1.
1261 @end deftypefn
1262
1263 @c @deftypefn {Function} {} PDF.CHISQ (@var{x}, @var{df})
1264 @deftypefn {Function} {} CDF.CHISQ (@var{x}, @var{df})
1265 @deftypefnx {Function} {} SIG.CHISQ (@var{x}, @var{df})
1266 @deftypefnx {Function} {} IDF.CHISQ (@var{p}, @var{df})
1267 @deftypefnx {Function} {} RV.CHISQ (@var{df})
1268 @c @deftypefnx {Function} {} NPDF.CHISQ (@var{x}, @var{df}, @var{lambda})
1269 @deftypefnx {Function} {} NCDF.CHISQ (@var{x}, @var{df}, @var{lambda})
1270 Chi-squared distribution with @var{df} degrees of freedom.  The
1271 noncentral distribution takes an additional parameter @var{lambda}.
1272 Constraints: @var{df} > 0, @var{lambda} > 0, @var{x} >= 0, 0 <=
1273 @var{p} < 1.
1274 @end deftypefn
1275
1276 @deftypefn {Function} {} PDF.EXP (@var{x}, @var{a})
1277 @deftypefnx {Function} {} CDF.EXP (@var{x}, @var{a})
1278 @deftypefnx {Function} {} IDF.EXP (@var{p}, @var{a})
1279 @deftypefnx {Function} {} RV.EXP (@var{a})
1280 Exponential distribution with scale parameter @var{a}.  The inverse of
1281 @var{a} represents the rate of decay.  Constraints: @var{a} > 0,
1282 @var{x} >= 0, 0 <= @var{p} < 1.
1283 @end deftypefn
1284
1285 @deftypefn {Function} {} PDF.XPOWER (@var{x}, @var{a}, @var{b})
1286 @deftypefnx {Function} {} RV.XPOWER (@var{a}, @var{b})
1287 Exponential power distribution with positive scale parameter @var{a}
1288 and nonnegative power parameter @var{b}.  Constraints: @var{a} > 0,
1289 @var{b} >= 0, @var{x} >= 0, 0 <= @var{p} <= 1.  This distribution is a
1290 @pspp{} extension.
1291 @end deftypefn
1292
1293 @deftypefn {Function} {} PDF.F (@var{x}, @var{df1}, @var{df2})
1294 @deftypefnx {Function} {} CDF.F (@var{x}, @var{df1}, @var{df2})
1295 @deftypefnx {Function} {} SIG.F (@var{x}, @var{df1}, @var{df2})
1296 @deftypefnx {Function} {} IDF.F (@var{p}, @var{df1}, @var{df2})
1297 @deftypefnx {Function} {} RV.F (@var{df1}, @var{df2})
1298 @c @deftypefnx {Function} {} NPDF.F (@var{x}, @var{df1}, @var{df2}, @var{lambda})
1299 @c @deftypefnx {Function} {} NCDF.F (@var{x}, @var{df1}, @var{df2}, @var{lambda})
1300 F-distribution of two chi-squared deviates with @var{df1} and
1301 @var{df2} degrees of freedom.  The noncentral distribution takes an
1302 additional parameter @var{lambda}.  Constraints: @var{df1} > 0,
1303 @var{df2} > 0, @var{lambda} >= 0, @var{x} >= 0, 0 <= @var{p} < 1.
1304 @end deftypefn
1305
1306 @deftypefn {Function} {} PDF.GAMMA (@var{x}, @var{a}, @var{b})
1307 @deftypefnx {Function} {} CDF.GAMMA (@var{x}, @var{a}, @var{b})
1308 @deftypefnx {Function} {} IDF.GAMMA (@var{p}, @var{a}, @var{b})
1309 @deftypefnx {Function} {} RV.GAMMA (@var{a}, @var{b})
1310 Gamma distribution with shape parameter @var{a} and scale parameter
1311 @var{b}.  Constraints: @var{a} > 0, @var{b} > 0, @var{x} >= 0, 0 <=
1312 @var{p} < 1.
1313 @end deftypefn
1314
1315 @c @deftypefn {Function} {} PDF.HALFNRM (@var{x}, @var{a}, @var{b})
1316 @c @deftypefnx {Function} {} CDF.HALFNRM (@var{x}, @var{a}, @var{b})
1317 @c @deftypefnx {Function} {} IDF.HALFNRM (@var{p}, @var{a}, @var{b})
1318 @c @deftypefnx {Function} {} RV.HALFNRM (@var{a}, @var{b})
1319 @c Half-normal distribution with location parameter @var{a} and shape
1320 @c parameter @var{b}.  Constraints: @var{b} > 0, 0 < @var{p} < 1.
1321 @c @end deftypefn
1322
1323 @c @deftypefn {Function} {} PDF.IGAUSS (@var{x}, @var{a}, @var{b})
1324 @c @deftypefnx {Function} {} CDF.IGAUSS (@var{x}, @var{a}, @var{b})
1325 @c @deftypefnx {Function} {} IDF.IGAUSS (@var{p}, @var{a}, @var{b})
1326 @c @deftypefnx {Function} {} RV.IGAUSS (@var{a}, @var{b})
1327 @c Inverse Gaussian distribution with parameters @var{a} and @var{b}.
1328 @c Constraints: @var{a} > 0, @var{b} > 0, @var{x} > 0, 0 <= @var{p} < 1.
1329 @c @end deftypefn
1330
1331 @deftypefn {Function} {} PDF.LANDAU (@var{x})
1332 @deftypefnx {Function} {} RV.LANDAU ()
1333 Landau distribution.
1334 @end deftypefn
1335
1336 @deftypefn {Function} {} PDF.LAPLACE (@var{x}, @var{a}, @var{b})
1337 @deftypefnx {Function} {} CDF.LAPLACE (@var{x}, @var{a}, @var{b})
1338 @deftypefnx {Function} {} IDF.LAPLACE (@var{p}, @var{a}, @var{b})
1339 @deftypefnx {Function} {} RV.LAPLACE (@var{a}, @var{b})
1340 Laplace distribution with location parameter @var{a} and scale
1341 parameter @var{b}.  Constraints: @var{b} > 0, 0 < @var{p} < 1.
1342 @end deftypefn
1343
1344 @deftypefn {Function} {} RV.LEVY (@var{c}, @var{alpha})
1345 Levy symmetric alpha-stable distribution with scale @var{c} and
1346 exponent @var{alpha}.  Constraints: 0 < @var{alpha} <= 2.
1347 @end deftypefn
1348
1349 @deftypefn {Function} {} RV.LVSKEW (@var{c}, @var{alpha}, @var{beta})
1350 Levy skew alpha-stable distribution with scale @var{c}, exponent
1351 @var{alpha}, and skewness parameter @var{beta}.  Constraints: 0 <
1352 @var{alpha} <= 2, -1 <= @var{beta} <= 1.
1353 @end deftypefn
1354
1355 @deftypefn {Function} {} PDF.LOGISTIC (@var{x}, @var{a}, @var{b})
1356 @deftypefnx {Function} {} CDF.LOGISTIC (@var{x}, @var{a}, @var{b})
1357 @deftypefnx {Function} {} IDF.LOGISTIC (@var{p}, @var{a}, @var{b})
1358 @deftypefnx {Function} {} RV.LOGISTIC (@var{a}, @var{b})
1359 Logistic distribution with location parameter @var{a} and scale
1360 parameter @var{b}.  Constraints: @var{b} > 0, 0 < @var{p} < 1.
1361 @end deftypefn
1362
1363 @deftypefn {Function} {} PDF.LNORMAL (@var{x}, @var{a}, @var{b})
1364 @deftypefnx {Function} {} CDF.LNORMAL (@var{x}, @var{a}, @var{b})
1365 @deftypefnx {Function} {} IDF.LNORMAL (@var{p}, @var{a}, @var{b})
1366 @deftypefnx {Function} {} RV.LNORMAL (@var{a}, @var{b})
1367 Lognormal distribution with parameters @var{a} and @var{b}.
1368 Constraints: @var{a} > 0, @var{b} > 0, @var{x} >= 0, 0 <= @var{p} < 1.
1369 @end deftypefn
1370
1371 @deftypefn {Function} {} PDF.NORMAL (@var{x}, @var{mu}, @var{sigma})
1372 @deftypefnx {Function} {} CDF.NORMAL (@var{x}, @var{mu}, @var{sigma})
1373 @deftypefnx {Function} {} IDF.NORMAL (@var{p}, @var{mu}, @var{sigma})
1374 @deftypefnx {Function} {} RV.NORMAL (@var{mu}, @var{sigma})
1375 Normal distribution with mean @var{mu} and standard deviation
1376 @var{sigma}.  Constraints: @var{b} > 0, 0 < @var{p} < 1.  Three
1377 additional functions are available as shorthand:
1378
1379 @deftypefn {Function} {} CDFNORM (@var{x})
1380 Equivalent to CDF.NORMAL(@var{x}, 0, 1).
1381 @end deftypefn
1382
1383 @deftypefn {Function} {} PROBIT (@var{p})
1384 Equivalent to IDF.NORMAL(@var{p}, 0, 1).
1385 @end deftypefn
1386
1387 @deftypefn {Function} {} NORMAL (@var{sigma})
1388 Equivalent to RV.NORMAL(0, @var{sigma}).
1389 @end deftypefn
1390 @end deftypefn
1391
1392 @deftypefn {Function} {} PDF.NTAIL (@var{x}, @var{a}, @var{sigma})
1393 @deftypefnx {Function} {} RV.NTAIL (@var{a}, @var{sigma})
1394 Normal tail distribution with lower limit @var{a} and standard
1395 deviation @var{sigma}.  This distribution is a @pspp{} extension.
1396 Constraints: @var{a} > 0, @var{x} > @var{a}, 0 < @var{p} < 1.
1397 @end deftypefn
1398
1399 @deftypefn {Function} {} PDF.PARETO (@var{x}, @var{a}, @var{b})
1400 @deftypefnx {Function} {} CDF.PARETO (@var{x}, @var{a}, @var{b})
1401 @deftypefnx {Function} {} IDF.PARETO (@var{p}, @var{a}, @var{b})
1402 @deftypefnx {Function} {} RV.PARETO (@var{a}, @var{b})
1403 Pareto distribution with threshold parameter @var{a} and shape
1404 parameter @var{b}.  Constraints: @var{a} > 0, @var{b} > 0, @var{x} >=
1405 @var{a}, 0 <= @var{p} < 1.
1406 @end deftypefn
1407
1408 @deftypefn {Function} {} PDF.RAYLEIGH (@var{x}, @var{sigma})
1409 @deftypefnx {Function} {} CDF.RAYLEIGH (@var{x}, @var{sigma})
1410 @deftypefnx {Function} {} IDF.RAYLEIGH (@var{p}, @var{sigma})
1411 @deftypefnx {Function} {} RV.RAYLEIGH (@var{sigma})
1412 Rayleigh distribution with scale parameter @var{sigma}.  This
1413 distribution is a @pspp{} extension.  Constraints: @var{sigma} > 0,
1414 @var{x} > 0.
1415 @end deftypefn
1416
1417 @deftypefn {Function} {} PDF.RTAIL (@var{x}, @var{a}, @var{sigma})
1418 @deftypefnx {Function} {} RV.RTAIL (@var{a}, @var{sigma})
1419 Rayleigh tail distribution with lower limit @var{a} and scale
1420 parameter @var{sigma}.  This distribution is a @pspp{} extension.
1421 Constraints: @var{a} > 0, @var{sigma} > 0, @var{x} > @var{a}.
1422 @end deftypefn
1423
1424 @c @deftypefn {Function} {} CDF.SMOD (@var{x}, @var{a}, @var{b})
1425 @c @deftypefnx {Function} {} IDF.SMOD (@var{p}, @var{a}, @var{b})
1426 @c Studentized maximum modulus distribution with parameters @var{a} and
1427 @c @var{b}.  Constraints: @var{a} > 0, @var{b} > 0, @var{x} > 0, 0 <=
1428 @c @var{p} < 1.
1429 @c @end deftypefn
1430
1431 @c @deftypefn {Function} {} CDF.SRANGE (@var{x}, @var{a}, @var{b})
1432 @c @deftypefnx {Function} {} IDF.SRANGE (@var{p}, @var{a}, @var{b})
1433 @c Studentized range distribution with parameters @var{a} and @var{b}.
1434 @c Constraints:  @var{a} >= 1, @var{b} >= 1, @var{x} > 0, 0 <= @var{p} <
1435 @c 1.
1436 @c @end deftypefn
1437
1438 @deftypefn {Function} {} PDF.T (@var{x}, @var{df})
1439 @deftypefnx {Function} {} CDF.T (@var{x}, @var{df})
1440 @deftypefnx {Function} {} IDF.T (@var{p}, @var{df})
1441 @deftypefnx {Function} {} RV.T (@var{df})
1442 @c @deftypefnx {Function} {} NPDF.T (@var{x}, @var{df}, @var{lambda})
1443 @c @deftypefnx {Function} {} NCDF.T (@var{x}, @var{df}, @var{lambda})
1444 T-distribution with @var{df} degrees of freedom.  The noncentral
1445 distribution takes an additional parameter @var{lambda}.  Constraints:
1446 @var{df} > 0, 0 < @var{p} < 1.
1447 @end deftypefn
1448
1449 @deftypefn {Function} {} PDF.T1G (@var{x}, @var{a}, @var{b})
1450 @deftypefnx {Function} {} CDF.T1G (@var{x}, @var{a}, @var{b})
1451 @deftypefnx {Function} {} IDF.T1G (@var{p}, @var{a}, @var{b})
1452 Type-1 Gumbel distribution with parameters @var{a} and @var{b}.  This
1453 distribution is a @pspp{} extension.  Constraints: 0 < @var{p} < 1.
1454 @end deftypefn
1455
1456 @deftypefn {Function} {} PDF.T2G (@var{x}, @var{a}, @var{b})
1457 @deftypefnx {Function} {} CDF.T2G (@var{x}, @var{a}, @var{b})
1458 @deftypefnx {Function} {} IDF.T2G (@var{p}, @var{a}, @var{b})
1459 Type-2 Gumbel distribution with parameters @var{a} and @var{b}.  This
1460 distribution is a @pspp{} extension.  Constraints: @var{x} > 0, 0 <
1461 @var{p} < 1.
1462 @end deftypefn
1463
1464 @deftypefn {Function} {} PDF.UNIFORM (@var{x}, @var{a}, @var{b})
1465 @deftypefnx {Function} {} CDF.UNIFORM (@var{x}, @var{a}, @var{b})
1466 @deftypefnx {Function} {} IDF.UNIFORM (@var{p}, @var{a}, @var{b})
1467 @deftypefnx {Function} {} RV.UNIFORM (@var{a}, @var{b})
1468 Uniform distribution with parameters @var{a} and @var{b}.
1469 Constraints: @var{a} <= @var{x} <= @var{b}, 0 <= @var{p} <= 1.  An
1470 additional function is available as shorthand:
1471
1472 @deftypefn {Function} {} UNIFORM (@var{b})
1473 Equivalent to RV.UNIFORM(0, @var{b}).
1474 @end deftypefn
1475 @end deftypefn
1476
1477 @deftypefn {Function} {} PDF.WEIBULL (@var{x}, @var{a}, @var{b})
1478 @deftypefnx {Function} {} CDF.WEIBULL (@var{x}, @var{a}, @var{b})
1479 @deftypefnx {Function} {} IDF.WEIBULL (@var{p}, @var{a}, @var{b})
1480 @deftypefnx {Function} {} RV.WEIBULL (@var{a}, @var{b})
1481 Weibull distribution with parameters @var{a} and @var{b}.
1482 Constraints: @var{a} > 0, @var{b} > 0, @var{x} >= 0, 0 <= @var{p} < 1.
1483 @end deftypefn
1484
1485 @node Discrete Distributions
1486 @subsubsection Discrete Distributions
1487
1488 The following discrete distributions are available:
1489
1490 @deftypefn {Function} {} PDF.BERNOULLI (@var{x})
1491 @deftypefnx {Function} {} CDF.BERNOULLI (@var{x}, @var{p})
1492 @deftypefnx {Function} {} RV.BERNOULLI (@var{p})
1493 Bernoulli distribution with probability of success @var{p}.
1494 Constraints: @var{x} = 0 or 1, 0 <= @var{p} <= 1.
1495 @end deftypefn
1496
1497 @deftypefn {Function} {} PDF.BINOM (@var{x}, @var{n}, @var{p})
1498 @deftypefnx {Function} {} CDF.BINOM (@var{x}, @var{n}, @var{p})
1499 @deftypefnx {Function} {} RV.BINOM (@var{n}, @var{p})
1500 Binomial distribution with @var{n} trials and probability of success
1501 @var{p}.  Constraints: integer @var{n} > 0, 0 <= @var{p} <= 1, integer
1502 @var{x} <= @var{n}.
1503 @end deftypefn
1504
1505 @deftypefn {Function} {} PDF.GEOM (@var{x}, @var{n}, @var{p})
1506 @deftypefnx {Function} {} CDF.GEOM (@var{x}, @var{n}, @var{p})
1507 @deftypefnx {Function} {} RV.GEOM (@var{n}, @var{p})
1508 Geometric distribution with probability of success @var{p}.
1509 Constraints: 0 <= @var{p} <= 1, integer @var{x} > 0.
1510 @end deftypefn
1511
1512 @deftypefn {Function} {} PDF.HYPER (@var{x}, @var{a}, @var{b}, @var{c})
1513 @deftypefnx {Function} {} CDF.HYPER (@var{x}, @var{a}, @var{b}, @var{c})
1514 @deftypefnx {Function} {} RV.HYPER (@var{a}, @var{b}, @var{c})
1515 Hypergeometric distribution when @var{b} objects out of @var{a} are
1516 drawn and @var{c} of the available objects are distinctive.
1517 Constraints: integer @var{a} > 0, integer @var{b} <= @var{a}, integer
1518 @var{c} <= @var{a}, integer @var{x} >= 0.
1519 @end deftypefn
1520
1521 @deftypefn {Function} {} PDF.LOG (@var{x}, @var{p})
1522 @deftypefnx {Function} {} RV.LOG (@var{p})
1523 Logarithmic distribution with probability parameter @var{p}.
1524 Constraints: 0 <= @var{p} < 1, @var{x} >= 1.
1525 @end deftypefn
1526
1527 @deftypefn {Function} {} PDF.NEGBIN (@var{x}, @var{n}, @var{p})
1528 @deftypefnx {Function} {} CDF.NEGBIN (@var{x}, @var{n}, @var{p})
1529 @deftypefnx {Function} {} RV.NEGBIN (@var{n}, @var{p})
1530 Negative binomial distribution with number of successes parameter
1531 @var{n} and probability of success parameter @var{p}.  Constraints:
1532 integer @var{n} >= 0, 0 < @var{p} <= 1, integer @var{x} >= 1.
1533 @end deftypefn
1534
1535 @deftypefn {Function} {} PDF.POISSON (@var{x}, @var{mu})
1536 @deftypefnx {Function} {} CDF.POISSON (@var{x}, @var{mu})
1537 @deftypefnx {Function} {} RV.POISSON (@var{mu})
1538 Poisson distribution with mean @var{mu}.  Constraints: @var{mu} > 0,
1539 integer @var{x} >= 0.
1540 @end deftypefn
1541
1542 @node Order of Operations
1543 @section Operator Precedence
1544 @cindex operator precedence
1545 @cindex precedence, operator
1546 @cindex order of operations
1547 @cindex operations, order of
1548
1549 The following table describes operator precedence.  Smaller-numbered
1550 levels in the table have higher precedence.  Within a level,
1551 operations are always performed from left to right.  The first
1552 occurrence of @samp{-} represents unary negation, the second binary
1553 subtraction.
1554
1555 @enumerate
1556 @item
1557 @code{()}
1558 @item
1559 @code{**}
1560 @item
1561 @code{-}
1562 @item
1563 @code{*  /}
1564 @item
1565 @code{+  -}
1566 @item
1567 @code{=  >=  >  <=  <  <>}
1568 @item
1569 @code{NOT}
1570 @item
1571 @code{AND}
1572 @item
1573 @code{OR}
1574 @end enumerate