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