From: Ben Pfaff Date: Tue, 6 May 2025 18:53:21 +0000 (-0700) Subject: work on manual X-Git-Url: https://pintos-os.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=ae9d801c4228df61332a799b4fc0fc5e0b2b44ea;p=pspp work on manual --- diff --git a/rust/doc/src/SUMMARY.md b/rust/doc/src/SUMMARY.md index a42f532705..eb7e9ad198 100644 --- a/rust/doc/src/SUMMARY.md +++ b/rust/doc/src/SUMMARY.md @@ -26,12 +26,7 @@ - [File Handles](language/files/file-handles.md) - [Syntax Diagrams](language/syntax-diagrams.md) - [Expressions](language/expressions/index.md) - - [Boolean Values](language/expressions/boolean-values.md) - - [Missing Values in Expressions](language/expressions/missing-values.md) - - [Grouping Operators](language/expressions/grouping.md) - - [Arithmetic Operators](language/expressions/arithmetic.md) - - [Logical Operators](language/expressions/logical.md) - - [Relational Operators](language/expressions/relational.md) + - [Operators](language/expressions/operators.md) - [Functions](language/expressions/functions/index.md) - [Mathematical Functions](language/expressions/functions/mathematical.md) - [Trigonometric Functions](language/expressions/functions/trigonometric.md) diff --git a/rust/doc/src/language/expressions/functions/statistical-distributions.md b/rust/doc/src/language/expressions/functions/statistical-distributions.md index 42ab2cb8a1..c7c73ad8ca 100644 --- a/rust/doc/src/language/expressions/functions/statistical-distributions.md +++ b/rust/doc/src/language/expressions/functions/statistical-distributions.md @@ -50,179 +50,179 @@ statistical distribution functions in general: The following continuous distributions are available: -* `PDF.BETA (X)` - `CDF.BETA (X, A, B)` - `IDF.BETA (P, A, B)` - `RV.BETA (A, B)` - `NPDF.BETA (X, A, B, ꟛ)` - `NCDF.BETA (X, A, B, ꟛ)` +* `PDF.BETA(X)` + `CDF.BETA(X, A, B)` + `IDF.BETA(P, A, B)` + `RV.BETA(A, B)` + `NPDF.BETA(X, A, B, ꟛ)` + `NCDF.BETA(X, A, B, ꟛ)` Beta distribution with shape parameters `A` and `B`. The noncentral distribution takes an additional parameter ꟛ. Constraints: `A > 0, B > 0, ꟛ >= 0, 0 <= X <= 1, 0 <= P <= 1`. -* `PDF.BVNOR (X0, X1, ρ)` - `CDF.BVNOR (X0, X1, ρ)` +* `PDF.BVNOR(X0, X1, ρ)` + `CDF.BVNOR(X0, X1, ρ)` Bivariate normal distribution of two standard normal variables with correlation coefficient ρ. Two variates X0 and X1 must be provided. Constraints: 0 <= ρ <= 1, 0 <= P <= 1. -* `PDF.CAUCHY (X, A, B)` - `CDF.CAUCHY (X, A, B)` - `IDF.CAUCHY (P, A, B)` - `RV.CAUCHY (A, B)` +* `PDF.CAUCHY(X, A, B)` + `CDF.CAUCHY(X, A, B)` + `IDF.CAUCHY(P, A, B)` + `RV.CAUCHY(A, B)` Cauchy distribution with location parameter `A` and scale parameter `B`. Constraints: B > 0, 0 < P < 1. -* `CDF.CHISQ (X, DF)` - `SIG.CHISQ (X, DF)` - `IDF.CHISQ (P, DF)` - `RV.CHISQ (DF)` - `NCDF.CHISQ (X, DF, ꟛ)` +* `CDF.CHISQ(X, DF)` + `SIG.CHISQ(X, DF)` + `IDF.CHISQ(P, DF)` + `RV.CHISQ(DF)` + `NCDF.CHISQ(X, DF, ꟛ)` Chi-squared distribution with DF degrees of freedom. The noncentral distribution takes an additional parameter ꟛ. Constraints: DF > 0, ꟛ > 0, X >= 0, 0 <= P < 1. -* `PDF.EXP (X, A)` - `CDF.EXP (X, A)` - `IDF.EXP (P, A)` - `RV.EXP (A)` +* `PDF.EXP(X, A)` + `CDF.EXP(X, A)` + `IDF.EXP(P, A)` + `RV.EXP(A)` Exponential distribution with scale parameter `A`. The inverse of `A` represents the rate of decay. Constraints: A > 0, X >= 0, 0 <= P < 1. -* `PDF.XPOWER (X, A, B)` - `RV.XPOWER (A, B)` +* `PDF.XPOWER(X, A, B)` + `RV.XPOWER(A, B)` Exponential power distribution with positive scale parameter `A` and nonnegative power parameter `B`. Constraints: A > 0, B >= 0, X >= 0, 0 <= P <= 1. This distribution is a PSPP extension. -* `PDF.F (X, DF1, DF2)` - `CDF.F (X, DF1, DF2)` - `SIG.F (X, DF1, DF2)` - `IDF.F (P, DF1, DF2)` - `RV.F (DF1, DF2)` +* `PDF.F(X, DF1, DF2)` + `CDF.F(X, DF1, DF2)` + `SIG.F(X, DF1, DF2)` + `IDF.F(P, DF1, DF2)` + `RV.F(DF1, DF2)` F-distribution of two chi-squared deviates with DF1 and DF2 degrees of freedom. The noncentral distribution takes an additional parameter ꟛ. Constraints: DF1 > 0, DF2 > 0, ꟛ >= 0, X >= 0, 0 <= P < 1. -* `PDF.GAMMA (X, A, B)` - `CDF.GAMMA (X, A, B)` - `IDF.GAMMA (P, A, B)` - `RV.GAMMA (A, B)` +* `PDF.GAMMA(X, A, B)` + `CDF.GAMMA(X, A, B)` + `IDF.GAMMA(P, A, B)` + `RV.GAMMA(A, B)` Gamma distribution with shape parameter `A` and scale parameter `B`. Constraints: A > 0, B > 0, X >= 0, 0 <= P < 1. -* `PDF.LANDAU (X)` - `RV.LANDAU ()` +* `PDF.LANDAU(X)` + `RV.LANDAU()` Landau distribution. -* `PDF.LAPLACE (X, A, B)` - `CDF.LAPLACE (X, A, B)` - `IDF.LAPLACE (P, A, B)` - `RV.LAPLACE (A, B)` +* `PDF.LAPLACE(X, A, B)` + `CDF.LAPLACE(X, A, B)` + `IDF.LAPLACE(P, A, B)` + `RV.LAPLACE(A, B)` Laplace distribution with location parameter `A` and scale parameter `B`. Constraints: B > 0, 0 < P < 1. -* `RV.LEVY (C, ɑ)` +* `RV.LEVY(C, ɑ)` Levy symmetric alpha-stable distribution with scale C and exponent ɑ. Constraints: 0 < ɑ <= 2. -* `RV.LVSKEW (C, ɑ, β)` +* `RV.LVSKEW(C, ɑ, β)` Levy skew alpha-stable distribution with scale C, exponent ɑ, and skewness parameter β. Constraints: 0 < ɑ <= 2, -1 <= β <= 1. -* `PDF.LOGISTIC (X, A, B)` - `CDF.LOGISTIC (X, A, B)` - `IDF.LOGISTIC (P, A, B)` - `RV.LOGISTIC (A, B)` +* `PDF.LOGISTIC(X, A, B)` + `CDF.LOGISTIC(X, A, B)` + `IDF.LOGISTIC(P, A, B)` + `RV.LOGISTIC(A, B)` Logistic distribution with location parameter `A` and scale parameter `B`. Constraints: B > 0, 0 < P < 1. -* `PDF.LNORMAL (X, A, B)` - `CDF.LNORMAL (X, A, B)` - `IDF.LNORMAL (P, A, B)` - `RV.LNORMAL (A, B)` +* `PDF.LNORMAL(X, A, B)` + `CDF.LNORMAL(X, A, B)` + `IDF.LNORMAL(P, A, B)` + `RV.LNORMAL(A, B)` Lognormal distribution with parameters `A` and `B`. Constraints: A > 0, B > 0, X >= 0, 0 <= P < 1. -* `PDF.NORMAL (X, μ, σ)` - `CDF.NORMAL (X, μ, σ)` - `IDF.NORMAL (P, μ, σ)` - `RV.NORMAL (μ, σ)` +* `PDF.NORMAL(X, μ, σ)` + `CDF.NORMAL(X, μ, σ)` + `IDF.NORMAL(P, μ, σ)` + `RV.NORMAL(μ, σ)` Normal distribution with mean μ and standard deviation σ. Constraints: B > 0, 0 < P < 1. Three additional functions are available as shorthand: - * `CDFNORM (X)` + * `CDFNORM(X)` Equivalent to `CDF.NORMAL(X, 0, 1)`. - * `PROBIT (P)` + * `PROBIT(P)` Equivalent to `IDF.NORMAL(P, 0, 1)`. - * `NORMAL (σ)` + * `NORMAL(σ)` Equivalent to `RV.NORMAL(0, σ)`. -* `PDF.NTAIL (X, A, σ)` - `RV.NTAIL (A, σ)` +* `PDF.NTAIL(X, A, σ)` + `RV.NTAIL(A, σ)` Normal tail distribution with lower limit `A` and standard deviation `σ`. This distribution is a PSPP extension. Constraints: A > 0, X > A, 0 < P < 1. -* `PDF.PARETO (X, A, B)` - `CDF.PARETO (X, A, B)` - `IDF.PARETO (P, A, B)` - `RV.PARETO (A, B)` +* `PDF.PARETO(X, A, B)` + `CDF.PARETO(X, A, B)` + `IDF.PARETO(P, A, B)` + `RV.PARETO(A, B)` Pareto distribution with threshold parameter `A` and shape parameter `B`. Constraints: A > 0, B > 0, X >= A, 0 <= P < 1. -* `PDF.RAYLEIGH (X, σ)` - `CDF.RAYLEIGH (X, σ)` - `IDF.RAYLEIGH (P, σ)` - `RV.RAYLEIGH (σ)` +* `PDF.RAYLEIGH(X, σ)` + `CDF.RAYLEIGH(X, σ)` + `IDF.RAYLEIGH(P, σ)` + `RV.RAYLEIGH(σ)` Rayleigh distribution with scale parameter σ. This distribution is a PSPP extension. Constraints: σ > 0, X > 0. -* `PDF.RTAIL (X, A, σ)` - `RV.RTAIL (A, σ)` +* `PDF.RTAIL(X, A, σ)` + `RV.RTAIL(A, σ)` Rayleigh tail distribution with lower limit `A` and scale parameter `σ`. This distribution is a PSPP extension. Constraints: A > 0, σ > 0, X > A. -* `PDF.T (X, DF)` - `CDF.T (X, DF)` - `IDF.T (P, DF)` - `RV.T (DF)` +* `PDF.T(X, DF)` + `CDF.T(X, DF)` + `IDF.T(P, DF)` + `RV.T(DF)` T-distribution with DF degrees of freedom. The noncentral distribution takes an additional parameter ꟛ. Constraints: DF > 0, 0 < P < 1. -* `PDF.T1G (X, A, B)` - `CDF.T1G (X, A, B)` - `IDF.T1G (P, A, B)` +* `PDF.T1G(X, A, B)` + `CDF.T1G(X, A, B)` + `IDF.T1G(P, A, B)` Type-1 Gumbel distribution with parameters `A` and `B`. This distribution is a PSPP extension. Constraints: 0 < P < 1. -* `PDF.T2G (X, A, B)` - `CDF.T2G (X, A, B)` - `IDF.T2G (P, A, B)` +* `PDF.T2G(X, A, B)` + `CDF.T2G(X, A, B)` + `IDF.T2G(P, A, B)` Type-2 Gumbel distribution with parameters `A` and `B`. This distribution is a PSPP extension. Constraints: X > 0, 0 < P < 1. -* `PDF.UNIFORM (X, A, B)` - `CDF.UNIFORM (X, A, B)` - `IDF.UNIFORM (P, A, B)` - `RV.UNIFORM (A, B)` +* `PDF.UNIFORM(X, A, B)` + `CDF.UNIFORM(X, A, B)` + `IDF.UNIFORM(P, A, B)` + `RV.UNIFORM(A, B)` Uniform distribution with parameters `A` and `B`. Constraints: A <= X <= B, 0 <= P <= 1. An additional function is available as shorthand: - - `UNIFORM (B)` + - `UNIFORM(B)` Equivalent to `RV.UNIFORM(0, B)`. -* `PDF.WEIBULL (X, A, B)` - `CDF.WEIBULL (X, A, B)` - `IDF.WEIBULL (P, A, B)` - `RV.WEIBULL (A, B)` +* `PDF.WEIBULL(X, A, B)` + `CDF.WEIBULL(X, A, B)` + `IDF.WEIBULL(P, A, B)` + `RV.WEIBULL(A, B)` Weibull distribution with parameters `A` and `B`. Constraints: A > 0, B > 0, X >= 0, 0 <= P < 1. @@ -230,44 +230,44 @@ The following continuous distributions are available: The following discrete distributions are available: -* `PDF.BERNOULLI (X)` - `CDF.BERNOULLI (X, P)` - `RV.BERNOULLI (P)` +* `PDF.BERNOULLI(X)` + `CDF.BERNOULLI(X, P)` + `RV.BERNOULLI(P)` Bernoulli distribution with probability of success P. Constraints: X = 0 or 1, 0 <= P <= 1. -* `PDF.BINOM (X, N, P)` - `CDF.BINOM (X, N, P)` - `RV.BINOM (N, P)` +* `PDF.BINOM(X, N, P)` + `CDF.BINOM(X, N, P)` + `RV.BINOM(N, P)` Binomial distribution with N trials and probability of success P. Constraints: integer N > 0, 0 <= P <= 1, integer X <= N. -* `PDF.GEOM (X, N, P)` - `CDF.GEOM (X, N, P)` - `RV.GEOM (N, P)` +* `PDF.GEOM(X, N, P)` + `CDF.GEOM(X, N, P)` + `RV.GEOM(N, P)` Geometric distribution with probability of success P. Constraints: 0 <= P <= 1, integer X > 0. -* `PDF.HYPER (X, A, B, C)` - `CDF.HYPER (X, A, B, C)` - `RV.HYPER (A, B, C)` +* `PDF.HYPER(X, A, B, C)` + `CDF.HYPER(X, A, B, C)` + `RV.HYPER(A, B, C)` Hypergeometric distribution when `B` objects out of `A` are drawn and `C` of the available objects are distinctive. Constraints: integer A > 0, integer B <= A, integer C <= A, integer X >= 0. -* `PDF.LOG (X, P)` - `RV.LOG (P)` +* `PDF.LOG(X, P)` + `RV.LOG(P)` Logarithmic distribution with probability parameter P. Constraints: 0 <= P < 1, X >= 1. -* `PDF.NEGBIN (X, N, P)` - `CDF.NEGBIN (X, N, P)` - `RV.NEGBIN (N, P)` +* `PDF.NEGBIN(X, N, P)` + `CDF.NEGBIN(X, N, P)` + `RV.NEGBIN(N, P)` Negative binomial distribution with number of successes parameter N and probability of success parameter P. Constraints: integer N >= 0, 0 < P <= 1, integer X >= 1. -* `PDF.POISSON (X, μ)` - `CDF.POISSON (X, μ)` - `RV.POISSON (μ)` +* `PDF.POISSON(X, μ)` + `CDF.POISSON(X, μ)` + `RV.POISSON(μ)` Poisson distribution with mean μ. Constraints: μ > 0, integer X >= 0. diff --git a/rust/doc/src/language/expressions/index.md b/rust/doc/src/language/expressions/index.md index e764aca3c8..19281e755d 100644 --- a/rust/doc/src/language/expressions/index.md +++ b/rust/doc/src/language/expressions/index.md @@ -1,12 +1,54 @@ # Mathematical Expressions Expressions share a common syntax each place they appear in PSPP -commands. Expressions are made up of "operands", which can be numbers, -strings, or variable names, separated by "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. +commands. Expressions are made up of "operands", which can be +numbers, strings, variable names, or invocations of functions, +separated by "operators". + +## Boolean Values + +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. + +## Missing Values + +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 `VALUE` and +`SYSMIS` functions. + + The [missing-value functions](functions/missing-value.md) can be +used to precisely control how missing values are treated in +expressions. + +## Order of Operations + +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. + +1. `()` +2. `**` +3. Unary `+` and `-` +4. `* /` +5. Binary `+` and `-` +6. `= >= > <= < <>` +7. `NOT` +8. `AND` +9. `OR` diff --git a/rust/doc/src/language/expressions/operators.md b/rust/doc/src/language/expressions/operators.md new file mode 100644 index 0000000000..23e232abe1 --- /dev/null +++ b/rust/doc/src/language/expressions/operators.md @@ -0,0 +1,103 @@ +# Operators + +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. + +## Grouping Operators + +Parentheses (`()`) 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. + +## Arithmetic Operators + +The arithmetic operators take numeric operands and produce numeric +results. + +* `A + B` + `A - B` + Addition and subtraction. + +* `A * B` + Multiplication. If either `A` or `B` is 0, then the result is 0, + even if the other operand is missing. + +* `A / B` + Division. If `A` is 0, then the result is 0, even if `B` is + missing. If `B` is zero, the result is system-missing. + +* `A ** B` + `A` raised to the power `B`. If `A` is negative and `B` is not an + integer, the result is system-missing. `0**0` is also + system-missing. + +* `-A` + Reverses the sign of `A`. + +## Logical Operators + +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. See [Boolean Values](#boolean-values), above, for more +information. + +* `A AND B` + `A & B` + True if both `A` and `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. + +* `A OR B` + `A | B` + True if at least one of `A` and `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. + +* `NOT A` + `~A` + True if `A` is false. If the operand is missing, then the result is + missing. + +## 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. + +* `A EQ B` + `A = B` + True if `A` is equal to `B`. + +* `A LE B` + `A <= B` + True if `A` is less than or equal to `B`. + +* `A LT B` + `A < B` + True if `A` is less than `B`. + +* `A GE B` + `A >= B` + True if `A` is greater than or equal to `B`. + +* `A GT B` + `A > B` + True if `A` is greater than `B`. + +* `A NE B` + `A ~= B` + `A <> B` + True if `A` is not equal to `B`. +