better tests

[pspp] / doc / expressions.texi

@c PSPP - a program for statistical analysis.
@c Copyright (C) 2017, 2020 Free Software Foundation, Inc.
@c Permission is granted to copy, distribute and/or modify this document
@c under the terms of the GNU Free Documentation License, Version 1.3
@c or any later version published by the Free Software Foundation;
@c with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
@c A copy of the license is included in the section entitled "GNU
@c Free Documentation License".
@c
@c Use @func when referring to a function.
@c Use @deftypefn for their definitions
@macro func{NAME}
@code{\NAME\}
@end macro

@node Expressions
@chapter Mathematical Expressions
@cindex expressions, mathematical
@cindex mathematical expressions

Expressions share a common syntax each place they appear in @pspp{}
commands.  Expressions are made up of @dfn{operands}, which can be
numbers, strings, or variable names, separated by @dfn{operators}.
There are five types of operators: grouping, arithmetic, logical,
relational, and functions.

Every operator takes one or more operands as input and yields exactly
one result as output.  Depending on the operator, operands accept
strings or numbers as operands.  With few exceptions, operands may be
full-fledged expressions in themselves.

@menu
* Boolean Values::                 Boolean values
* Missing Values in Expressions::  Using missing values in expressions
* Grouping Operators::             parentheses
* Arithmetic Operators::           add sub mul div pow
* Logical Operators::              AND NOT OR
* Relational Operators::           EQ GE GT LE LT NE
* Functions::                      More-sophisticated operators
* Order of Operations::            Operator precedence
@end menu

@node Boolean Values
@section Boolean Values
@cindex Boolean
@cindex values, Boolean

Some @pspp{} operators and expressions work with Boolean values, which
represent true/false conditions.  Booleans have only three possible
values: 0 (false), 1 (true), and system-missing (unknown).
System-missing is neither true nor false and indicates that the true
value is unknown.

Boolean-typed operands or function arguments must take on one of these
three values.  Other values are considered false, but provoke a warning
when the expression is evaluated.

Strings and Booleans are not compatible, and neither may be used in
place of the other.

@node Missing Values in Expressions
@section Missing Values in Expressions

Most numeric operators yield system-missing when given any
system-missing operand.  A string operator given any system-missing
operand typically results in the empty string.  Exceptions are listed
under particular operator descriptions.

String user-missing values are not treated specially in expressions.

User-missing values for numeric variables are always transformed into
the system-missing value, except inside the arguments to the
@code{VALUE} and @code{SYSMIS} functions.

The missing-value functions can be used to precisely control how missing
values are treated in expressions.  @xref{Missing Value Functions}, for
more details.

@node Grouping Operators
@section Grouping Operators
@cindex parentheses
@cindex @samp{(  )}
@cindex grouping operators
@cindex operators, grouping

Parentheses (@samp{()}) are the grouping operators.  Surround an
expression with parentheses to force early evaluation.

Parentheses also surround the arguments to functions, but in that
situation they act as punctuators, not as operators.

@node Arithmetic Operators
@section Arithmetic Operators
@cindex operators, arithmetic
@cindex arithmetic operators

The arithmetic operators take numeric operands and produce numeric
results.

@table @code
@cindex @samp{+}
@cindex addition
@item @var{a} + @var{b}
Yields the sum of @var{a} and @var{b}.

@cindex @samp{-}
@cindex subtraction
@item @var{a} - @var{b}
Subtracts @var{b} from @var{a} and yields the difference.

@cindex @samp{*}
@cindex multiplication
@item @var{a} * @var{b}
Yields the product of @var{a} and @var{b}.  If either @var{a} or
@var{b} is 0, then the result is 0, even if the other operand is
missing.

@cindex @samp{/}
@cindex division
@item @var{a} / @var{b}
Divides @var{a} by @var{b} and yields the quotient.  If @var{a} is 0,
then the result is 0, even if @var{b} is missing.  If @var{b} is zero,
the result is system-missing.

@cindex @samp{**}
@cindex exponentiation
@item @var{a} ** @var{b}
Yields the result of raising @var{a} to the power @var{b}.  If
@var{a} is negative and @var{b} is not an integer, the result is
system-missing.  The result of @code{0**0} is system-missing as well.

@cindex @samp{-}
@cindex negation
@item - @var{a}
Reverses the sign of @var{a}.
@end table

@node Logical Operators
@section Logical Operators
@cindex logical operators
@cindex operators, logical

@cindex true
@cindex false
@cindex Boolean
@cindex values, system-missing
@cindex system-missing
The logical operators take logical operands and produce logical
results, meaning ``true or false.''  Logical operators are
not true Boolean operators because they may also result in a
system-missing value.  @xref{Boolean Values}, for more information.

@table @code
@cindex @code{AND}
@cindex @samp{&}
@cindex intersection, logical
@cindex logical intersection
@item @var{a} AND @var{b}
@itemx @var{a} & @var{b}
True if both @var{a} and @var{b} are true, false otherwise.  If one
operand is false, the result is false even if the other is missing.  If
both operands are missing, the result is missing.

@cindex @code{OR}
@cindex @samp{|}
@cindex union, logical
@cindex logical union
@item @var{a} OR @var{b}
@itemx @var{a} | @var{b}
True if at least one of @var{a} and @var{b} is true.  If one operand is
true, the result is true even if the other operand is missing.  If both
operands are missing, the result is missing.

@cindex @code{NOT}
@cindex @samp{~}
@cindex inversion, logical
@cindex logical inversion
@item NOT @var{a}
@itemx ~ @var{a}
True if @var{a} is false.  If the operand is missing, then the result
is missing.
@end table

@node Relational Operators
@section Relational Operators

The relational operators take numeric or string operands and produce Boolean
results.

Strings cannot be compared to numbers.  When strings of different
lengths are compared, the shorter string is right-padded with spaces
to match the length of the longer string.

The results of string comparisons, other than tests for equality or
inequality, depend on the character set in use.  String comparisons
are case-sensitive.

@table @code
@cindex equality, testing
@cindex testing for equality
@cindex @code{EQ}
@cindex @samp{=}
@item @var{a} EQ @var{b}
@itemx @var{a} = @var{b}
True if @var{a} is equal to @var{b}.

@cindex less than or equal to
@cindex @code{LE}
@cindex @code{<=}
@item @var{a} LE @var{b}
@itemx @var{a} <= @var{b}
True if @var{a} is less than or equal to @var{b}.

@cindex less than
@cindex @code{LT}
@cindex @code{<}
@item @var{a} LT @var{b}
@itemx @var{a} < @var{b}
True if @var{a} is less than @var{b}.

@cindex greater than or equal to
@cindex @code{GE}
@cindex @code{>=}
@item @var{a} GE @var{b}
@itemx @var{a} >= @var{b}
True if @var{a} is greater than or equal to @var{b}.

@cindex greater than
@cindex @code{GT}
@cindex @samp{>}
@item @var{a} GT @var{b}
@itemx @var{a} > @var{b}
True if @var{a} is greater than @var{b}.

@cindex inequality, testing
@cindex testing for inequality
@cindex @code{NE}
@cindex @code{~=}
@cindex @code{<>}
@item @var{a} NE @var{b}
@itemx @var{a} ~= @var{b}
@itemx @var{a} <> @var{b}
True if @var{a} is not equal to @var{b}.
@end table

@node Functions
@section Functions
@cindex functions

@cindex mathematics
@cindex operators
@cindex parentheses
@cindex @code{(}
@cindex @code{)}
@cindex names, of functions
@pspp{} functions provide mathematical abilities above and beyond
those possible using simple operators.  Functions have a common
syntax: each is composed of a function name followed by a left
parenthesis, one or more arguments, and a right parenthesis.

Function names are not reserved.  Their names are specially treated
only when followed by a left parenthesis, so that @samp{EXP(10)}
refers to the constant value @math{e} raised to the 10th power, but
@samp{EXP} by itself refers to the value of a variable called @code{EXP}.

The sections below describe each function in detail.

@menu
* Mathematics::                 EXP LG10 LN LNGAMMA SQRT
* Miscellaneous Mathematics::   ABS MOD MOD10 RND TRUNC
* Trigonometry::                ACOS ARCOS ARSIN ARTAN ASIN ATAN COS SIN TAN
* Missing Value Functions::     MISSING NMISS NVALID SYSMIS VALUE
* Set Membership::              ANY RANGE
* Statistical Functions::       CFVAR MAX MEAN MEDIAN MIN SD SUM VARIANCE
* String Functions::            CONCAT INDEX LENGTH LOWER LPAD LTRIM NUMBER
                                REPLACE RINDEX RPAD RTRIM STRING STRUNC SUBSTR
                                UPCASE
* Time and Date::               CTIME.xxx DATE.xxx TIME.xxx XDATE.xxx
                                DATEDIFF DATESUM
* Miscellaneous Functions::     LAG YRMODA VALUELABEL
* Statistical Distribution Functions::  PDF CDF SIG IDF RV NPDF NCDF
@end menu

@node Mathematics
@subsection Mathematical Functions
@cindex mathematics, advanced

Advanced mathematical functions take numeric arguments and produce
numeric results.

@deftypefn {Function} {} EXP (@var{exponent})
Returns @math{e} (approximately 2.71828) raised to power @var{exponent}.
@end deftypefn

@cindex logarithms
@deftypefn {Function} {} LG10 (@var{number})
Takes the base-10 logarithm of @var{number}.  If @var{number} is
not positive, the result is system-missing.
@end deftypefn

@deftypefn {Function} {} LN (@var{number})
Takes the base-@math{e} logarithm of @var{number}.  If @var{number} is
not positive, the result is system-missing.
@end deftypefn

@deftypefn {Function} {} LNGAMMA (@var{number})
Yields the base-@math{e} logarithm of the complete gamma of @var{number}.
If @var{number} is a negative integer, the result is system-missing.
@end deftypefn

@cindex square roots
@deftypefn {Function} {} SQRT (@var{number})
Takes the square root of @var{number}.  If @var{number} is negative,
the result is system-missing.
@end deftypefn

@node Miscellaneous Mathematics
@subsection Miscellaneous Mathematical Functions
@cindex mathematics, miscellaneous

Miscellaneous mathematical functions take numeric arguments and produce
numeric results.

@cindex absolute value
@deftypefn {Function} {} ABS (@var{number})
Results in the absolute value of @var{number}.
@end deftypefn

@cindex modulus
@deftypefn {Function} {} MOD (@var{numerator}, @var{denominator})
Returns the remainder (modulus) of @var{numerator} divided by
@var{denominator}.  If @var{numerator} is 0, then the result is 0,
even if @var{denominator} is missing.  If @var{denominator} is 0, the
result is system-missing.
@end deftypefn

@cindex modulus, by 10
@deftypefn {Function} {} MOD10 (@var{number})
Returns the remainder when @var{number} is divided by 10.  If
@var{number} is negative, MOD10(@var{number}) is negative or zero.
@end deftypefn

@cindex rounding
@deftypefn {Function} {} RND (@var{number} [, @var{mult}[, @var{fuzzbits}]])
Rounds @var{number} and rounds it to a multiple of @var{mult} (by
default 1).  Halves are rounded away from zero, as are values that
fall short of halves by less than @var{fuzzbits} of errors in the
least-significant bits of @var{number}.  If @var{fuzzbits} is not
specified then the default is taken from SET FUZZBITS (@pxref{SET
FUZZBITS}), which is 6 unless overridden.
@end deftypefn

@cindex truncation
@deftypefn {Function} {} TRUNC (@var{number} [, @var{mult}[, @var{fuzzbits}]])
Rounds @var{number} to a multiple of @var{mult}, toward zero.  For the
default @var{mult} of 1, this is equivalent to discarding the
fractional part of @var{number}.  Values that fall short of a multiple
of @var{mult} by less than @var{fuzzbits} of errors in the
least-significant bits of @var{number} are rounded away from zero.  If
@var{fuzzbits} is not specified then the default is taken from SET
FUZZBITS (@pxref{SET FUZZBITS}), which is 6 unless overridden.
@end deftypefn

@node Trigonometry
@subsection Trigonometric Functions
@cindex trigonometry

Trigonometric functions take numeric arguments and produce numeric
results.

@cindex arccosine
@cindex inverse cosine
@deftypefn {Function} {} ARCOS (@var{number})
@deftypefnx {Function} {} ACOS (@var{number})
Takes the arccosine, in radians, of @var{number}.  Results in
system-missing if @var{number} is not between -1 and 1 inclusive.
This function is a @pspp{} extension.
@end deftypefn

@cindex arcsine
@cindex inverse sine
@deftypefn {Function} {} ARSIN (@var{number})
@deftypefnx {Function} {} ASIN (@var{number})
Takes the arcsine, in radians, of @var{number}.  Results in
system-missing if @var{number} is not between -1 and 1 inclusive.
@end deftypefn

@cindex arctangent
@cindex inverse tangent
@deftypefn {Function} {} ARTAN (@var{number})
@deftypefnx {Function} {} ATAN (@var{number})
Takes the arctangent, in radians, of @var{number}.
@end deftypefn

@cindex cosine
@deftypefn {Function} {} COS (@var{angle})
Takes the cosine of @var{angle} which should be in radians.
@end deftypefn

@cindex sine
@deftypefn {Function} {} SIN (@var{angle})
Takes the sine of @var{angle} which should be in radians.
@end deftypefn

@cindex tangent
@deftypefn {Function} {} TAN (@var{angle})
Takes the tangent of @var{angle} which should be in radians.
Results in system-missing at values
of @var{angle} that are too close to odd multiples of @math{\pi/2}.
Portability: none.
@end deftypefn

@node Missing Value Functions
@subsection Missing-Value Functions
@cindex missing values
@cindex values, missing
@cindex functions, missing-value

Missing-value functions take various numeric arguments and yield
various types of results.  Except where otherwise stated below, the
normal rules of evaluation apply within expression arguments to these
functions.  In particular, user-missing values for numeric variables
are converted to system-missing values.

@deftypefn {Function} {} MISSING (@var{expr})
When @var{expr} is simply the name of a numeric variable, returns 1 if
the variable has the system-missing value or if it is user-missing.
For any other value 0 is returned.
If @var{expr} takes another form, the function returns 1 if the value is
system-missing, 0 otherwise.
@end deftypefn

@deftypefn {Function} {} NMISS (@var{expr} [, @var{expr}]@dots{})
Each argument must be a numeric expression.  Returns the number of
system-missing values in the list, which may include variable ranges
using the @code{@var{var1} TO @var{var2}} syntax.
@end deftypefn

@deftypefn {Function} {} NVALID (@var{expr} [, @var{expr}]@dots{})
Each argument must be a numeric expression.  Returns the number of
values in the list that are not system-missing.  The list may include
variable ranges using the @code{@var{var1} TO @var{var2}} syntax.
@end deftypefn

@deftypefn {Function} {} SYSMIS (@var{expr})
Returns 1 if @var{expr} has the system-missing value, 0 otherwise.
@end deftypefn

@deftypefn {Function} {} VALUE (@var{variable})
Prevents the user-missing values of @var{variable} from being
transformed into system-missing values, and always results in the
actual value of @var{variable}, whether it is valid, user-missing, or
system-missing.
@end deftypefn

@node Set Membership
@subsection Set-Membership Functions
@cindex set membership
@cindex membership, of set

Set membership functions determine whether a value is a member of a set.
They take a set of numeric arguments or a set of string arguments, and
produce Boolean results.

String comparisons are performed according to the rules given in
@ref{Relational Operators}.

@deftypefn {Function} {} ANY (@var{value}, @var{set} [, @var{set}]@dots{})
Results in true if @var{value} is equal to any of the @var{set}
values.  Otherwise, results in false.  If @var{value} is
system-missing, returns system-missing.  System-missing values in
@var{set} do not cause @func{ANY} to return system-missing.
@end deftypefn

@deftypefn {Function} {} RANGE (@var{value}, @var{low}, @var{high} [, @var{low}, @var{high}]@dots{})
Results in true if @var{value} is in any of the intervals bounded by
@var{low} and @var{high} inclusive.  Otherwise, results in false.
Each @var{low} must be less than or equal to its corresponding
@var{high} value.  @var{low} and @var{high} must be given in pairs.
If @var{value} is system-missing, returns system-missing.
System-missing values in @var{set} do not cause @func{RANGE} to return
system-missing.
@end deftypefn

@node Statistical Functions
@subsection Statistical Functions
@cindex functions, statistical
@cindex statistics

Statistical functions compute descriptive statistics on a list of
values.  Some statistics can be computed on numeric or string values;
other can only be computed on numeric values.  Their results have the
same type as their arguments.  The current case's weighting factor
(@pxref{WEIGHT}) has no effect on statistical functions.

These functions' argument lists may include entire ranges of variables
using the @code{@var{var1} TO @var{var2}} syntax.

@cindex arguments, minimum valid
@cindex minimum valid number of arguments
Unlike most functions, statistical functions can return non-missing
values even when some of their arguments are missing.  Most
statistical functions, by default, require only 1 non-missing value to
have a non-missing return, but @func{CFVAR}, @func{SD}, and @func {VARIANCE} require 2.
These defaults can be increased (but not decreased) by appending a dot
and the minimum number of valid arguments to the function name.  For
example, @subcmd{MEAN.3(X, Y, Z)} would only return non-missing if all
of @samp{X}, @samp{Y}, and @samp{Z} were valid.

@cindex coefficient of variation
@cindex variation, coefficient of
@deftypefn {Function} {} CFVAR (@var{number}, @var{number}[, @dots{}])
Results in the coefficient of variation of the values of @var{number}.
(The coefficient of variation is the standard deviation divided by the
mean.)
@end deftypefn

@cindex maximum
@deftypefn {Function} {} MAX (@var{value}, @var{value}[, @dots{}])
Results in the value of the greatest @var{value}.  The @var{value}s may
be numeric or string.
@end deftypefn

@cindex mean
@deftypefn {Function} {} MEAN (@var{number}, @var{number}[, @dots{}])
Results in the mean of the values of @var{number}.
@end deftypefn

@cindex median
@deftypefn {Function} {} MEDIAN (@var{number}, @var{number}[, @dots{}])
Results in the median of the values of @var{number}.  Given an even
number of nonmissing arguments, yields the mean of the two middle
values.
@end deftypefn

@cindex minimum
@deftypefn {Function} {} MIN (@var{number}, @var{number}[, @dots{}])
Results in the value of the least @var{value}.  The @var{value}s may
be numeric or string.
@end deftypefn

@cindex standard deviation
@cindex deviation, standard
@deftypefn {Function} {} SD (@var{number}, @var{number}[, @dots{}])
Results in the standard deviation of the values of @var{number}.
@end deftypefn

@cindex sum
@deftypefn {Function} {} SUM (@var{number}, @var{number}[, @dots{}])
Results in the sum of the values of @var{number}.
@end deftypefn

@cindex variance
@deftypefn {Function} {} VARIANCE (@var{number}, @var{number}[, @dots{}])
Results in the variance of the values of @var{number}.
@end deftypefn

@node String Functions
@subsection String Functions
@cindex functions, string
@cindex string functions

String functions take various arguments and return various results.

@cindex concatenation
@cindex strings, concatenation of
@deftypefn {Function} {} CONCAT (@var{string}, @var{string}[, @dots{}])
Returns a string consisting of each @var{string} in sequence.
@code{CONCAT("abc", "def", "ghi")} has a value of @code{"abcdefghi"}.
The resultant string is truncated to a maximum of 255 characters.
@end deftypefn

@cindex searching strings
@deftypefn {Function} {} INDEX (@var{haystack}, @var{needle})
Returns a positive integer indicating the position of the first
occurrence of @var{needle} in @var{haystack}.  Returns 0 if @var{haystack}
does not contain @var{needle}.  Returns system-missing if @var{needle}
is an empty string.
@end deftypefn

@deftypefn {Function} {} INDEX (@var{haystack}, @var{needles}, @var{needle_len})
Divides @var{needles} into one or more needles, each with length
@var{needle_len}.
Searches @var{haystack} for the first occurrence of each needle, and
returns the smallest value.  Returns 0 if @var{haystack} does not
contain any part in @var{needle}.  It is an error if @var{needle_len}
does not evenly divide the length of @var{needles}.  Returns
system-missing if @var{needles} is an empty string.
@end deftypefn

@cindex strings, finding length of
@deftypefn {Function} {} LENGTH (@var{string})
Returns the number of characters in @var{string}.
@end deftypefn

@cindex strings, case of
@deftypefn {Function} {} LOWER (@var{string})
Returns a string identical to @var{string} except that all uppercase
letters are changed to lowercase letters.  The definitions of
``uppercase'' and ``lowercase'' are system-dependent.
@end deftypefn

@cindex strings, padding
@deftypefn {Function} {} LPAD (@var{string}, @var{length})
If @var{string} is at least @var{length} characters in length, returns
@var{string} unchanged.  Otherwise, returns @var{string} padded with
spaces on the left side to length @var{length}.  Returns an empty string
if @var{length} is system-missing, negative, or greater than 255.
@end deftypefn

@deftypefn {Function} {} LPAD (@var{string}, @var{length}, @var{padding})
If @var{string} is at least @var{length} characters in length, returns
@var{string} unchanged.  Otherwise, returns @var{string} padded with
@var{padding} on the left side to length @var{length}.  Returns an empty
string if @var{length} is system-missing, negative, or greater than 255, or
if @var{padding} does not contain exactly one character.
@end deftypefn

@cindex strings, trimming
@cindex white space, trimming
@deftypefn {Function} {} LTRIM (@var{string})
Returns @var{string}, after removing leading spaces.  Other white space,
such as tabs, carriage returns, line feeds, and vertical tabs, is not
removed.
@end deftypefn

@deftypefn {Function} {} LTRIM (@var{string}, @var{padding})
Returns @var{string}, after removing leading @var{padding} characters.
If @var{padding} does not contain exactly one character, returns an
empty string.
@end deftypefn

@cindex numbers, converting from strings
@cindex strings, converting to numbers
@deftypefn {Function} {} NUMBER (@var{string}, @var{format})
Returns the number produced when @var{string} is interpreted according
to format specifier @var{format}.  If the format width @var{w} is less
than the length of @var{string}, then only the first @var{w}
characters in @var{string} are used, @i{e.g.}@: @code{NUMBER("123", F3.0)}
and @code{NUMBER("1234", F3.0)} both have value 123.  If @var{w} is
greater than @var{string}'s length, then it is treated as if it were
right-padded with spaces.  If @var{string} is not in the correct
format for @var{format}, system-missing is returned.
@end deftypefn

@cindex strings, replacing substrings
@cindex replacing substrings
@deftypefn {Function} {} REPLACE (@var{haystack}, @var{needle}, @var{replacement}[, @var{n}])
Returns string @var{haystack} with instances of @var{needle} replaced
by @var{replacement}.  If nonnegative integer @var{n} is specified, it
limits the maximum number of replacements; otherwise, all instances of
@var{needle} are replaced.
@end deftypefn

@cindex strings, searching backwards
@deftypefn {Function} {} RINDEX (@var{haystack}, @var{needle})
Returns a positive integer indicating the position of the last
occurrence of @var{needle} in @var{haystack}.  Returns 0 if
@var{haystack} does not contain @var{needle}.  Returns system-missing if
@var{needle} is an empty string.
@end deftypefn

@deftypefn {Function} {} RINDEX (@var{haystack}, @var{needle}, @var{needle_len})
Divides @var{needle} into parts, each with length @var{needle_len}.
Searches @var{haystack} for the last occurrence of each part, and
returns the largest value.  Returns 0 if @var{haystack} does not contain
any part in @var{needle}.  It is an error if @var{needle_len} does not
evenly divide the length of @var{needle}.  Returns system-missing
if @var{needle} is an empty string or if needle_len is less than 1.
@end deftypefn

@cindex padding strings
@cindex strings, padding
@deftypefn {Function} {} RPAD (@var{string}, @var{length})
If @var{string} is at least @var{length} characters in length, returns
@var{string} unchanged.  Otherwise, returns @var{string} padded with
spaces on the right to length @var{length}.  Returns an empty string if
@var{length} is system-missing, negative, or greater than 255.
@end deftypefn

@deftypefn {Function} {} RPAD (@var{string}, @var{length}, @var{padding})
If @var{string} is at least @var{length} characters in length, returns
@var{string} unchanged.  Otherwise, returns @var{string} padded with
@var{padding} on the right to length @var{length}.  Returns an empty
string if @var{length} is system-missing, negative, or greater than 255,
or if @var{padding} does not contain exactly one character.
@end deftypefn

@cindex strings, trimming
@cindex white space, trimming
@deftypefn {Function} {} RTRIM (@var{string})
Returns @var{string}, after removing trailing spaces.  Other types of
white space are not removed.
@end deftypefn

@deftypefn {Function} {} RTRIM (@var{string}, @var{padding})
Returns @var{string}, after removing trailing @var{padding} characters.
If @var{padding} does not contain exactly one character, returns an
empty string.
@end deftypefn

@cindex strings, converting from numbers
@cindex numbers, converting to strings
@deftypefn {Function} {} STRING (@var{number}, @var{format})
Returns a string corresponding to @var{number} in the format given by
format specifier @var{format}.  For example, @code{STRING(123.56, F5.1)}
has the value @code{"123.6"}.
@end deftypefn

@cindex strings, trimming
@cindex strings, truncating
@cindex white space, trimming
@deftypefn {Function} {} STRUNC (@var{string}, @var{n})
Returns @var{string}, first trimming it to at most @var{n} bytes, then
removing trailing spaces.  Returns an empty string if @var{n} is
missing or negative.
@end deftypefn

@cindex substrings
@cindex strings, taking substrings of
@deftypefn {Function} {} SUBSTR (@var{string}, @var{start})
Returns a string consisting of the value of @var{string} from position
@var{start} onward.  Returns an empty string if @var{start} is system-missing,
less than 1, or greater than the length of @var{string}.
@end deftypefn

@deftypefn {Function} {} SUBSTR (@var{string}, @var{start}, @var{count})
Returns a string consisting of the first @var{count} characters from
@var{string} beginning at position @var{start}.  Returns an empty string
if @var{start} or @var{count} is system-missing, if @var{start} is less
than 1 or greater than the number of characters in @var{string}, or if
@var{count} is less than 1.  Returns a string shorter than @var{count}
characters if @var{start} + @var{count} - 1 is greater than the number
of characters in @var{string}.  Examples: @code{SUBSTR("abcdefg", 3, 2)}
has value @code{"cd"}; @code{SUBSTR("nonsense", 4, 10)} has the value
@code{"sense"}.
@end deftypefn

@cindex case conversion
@cindex strings, case of
@deftypefn {Function} {} UPCASE (@var{string})
Returns @var{string}, changing lowercase letters to uppercase letters.
@end deftypefn

@node Time and Date
@subsection Time & Date Functions
@cindex functions, time & date
@cindex times
@cindex dates

@cindex dates, valid
For compatibility, @pspp{} considers dates before 15 Oct 1582 invalid.
Most time and date functions will not accept earlier dates.

@menu
* Time and Date Concepts::      How times & dates are defined and represented
* Time Construction::           TIME.@{DAYS HMS@}
* Time Extraction::             CTIME.@{DAYS HOURS MINUTES SECONDS@}
* Date Construction::           DATE.@{DMY MDY MOYR QYR WKYR YRDAY@}
* Date Extraction::             XDATE.@{DATE HOUR JDAY MDAY MINUTE MONTH
                                       QUARTER SECOND TDAY TIME WEEK
                                       WKDAY YEAR@}
* Time and Date Arithmetic::    DATEDIFF DATESUM
@end menu

@node Time and Date Concepts
@subsubsection How times & dates are defined and represented

@cindex time, concepts
@cindex time, intervals
Times and dates are handled by @pspp{} as single numbers.  A
@dfn{time} is an interval.  @pspp{} measures times in seconds.
Thus, the following intervals correspond with the numeric values given:

@example
          10 minutes                        600
          1 hour                          3,600
          1 day, 3 hours, 10 seconds     97,210
          40 days                     3,456,000
@end example

@cindex dates, concepts
@cindex time, instants of
A @dfn{date}, on the other hand, is a particular instant in the past
or the future.  @pspp{} represents a date as a number of seconds since
midnight preceding 14 Oct 1582.  Because midnight preceding the dates
given below correspond with the numeric @pspp{} dates given:

@example
              15 Oct 1582                86,400
               4 Jul 1776         6,113,318,400
               1 Jan 1900        10,010,390,400
               1 Oct 1978        12,495,427,200
              24 Aug 1995        13,028,601,600
@end example

@node Time Construction
@subsubsection Functions that Produce Times
@cindex times, constructing
@cindex constructing times

These functions take numeric arguments and return numeric values that
represent times.

@cindex days
@cindex time, in days
@deftypefn {Function} {} TIME.DAYS (@var{ndays})
Returns a time corresponding to @var{ndays} days.
@end deftypefn

@cindex hours-minutes-seconds
@cindex time, in hours-minutes-seconds
@deftypefn {Function} {} TIME.HMS (@var{nhours}, @var{nmins}, @var{nsecs})
Returns a time corresponding to @var{nhours} hours, @var{nmins}
minutes, and @var{nsecs} seconds.  The arguments may not have mixed
signs: if any of them are positive, then none may be negative, and
vice versa.
@end deftypefn

@node Time Extraction
@subsubsection Functions that Examine Times
@cindex extraction, of time
@cindex time examination
@cindex examination, of times
@cindex time, lengths of

These functions take numeric arguments in @pspp{} time format and
give numeric results.

@cindex days
@cindex time, in days
@deftypefn {Function} {} CTIME.DAYS (@var{time})
Results in the number of days and fractional days in @var{time}.
@end deftypefn

@cindex hours
@cindex time, in hours
@deftypefn {Function} {} CTIME.HOURS (@var{time})
Results in the number of hours and fractional hours in @var{time}.
@end deftypefn

@cindex minutes
@cindex time, in minutes
@deftypefn {Function} {} CTIME.MINUTES (@var{time})
Results in the number of minutes and fractional minutes in @var{time}.
@end deftypefn

@cindex seconds
@cindex time, in seconds
@deftypefn {Function} {} CTIME.SECONDS (@var{time})
Results in the number of seconds and fractional seconds in @var{time}.
(@code{CTIME.SECONDS} does nothing; @code{CTIME.SECONDS(@var{x})} is
equivalent to @code{@var{x}}.)
@end deftypefn

@node Date Construction
@subsubsection Functions that Produce Dates
@cindex dates, constructing
@cindex constructing dates

@cindex arguments, of date construction functions
These functions take numeric arguments and give numeric results that
represent dates.  Arguments taken by these functions are:

@table @var
@item day
Refers to a day of the month between 1 and 31.  Day 0 is also accepted
and refers to the final day of the previous month.  Days 29, 30, and
31 are accepted even in months that have fewer days and refer to a day
near the beginning of the following month.

@item month
Refers to a month of the year between 1 and 12.  Months 0 and 13 are
also accepted and refer to the last month of the preceding year and
the first month of the following year, respectively.

@item quarter
Refers to a quarter of the year between 1 and 4.  The quarters of the
year begin on the first day of months 1, 4, 7, and 10.

@item week
Refers to a week of the year between 1 and 53.

@item yday
Refers to a day of the year between 1 and 366.

@item year
Refers to a year, 1582 or greater.  Years between 0 and 99 are treated
according to the epoch set on SET EPOCH, by default beginning 69 years
before the current date (@pxref{SET EPOCH}).
@end table

@cindex arguments, invalid
If these functions' arguments are out-of-range, they are correctly
normalized before conversion to date format.  Non-integers are rounded
toward zero.

@cindex day-month-year
@cindex dates, day-month-year
@deftypefn {Function} {} DATE.DMY (@var{day}, @var{month}, @var{year})
@deftypefnx {Function} {} DATE.MDY (@var{month}, @var{day}, @var{year})
Results in a date value corresponding to the midnight before day
@var{day} of month @var{month} of year @var{year}.
@end deftypefn

@cindex month-year
@cindex dates, month-year
@deftypefn {Function} {} DATE.MOYR (@var{month}, @var{year})
Results in a date value corresponding to the midnight before the first
day of month @var{month} of year @var{year}.
@end deftypefn

@cindex quarter-year
@cindex dates, quarter-year
@deftypefn {Function} {} DATE.QYR (@var{quarter}, @var{year})
Results in a date value corresponding to the midnight before the first
day of quarter @var{quarter} of year @var{year}.
@end deftypefn

@cindex week-year
@cindex dates, week-year
@deftypefn {Function} {} DATE.WKYR (@var{week}, @var{year})
Results in a date value corresponding to the midnight before the first
day of week @var{week} of year @var{year}.
@end deftypefn

@cindex year-day
@cindex dates, year-day
@deftypefn {Function} {} DATE.YRDAY (@var{year}, @var{yday})
Results in a date value corresponding to the day
@var{yday} of year @var{year}.
@end deftypefn

@node Date Extraction
@subsubsection Functions that Examine Dates
@cindex extraction, of dates
@cindex date examination

@cindex arguments, of date extraction functions
These functions take numeric arguments in @pspp{} date or time
format and give numeric results.  These names are used for arguments:

@table @var
@item date
A numeric value in @pspp{} date format.

@item time
A numeric value in @pspp{} time format.

@item time-or-date
A numeric value in @pspp{} time or date format.
@end table

@cindex days
@cindex dates, in days
@cindex time, in days
@deftypefn {Function} {} XDATE.DATE (@var{time-or-date})
For a time, results in the time corresponding to the number of whole
days @var{date-or-time} includes.  For a date, results in the date
corresponding to the latest midnight at or before @var{date-or-time};
that is, gives the date that @var{date-or-time} is in.
@end deftypefn

@cindex hours
@cindex dates, in hours
@cindex time, in hours
@deftypefn {Function} {} XDATE.HOUR (@var{time-or-date})
For a time, results in the number of whole hours beyond the number of
whole days represented by @var{date-or-time}.  For a date, results in
the hour (as an integer between 0 and 23) corresponding to
@var{date-or-time}.
@end deftypefn

@cindex day of the year
@cindex dates, day of the year
@deftypefn {Function} {} XDATE.JDAY (@var{date})
Results in the day of the year (as an integer between 1 and 366)
corresponding to @var{date}.
@end deftypefn

@cindex day of the month
@cindex dates, day of the month
@deftypefn {Function} {} XDATE.MDAY (@var{date})
Results in the day of the month (as an integer between 1 and 31)
corresponding to @var{date}.
@end deftypefn

@cindex minutes
@cindex dates, in minutes
@cindex time, in minutes
@deftypefn {Function} {} XDATE.MINUTE (@var{time-or-date})
Results in the number of minutes (as an integer between 0 and 59) after
the last hour in @var{time-or-date}.
@end deftypefn

@cindex months
@cindex dates, in months
@deftypefn {Function} {} XDATE.MONTH (@var{date})
Results in the month of the year (as an integer between 1 and 12)
corresponding to @var{date}.
@end deftypefn

@cindex quarters
@cindex dates, in quarters
@deftypefn {Function} {} XDATE.QUARTER (@var{date})
Results in the quarter of the year (as an integer between 1 and 4)
corresponding to @var{date}.
@end deftypefn

@cindex seconds
@cindex dates, in seconds
@cindex time, in seconds
@deftypefn {Function} {} XDATE.SECOND (@var{time-or-date})
Results in the number of whole seconds after the last whole minute (as
an integer between 0 and 59) in @var{time-or-date}.
@end deftypefn

@cindex days
@cindex times, in days
@deftypefn {Function} {} XDATE.TDAY (@var{date})
Results in the number of whole days from 14 Oct 1582 to @var{date}.
@end deftypefn

@cindex time
@cindex dates, time of day
@deftypefn {Function} {} XDATE.TIME (@var{date})
Results in the time of day at the instant corresponding to @var{date},
as a time value.  This is the number of seconds since
midnight on the day corresponding to @var{date}.
@end deftypefn

@cindex week
@cindex dates, in weeks
@deftypefn {Function} {} XDATE.WEEK (@var{date})
Results in the week of the year (as an integer between 1 and 53)
corresponding to @var{date}.
@end deftypefn

@cindex day of the week
@cindex weekday
@cindex dates, day of the week
@cindex dates, in weekdays
@deftypefn {Function} {} XDATE.WKDAY (@var{date})
Results in the day of week (as an integer between 1 and 7) corresponding
to @var{date}, where 1 represents Sunday.
@end deftypefn

@cindex years
@cindex dates, in years
@deftypefn {Function} {} XDATE.YEAR (@var{date})
Returns the year (as an integer 1582 or greater) corresponding to
@var{date}.
@end deftypefn

@node Time and Date Arithmetic
@subsubsection Time and Date Arithmetic

@cindex time, mathematical properties of
@cindex mathematics, applied to times & dates
@cindex dates, mathematical properties of
@noindent
Ordinary arithmetic operations on dates and times often produce
sensible results.  Adding a time to, or subtracting one from, a date
produces a new date that much earlier or later.  The difference of two
dates yields the time between those dates.  Adding two times produces
the combined time.  Multiplying a time by a scalar produces a time
that many times longer.  Since times and dates are just numbers, the
ordinary addition and subtraction operators are employed for these
purposes.

Adding two dates does not produce a useful result.

Dates and times may have very large values.  Thus,
it is not a good idea to take powers of these values; also, the
accuracy of some procedures may be affected.  If necessary, convert
times or dates in seconds to some other unit, like days or years,
before performing analysis.

@pspp{} supplies a few functions for date arithmetic:

@deftypefn {Function} {} DATEDIFF (@var{date2}, @var{date1}, @var{unit})
Returns the span of time from @var{date1} to @var{date2} in terms of
@var{unit}, which must be a quoted string, one of @samp{years},
@samp{quarters}, @samp{months}, @samp{weeks}, @samp{days},
@samp{hours}, @samp{minutes}, and @samp{seconds}.  The result is an
integer, truncated toward zero.

One year is considered to span from a given date to the same month,
day, and time of day the next year.  Thus, from Jan.@tie{}1 of one
year to Jan.@tie{}1 the next year is considered to be a full year, but
Feb.@tie{}29 of a leap year to the following Feb.@tie{}28 is not.
Similarly, one month spans from a given day of the month to the same
day of the following month.  Thus, there is never a full month from
Jan.@tie{}31 of a given year to any day in the following February.
@end deftypefn

@deftypefn {Function} {} DATESUM (@var{date}, @var{quantity}, @var{unit}[, @var{method}])
Returns @var{date} advanced by the given @var{quantity} of the
specified @var{unit}, which must be one of the strings @samp{years},
@samp{quarters}, @samp{months}, @samp{weeks}, @samp{days},
@samp{hours}, @samp{minutes}, and @samp{seconds}.

When @var{unit} is @samp{years}, @samp{quarters}, or @samp{months},
only the integer part of @var{quantity} is considered.  Adding one of
these units can cause the day of the month to exceed the number of
days in the month.  In this case, the @var{method} comes into
play: if it is omitted or specified as @samp{closest} (as a quoted
string), then the resulting day is the last day of the month;
otherwise, if it is specified as @samp{rollover}, then the extra days
roll over into the following month.

When @var{unit} is @samp{weeks}, @samp{days}, @samp{hours},
@samp{minutes}, or @samp{seconds}, the @var{quantity} is not rounded
to an integer and @var{method}, if specified, is ignored.
@end deftypefn

@node Miscellaneous Functions
@subsection Miscellaneous Functions
@cindex functions, miscellaneous

@cindex cross-case function
@cindex function, cross-case
@deftypefn {Function} {} LAG (@var{variable}[, @var{n}])
@anchor{LAG}

@var{variable} must be a numeric or string variable name.  @code{LAG}
yields the value of that variable for the case @var{n} before the
current one.  Results in system-missing (for numeric variables) or
blanks (for string variables) for the first @var{n} cases.

@code{LAG} obtains values from the cases that become the new active
dataset
after a procedure executes.  Thus, @code{LAG} will not return values
from cases dropped by transformations such as @cmd{SELECT IF}, and
transformations like @cmd{COMPUTE} that modify data will change the
values returned by @code{LAG}.  These are both the case whether these
transformations precede or follow the use of @code{LAG}.

If @code{LAG} is used before @cmd{TEMPORARY}, then the values it returns
are those in cases just before @cmd{TEMPORARY}.  @code{LAG} may not be
used after @cmd{TEMPORARY}.

If omitted, @var{ncases} defaults to 1.  Otherwise, @var{ncases} must
be a small positive constant integer.  There is no explicit limit, but
use of a large value will increase memory consumption.
@end deftypefn

@cindex date, Julian
@cindex Julian date
@deftypefn {Function} {} YRMODA (@var{year}, @var{month}, @var{day})
@var{year} is a year, either between 0 and 99 or at least 1582.
Unlike other @pspp{} date functions, years between 0 and 99 always
correspond to 1900 through 1999.  @var{month} is a month between 1 and
13.  @var{day} is a day between 0 and 31.  A @var{day} of 0 refers to
the last day of the previous month, and a @var{month} of 13 refers to
the first month of the next year.  @var{year} must be in range.
@var{year}, @var{month}, and @var{day} must all be integers.

@code{YRMODA} results in the number of days between 15 Oct 1582 and
the date specified, plus one.  The date passed to @code{YRMODA} must be
on or after 15 Oct 1582.  15 Oct 1582 has a value of 1.
@end deftypefn

@cindex value label
@deftypefn {Function} VALUELABEL (@var{variable})
Returns a string matching the label associated with the current value
of @var{variable}.  If the current value of @var{variable} has no
associated label, then this function returns the empty string.
@var{variable} may be a numeric or string variable.
@end deftypefn

@node Statistical Distribution Functions
@subsection Statistical Distribution Functions

@pspp{} can calculate several functions of standard statistical
distributions.  These functions are named systematically based on the
function and the distribution.  The table below describes the
statistical distribution functions in general:

@table @asis
@item PDF.@var{dist} (@var{x}[, @var{param}@dots{}])
Probability density function for @var{dist}.  The domain of @var{x}
depends on @var{dist}.  For continuous distributions, the result is
the density of the probability function at @var{x}, and the range is
nonnegative real numbers.  For discrete distributions, the result is
the probability of @var{x}.

@item CDF.@var{dist} (@var{x}[, @var{param}@dots{}])
Cumulative distribution function for @var{dist}, that is, the
probability that a random variate drawn from the distribution is less
than @var{x}.  The domain of @var{x} depends @var{dist}.  The result is
a probability.

@item SIG.@var{dist} (@var{x}[, @var{param}@dots{})
Tail probability function for @var{dist}, that is, the probability
that a random variate drawn from the distribution is greater than
@var{x}.  The domain of @var{x} depends @var{dist}.  The result is a
probability.  Only a few distributions include an @func{SIG} function.

@item IDF.@var{dist} (@var{p}[, @var{param}@dots{}])
Inverse distribution function for @var{dist}, the value of @var{x} for
which the CDF would yield @var{p}.  The value of @var{p} is a
probability.  The range depends on @var{dist} and is identical to the
domain for the corresponding CDF.

@item RV.@var{dist} ([@var{param}@dots{}])
Random variate function for @var{dist}.  The range depends on the
distribution.

@item NPDF.@var{dist} (@var{x}[, @var{param}@dots{}])
Noncentral probability density function.  The result is the density of
the given noncentral distribution at @var{x}.  The domain of @var{x}
depends on @var{dist}.  The range is nonnegative real numbers.  Only a
few distributions include an @func{NPDF} function.

@item NCDF.@var{dist} (@var{x}[, @var{param}@dots{}])
Noncentral cumulative distribution function for @var{dist}, that is,
the probability that a random variate drawn from the given noncentral
distribution is less than @var{x}.  The domain of @var{x} depends
@var{dist}.  The result is a probability.  Only a few distributions
include an NCDF function.
@end table

The individual distributions are described individually below.

@menu
* Continuous Distributions::
* Discrete Distributions::
@end menu

@node Continuous Distributions
@subsubsection Continuous Distributions

The following continuous distributions are available:

@deftypefn {Function} {} PDF.BETA (@var{x})
@deftypefnx {Function} {} CDF.BETA (@var{x}, @var{a}, @var{b})
@deftypefnx {Function} {} IDF.BETA (@var{p}, @var{a}, @var{b})
@deftypefnx {Function} {} RV.BETA (@var{a}, @var{b})
@deftypefnx {Function} {} NPDF.BETA (@var{x}, @var{a}, @var{b}, @var{lambda})
@deftypefnx {Function} {} NCDF.BETA (@var{x}, @var{a}, @var{b}, @var{lambda})
Beta distribution with shape parameters @var{a} and @var{b}.  The
noncentral distribution takes an additional parameter @var{lambda}.
Constraints: @var{a} > 0, @var{b} > 0, @var{lambda} >= 0, 0 <= @var{x}
<= 1, 0 <= @var{p} <= 1.
@end deftypefn

@deftypefn {Function} {} PDF.BVNOR (@var{x0}, @var{x1}, @var{rho})
@deftypefnx {Function} {} CDF.BVNOR (@var{x0}, @var{x1}, @var{rho})
Bivariate normal distribution of two standard normal variables with
correlation coefficient @var{rho}.  Two variates @var{x0} and @var{x1}
must be provided.  Constraints: 0 <= @var{rho} <= 1, 0 <= @var{p} <= 1.
@end deftypefn

@deftypefn {Function} {} PDF.CAUCHY (@var{x}, @var{a}, @var{b})
@deftypefnx {Function} {} CDF.CAUCHY (@var{x}, @var{a}, @var{b})
@deftypefnx {Function} {} IDF.CAUCHY (@var{p}, @var{a}, @var{b})
@deftypefnx {Function} {} RV.CAUCHY (@var{a}, @var{b})
Cauchy distribution with location parameter @var{a} and scale
parameter @var{b}.  Constraints: @var{b} > 0, 0 < @var{p} < 1.
@end deftypefn

@c @deftypefn {Function} {} PDF.CHISQ (@var{x}, @var{df})
@deftypefn {Function} {} CDF.CHISQ (@var{x}, @var{df})
@deftypefnx {Function} {} SIG.CHISQ (@var{x}, @var{df})
@deftypefnx {Function} {} IDF.CHISQ (@var{p}, @var{df})
@deftypefnx {Function} {} RV.CHISQ (@var{df})
@c @deftypefnx {Function} {} NPDF.CHISQ (@var{x}, @var{df}, @var{lambda})
@deftypefnx {Function} {} NCDF.CHISQ (@var{x}, @var{df}, @var{lambda})
Chi-squared distribution with @var{df} degrees of freedom.  The
noncentral distribution takes an additional parameter @var{lambda}.
Constraints: @var{df} > 0, @var{lambda} > 0, @var{x} >= 0, 0 <=
@var{p} < 1.
@end deftypefn

@deftypefn {Function} {} PDF.EXP (@var{x}, @var{a})
@deftypefnx {Function} {} CDF.EXP (@var{x}, @var{a})
@deftypefnx {Function} {} IDF.EXP (@var{p}, @var{a})
@deftypefnx {Function} {} RV.EXP (@var{a})
Exponential distribution with scale parameter @var{a}.  The inverse of
@var{a} represents the rate of decay.  Constraints: @var{a} > 0,
@var{x} >= 0, 0 <= @var{p} < 1.
@end deftypefn

@deftypefn {Function} {} PDF.XPOWER (@var{x}, @var{a}, @var{b})
@deftypefnx {Function} {} RV.XPOWER (@var{a}, @var{b})
Exponential power distribution with positive scale parameter @var{a}
and nonnegative power parameter @var{b}.  Constraints: @var{a} > 0,
@var{b} >= 0, @var{x} >= 0, 0 <= @var{p} <= 1.  This distribution is a
@pspp{} extension.
@end deftypefn

@deftypefn {Function} {} PDF.F (@var{x}, @var{df1}, @var{df2})
@deftypefnx {Function} {} CDF.F (@var{x}, @var{df1}, @var{df2})
@deftypefnx {Function} {} SIG.F (@var{x}, @var{df1}, @var{df2})
@deftypefnx {Function} {} IDF.F (@var{p}, @var{df1}, @var{df2})
@deftypefnx {Function} {} RV.F (@var{df1}, @var{df2})
@c @deftypefnx {Function} {} NPDF.F (@var{x}, @var{df1}, @var{df2}, @var{lambda})
@c @deftypefnx {Function} {} NCDF.F (@var{x}, @var{df1}, @var{df2}, @var{lambda})
F-distribution of two chi-squared deviates with @var{df1} and
@var{df2} degrees of freedom.  The noncentral distribution takes an
additional parameter @var{lambda}.  Constraints: @var{df1} > 0,
@var{df2} > 0, @var{lambda} >= 0, @var{x} >= 0, 0 <= @var{p} < 1.
@end deftypefn

@deftypefn {Function} {} PDF.GAMMA (@var{x}, @var{a}, @var{b})
@deftypefnx {Function} {} CDF.GAMMA (@var{x}, @var{a}, @var{b})
@deftypefnx {Function} {} IDF.GAMMA (@var{p}, @var{a}, @var{b})
@deftypefnx {Function} {} RV.GAMMA (@var{a}, @var{b})
Gamma distribution with shape parameter @var{a} and scale parameter
@var{b}.  Constraints: @var{a} > 0, @var{b} > 0, @var{x} >= 0, 0 <=
@var{p} < 1.
@end deftypefn

@c @deftypefn {Function} {} PDF.HALFNRM (@var{x}, @var{a}, @var{b})
@c @deftypefnx {Function} {} CDF.HALFNRM (@var{x}, @var{a}, @var{b})
@c @deftypefnx {Function} {} IDF.HALFNRM (@var{p}, @var{a}, @var{b})
@c @deftypefnx {Function} {} RV.HALFNRM (@var{a}, @var{b})
@c Half-normal distribution with location parameter @var{a} and shape
@c parameter @var{b}.  Constraints: @var{b} > 0, 0 < @var{p} < 1.
@c @end deftypefn

@c @deftypefn {Function} {} PDF.IGAUSS (@var{x}, @var{a}, @var{b})
@c @deftypefnx {Function} {} CDF.IGAUSS (@var{x}, @var{a}, @var{b})
@c @deftypefnx {Function} {} IDF.IGAUSS (@var{p}, @var{a}, @var{b})
@c @deftypefnx {Function} {} RV.IGAUSS (@var{a}, @var{b})
@c Inverse Gaussian distribution with parameters @var{a} and @var{b}.
@c Constraints: @var{a} > 0, @var{b} > 0, @var{x} > 0, 0 <= @var{p} < 1.
@c @end deftypefn

@deftypefn {Function} {} PDF.LANDAU (@var{x})
@deftypefnx {Function} {} RV.LANDAU ()
Landau distribution.
@end deftypefn

@deftypefn {Function} {} PDF.LAPLACE (@var{x}, @var{a}, @var{b})
@deftypefnx {Function} {} CDF.LAPLACE (@var{x}, @var{a}, @var{b})
@deftypefnx {Function} {} IDF.LAPLACE (@var{p}, @var{a}, @var{b})
@deftypefnx {Function} {} RV.LAPLACE (@var{a}, @var{b})
Laplace distribution with location parameter @var{a} and scale
parameter @var{b}.  Constraints: @var{b} > 0, 0 < @var{p} < 1.
@end deftypefn

@deftypefn {Function} {} RV.LEVY (@var{c}, @var{alpha})
Levy symmetric alpha-stable distribution with scale @var{c} and
exponent @var{alpha}.  Constraints: 0 < @var{alpha} <= 2.
@end deftypefn

@deftypefn {Function} {} RV.LVSKEW (@var{c}, @var{alpha}, @var{beta})
Levy skew alpha-stable distribution with scale @var{c}, exponent
@var{alpha}, and skewness parameter @var{beta}.  Constraints: 0 <
@var{alpha} <= 2, -1 <= @var{beta} <= 1.
@end deftypefn

@deftypefn {Function} {} PDF.LOGISTIC (@var{x}, @var{a}, @var{b})
@deftypefnx {Function} {} CDF.LOGISTIC (@var{x}, @var{a}, @var{b})
@deftypefnx {Function} {} IDF.LOGISTIC (@var{p}, @var{a}, @var{b})
@deftypefnx {Function} {} RV.LOGISTIC (@var{a}, @var{b})
Logistic distribution with location parameter @var{a} and scale
parameter @var{b}.  Constraints: @var{b} > 0, 0 < @var{p} < 1.
@end deftypefn

@deftypefn {Function} {} PDF.LNORMAL (@var{x}, @var{a}, @var{b})
@deftypefnx {Function} {} CDF.LNORMAL (@var{x}, @var{a}, @var{b})
@deftypefnx {Function} {} IDF.LNORMAL (@var{p}, @var{a}, @var{b})
@deftypefnx {Function} {} RV.LNORMAL (@var{a}, @var{b})
Lognormal distribution with parameters @var{a} and @var{b}.
Constraints: @var{a} > 0, @var{b} > 0, @var{x} >= 0, 0 <= @var{p} < 1.
@end deftypefn

@deftypefn {Function} {} PDF.NORMAL (@var{x}, @var{mu}, @var{sigma})
@deftypefnx {Function} {} CDF.NORMAL (@var{x}, @var{mu}, @var{sigma})
@deftypefnx {Function} {} IDF.NORMAL (@var{p}, @var{mu}, @var{sigma})
@deftypefnx {Function} {} RV.NORMAL (@var{mu}, @var{sigma})
Normal distribution with mean @var{mu} and standard deviation
@var{sigma}.  Constraints: @var{b} > 0, 0 < @var{p} < 1.  Three
additional functions are available as shorthand:

@deftypefn {Function} {} CDFNORM (@var{x})
Equivalent to CDF.NORMAL(@var{x}, 0, 1).
@end deftypefn

@deftypefn {Function} {} PROBIT (@var{p})
Equivalent to IDF.NORMAL(@var{p}, 0, 1).
@end deftypefn

@deftypefn {Function} {} NORMAL (@var{sigma})
Equivalent to RV.NORMAL(0, @var{sigma}).
@end deftypefn
@end deftypefn

@deftypefn {Function} {} PDF.NTAIL (@var{x}, @var{a}, @var{sigma})
@deftypefnx {Function} {} RV.NTAIL (@var{a}, @var{sigma})
Normal tail distribution with lower limit @var{a} and standard
deviation @var{sigma}.  This distribution is a @pspp{} extension.
Constraints: @var{a} > 0, @var{x} > @var{a}, 0 < @var{p} < 1.
@end deftypefn

@deftypefn {Function} {} PDF.PARETO (@var{x}, @var{a}, @var{b})
@deftypefnx {Function} {} CDF.PARETO (@var{x}, @var{a}, @var{b})
@deftypefnx {Function} {} IDF.PARETO (@var{p}, @var{a}, @var{b})
@deftypefnx {Function} {} RV.PARETO (@var{a}, @var{b})
Pareto distribution with threshold parameter @var{a} and shape
parameter @var{b}.  Constraints: @var{a} > 0, @var{b} > 0, @var{x} >=
@var{a}, 0 <= @var{p} < 1.
@end deftypefn

@deftypefn {Function} {} PDF.RAYLEIGH (@var{x}, @var{sigma})
@deftypefnx {Function} {} CDF.RAYLEIGH (@var{x}, @var{sigma})
@deftypefnx {Function} {} IDF.RAYLEIGH (@var{p}, @var{sigma})
@deftypefnx {Function} {} RV.RAYLEIGH (@var{sigma})
Rayleigh distribution with scale parameter @var{sigma}.  This
distribution is a @pspp{} extension.  Constraints: @var{sigma} > 0,
@var{x} > 0.
@end deftypefn

@deftypefn {Function} {} PDF.RTAIL (@var{x}, @var{a}, @var{sigma})
@deftypefnx {Function} {} RV.RTAIL (@var{a}, @var{sigma})
Rayleigh tail distribution with lower limit @var{a} and scale
parameter @var{sigma}.  This distribution is a @pspp{} extension.
Constraints: @var{a} > 0, @var{sigma} > 0, @var{x} > @var{a}.
@end deftypefn

@c @deftypefn {Function} {} CDF.SMOD (@var{x}, @var{a}, @var{b})
@c @deftypefnx {Function} {} IDF.SMOD (@var{p}, @var{a}, @var{b})
@c Studentized maximum modulus distribution with parameters @var{a} and
@c @var{b}.  Constraints: @var{a} > 0, @var{b} > 0, @var{x} > 0, 0 <=
@c @var{p} < 1.
@c @end deftypefn

@c @deftypefn {Function} {} CDF.SRANGE (@var{x}, @var{a}, @var{b})
@c @deftypefnx {Function} {} IDF.SRANGE (@var{p}, @var{a}, @var{b})
@c Studentized range distribution with parameters @var{a} and @var{b}.
@c Constraints:  @var{a} >= 1, @var{b} >= 1, @var{x} > 0, 0 <= @var{p} <
@c 1.
@c @end deftypefn

@deftypefn {Function} {} PDF.T (@var{x}, @var{df})
@deftypefnx {Function} {} CDF.T (@var{x}, @var{df})
@deftypefnx {Function} {} IDF.T (@var{p}, @var{df})
@deftypefnx {Function} {} RV.T (@var{df})
@c @deftypefnx {Function} {} NPDF.T (@var{x}, @var{df}, @var{lambda})
@c @deftypefnx {Function} {} NCDF.T (@var{x}, @var{df}, @var{lambda})
T-distribution with @var{df} degrees of freedom.  The noncentral
distribution takes an additional parameter @var{lambda}.  Constraints:
@var{df} > 0, 0 < @var{p} < 1.
@end deftypefn

@deftypefn {Function} {} PDF.T1G (@var{x}, @var{a}, @var{b})
@deftypefnx {Function} {} CDF.T1G (@var{x}, @var{a}, @var{b})
@deftypefnx {Function} {} IDF.T1G (@var{p}, @var{a}, @var{b})
Type-1 Gumbel distribution with parameters @var{a} and @var{b}.  This
distribution is a @pspp{} extension.  Constraints: 0 < @var{p} < 1.
@end deftypefn

@deftypefn {Function} {} PDF.T2G (@var{x}, @var{a}, @var{b})
@deftypefnx {Function} {} CDF.T2G (@var{x}, @var{a}, @var{b})
@deftypefnx {Function} {} IDF.T2G (@var{p}, @var{a}, @var{b})
Type-2 Gumbel distribution with parameters @var{a} and @var{b}.  This
distribution is a @pspp{} extension.  Constraints: @var{x} > 0, 0 <
@var{p} < 1.
@end deftypefn

@deftypefn {Function} {} PDF.UNIFORM (@var{x}, @var{a}, @var{b})
@deftypefnx {Function} {} CDF.UNIFORM (@var{x}, @var{a}, @var{b})
@deftypefnx {Function} {} IDF.UNIFORM (@var{p}, @var{a}, @var{b})
@deftypefnx {Function} {} RV.UNIFORM (@var{a}, @var{b})
Uniform distribution with parameters @var{a} and @var{b}.
Constraints: @var{a} <= @var{x} <= @var{b}, 0 <= @var{p} <= 1.  An
additional function is available as shorthand:

@deftypefn {Function} {} UNIFORM (@var{b})
Equivalent to RV.UNIFORM(0, @var{b}).
@end deftypefn
@end deftypefn

@deftypefn {Function} {} PDF.WEIBULL (@var{x}, @var{a}, @var{b})
@deftypefnx {Function} {} CDF.WEIBULL (@var{x}, @var{a}, @var{b})
@deftypefnx {Function} {} IDF.WEIBULL (@var{p}, @var{a}, @var{b})
@deftypefnx {Function} {} RV.WEIBULL (@var{a}, @var{b})
Weibull distribution with parameters @var{a} and @var{b}.
Constraints: @var{a} > 0, @var{b} > 0, @var{x} >= 0, 0 <= @var{p} < 1.
@end deftypefn

@node Discrete Distributions
@subsubsection Discrete Distributions

The following discrete distributions are available:

@deftypefn {Function} {} PDF.BERNOULLI (@var{x})
@deftypefnx {Function} {} CDF.BERNOULLI (@var{x}, @var{p})
@deftypefnx {Function} {} RV.BERNOULLI (@var{p})
Bernoulli distribution with probability of success @var{p}.
Constraints: @var{x} = 0 or 1, 0 <= @var{p} <= 1.
@end deftypefn

@deftypefn {Function} {} PDF.BINOM (@var{x}, @var{n}, @var{p})
@deftypefnx {Function} {} CDF.BINOM (@var{x}, @var{n}, @var{p})
@deftypefnx {Function} {} RV.BINOM (@var{n}, @var{p})
Binomial distribution with @var{n} trials and probability of success
@var{p}.  Constraints: integer @var{n} > 0, 0 <= @var{p} <= 1, integer
@var{x} <= @var{n}.
@end deftypefn

@deftypefn {Function} {} PDF.GEOM (@var{x}, @var{n}, @var{p})
@deftypefnx {Function} {} CDF.GEOM (@var{x}, @var{n}, @var{p})
@deftypefnx {Function} {} RV.GEOM (@var{n}, @var{p})
Geometric distribution with probability of success @var{p}.
Constraints: 0 <= @var{p} <= 1, integer @var{x} > 0.
@end deftypefn

@deftypefn {Function} {} PDF.HYPER (@var{x}, @var{a}, @var{b}, @var{c})
@deftypefnx {Function} {} CDF.HYPER (@var{x}, @var{a}, @var{b}, @var{c})
@deftypefnx {Function} {} RV.HYPER (@var{a}, @var{b}, @var{c})
Hypergeometric distribution when @var{b} objects out of @var{a} are
drawn and @var{c} of the available objects are distinctive.
Constraints: integer @var{a} > 0, integer @var{b} <= @var{a}, integer
@var{c} <= @var{a}, integer @var{x} >= 0.
@end deftypefn

@deftypefn {Function} {} PDF.LOG (@var{x}, @var{p})
@deftypefnx {Function} {} RV.LOG (@var{p})
Logarithmic distribution with probability parameter @var{p}.
Constraints: 0 <= @var{p} < 1, @var{x} >= 1.
@end deftypefn

@deftypefn {Function} {} PDF.NEGBIN (@var{x}, @var{n}, @var{p})
@deftypefnx {Function} {} CDF.NEGBIN (@var{x}, @var{n}, @var{p})
@deftypefnx {Function} {} RV.NEGBIN (@var{n}, @var{p})
Negative binomial distribution with number of successes parameter
@var{n} and probability of success parameter @var{p}.  Constraints:
integer @var{n} >= 0, 0 < @var{p} <= 1, integer @var{x} >= 1.
@end deftypefn

@deftypefn {Function} {} PDF.POISSON (@var{x}, @var{mu})
@deftypefnx {Function} {} CDF.POISSON (@var{x}, @var{mu})
@deftypefnx {Function} {} RV.POISSON (@var{mu})
Poisson distribution with mean @var{mu}.  Constraints: @var{mu} > 0,
integer @var{x} >= 0.
@end deftypefn

@node Order of Operations
@section Operator Precedence
@cindex operator precedence
@cindex precedence, operator
@cindex order of operations
@cindex operations, order of

The following table describes operator precedence.  Smaller-numbered
levels in the table have higher precedence.  Within a level,
operations are always performed from left to right.  The first
occurrence of @samp{-} represents unary negation, the second binary
subtraction.

@enumerate
@item
@code{()}
@item
@code{**}
@item
@code{-}
@item
@code{*  /}
@item
@code{+  -}
@item
@code{=  >=  >  <=  <  <>}
@item
@code{NOT}
@item
@code{AND}
@item
@code{OR}
@end enumerate