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