X-Git-Url: https://pintos-os.org/cgi-bin/gitweb.cgi?a=blobdiff_plain;f=doc%2Fexpressions.texi;h=cd214380e7326a5d5e23fd165fc85d867404f264;hb=5f832a7feba823b45f0e692f4052a3ceb081df65;hp=d27d11b40744a467de4ddcaaf57fccbe55c0ac41;hpb=55c55aa33d0f90d1b3b58f8b33b3fc54062c553e;p=pspp diff --git a/doc/expressions.texi b/doc/expressions.texi index d27d11b407..cd214380e7 100644 --- a/doc/expressions.texi +++ b/doc/expressions.texi @@ -1,7 +1,16 @@ -@c Use @func when refering to a function. -@c Use @deftypefn for their definitions +@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/} +@code{\NAME\} @end macro @node Expressions @@ -123,7 +132,7 @@ 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}. +Reverses the sign of @var{a}. @end table @node Logical Operators @@ -263,7 +272,7 @@ The sections below describe each function in detail. * 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 +* 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 @@ -414,7 +423,11 @@ functions. In particular, user-missing values for numeric variables are converted to system-missing values. @deftypefn {Function} {} MISSING (@var{expr}) -Returns 1 if @var{expr} has the system-missing value, 0 otherwise. +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{}) @@ -430,16 +443,14 @@ variable ranges using the @code{@var{var1} TO @var{var2}} syntax. @end deftypefn @deftypefn {Function} {} SYSMIS (@var{expr}) -When @var{expr} is simply the name of a numeric variable, returns 1 if -the variable has the system-missing value, 0 if it is user-missing or -not missing. If given @var{expr} takes another form, results in 1 if -the value is system-missing, 0 otherwise. +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 +@deftypefnx {Function} {} VALUE (@var{vector}(@var{index})) +Prevents the user-missing values of the variable or vector element +from being transformed into system-missing values, and always results +in its actual value, whether it is valid, user-missing, or system-missing. @end deftypefn @@ -453,23 +464,25 @@ 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}. +@ref{Relational Operators}. User-missing string values are treated as +valid values. @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. +Returns true if @var{value} is equal to any of the @var{set} values, +and false otherwise. For numeric arguments, returns system-missing if +@var{value} is system-missing or if all the values in @var{set} are +system-missing. If @var{value} @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. +Returns true if @var{value} is in any of the intervals bounded by +@var{low} and @var{high} inclusive, and false otherwise. @var{low} +and @var{high} must be given in pairs. Returns system-missing if any +@var{high} is less than its @var{low} or, for numeric arguments, if +@var{value} is system-missing or if all the @var{low}-@var{high} pairs +contain one (or two) system-missing values. A pair does not match +@var{value} if either @var{low} or @var{high} is missing, even if +@var{value} equals the non-missing endpoint. @end deftypefn @node Statistical Functions @@ -557,30 +570,33 @@ String functions take various arguments and return various results. @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. +The resultant string is truncated to a maximum of 32767 bytes. @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. +@deftypefnx {Function} {} RINDEX (@var{haystack}, @var{needle}) +Returns a positive integer indicating the position of the first (for +@code{INDEX}) or last (for @code{RINDEX}) occurrence of @var{needle} +in @var{haystack}. Returns 0 if @var{haystack} does not contain +@var{needle}. Returns 1 if @var{needle} is the 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. +@deftypefnx {Function} {} RINDEX (@var{haystack}, @var{needle}, @var{needle_len}) +Divides @var{needles} into multiple needles, each with length +@var{needle_len}, which must be a positive integer that evenly divides +the length of @var{needles}. Searches @var{haystack} for the +occurrences of each needle and returns a positive integer indicating +the byte index of the beginning of the first (for @code{INDEX}) or +last (for @code{RINDEX}) needle it finds. Returns 0 if @var{haystack} +does not contain any of the needles, or if @var{needles} is the empty +string. @end deftypefn @cindex strings, finding length of @deftypefn {Function} {} LENGTH (@var{string}) -Returns the number of characters in @var{string}. +Returns the number of bytes in @var{string}. @end deftypefn @cindex strings, case of @@ -591,33 +607,30 @@ letters are changed to lowercase letters. The definitions of @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}]) +@deftypefnx {Function} {} RPAD (@var{string}, @var{length}[, @var{padding}]) +If @var{string} is at least @var{length} bytes long, these functions +return @var{string} unchanged. Otherwise, they return @var{string} +padded with @var{padding} on the left side (for @code{LPAD}) or right +side (for @code{RPAD}) to @var{length} bytes. These functions report +an error and return @var{string} unchanged if @var{length} is missing +or bigger than 32767. -@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. +The @var{padding} argument must not be an empty string and defaults to +a space if not specified. If its length does not evenly fit the +amount of space needed for padding, the returned string will be +shorter than @var{length}. @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. +@deftypefn {Function} {} LTRIM (@var{string}[, @var{padding}]) +@deftypefnx {Function} {} RTRIM (@var{string}[, @var{padding}]) +These functions return @var{string}, after removing leading (for +@code{LTRIM}) or trailing (for @code{RTRIM}) copies of @var{padding}. +If @var{padding} is omitted, these functions remove spaces (but not +tabs or other white space). These functions return @var{string} +unchanged if @var{padding} is the empty string. @end deftypefn @cindex numbers, converting from strings @@ -625,9 +638,9 @@ empty string. @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, e.g.@: @code{NUMBER("123", F3.0)} -and @code{NUMBER("1234", F3.0)} both have value 123. If @var{w} is +than the length of @var{string}, then only the first @var{w} bytes 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. @@ -642,53 +655,6 @@ 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}) @@ -702,8 +668,9 @@ has the value @code{"123.6"}. @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. +removing trailing spaces (but not tabs or other white space). Returns +an empty string if @var{n} is zero or negative, or @var{string} +unchanged if @var{n} is missing. @end deftypefn @cindex substrings @@ -715,15 +682,15 @@ 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"}. +Returns a string consisting of the first @var{count} bytes 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 bytes in @var{string}, or +if @var{count} is less than 1. Returns a string shorter than +@var{count} bytes if @var{start} + @var{count} - 1 is greater than the +number of bytes 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 @@ -761,7 +728,7 @@ Most time and date functions will not accept earlier dates. 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 @@ -804,7 +771,7 @@ Returns a time corresponding to @var{ndays} days. 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. +vice versa. @end deftypefn @node Time Extraction @@ -958,7 +925,7 @@ that is, gives the date that @var{date-or-time} is in. 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}. +@var{date-or-time}. @end deftypefn @cindex day of the year @@ -980,7 +947,7 @@ corresponding to @var{date}. @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}. +the last hour in @var{time-or-date}. @end deftypefn @cindex months @@ -1214,8 +1181,8 @@ include an NCDF function. The individual distributions are described individually below. @menu -* Continuous Distributions:: -* Discrete Distributions:: +* Continuous Distributions:: +* Discrete Distributions:: @end menu @node Continuous Distributions @@ -1236,7 +1203,7 @@ Constraints: @var{a} > 0, @var{b} > 0, @var{lambda} >= 0, 0 <= @var{x} @end deftypefn @deftypefn {Function} {} PDF.BVNOR (@var{x0}, @var{x1}, @var{rho}) -@deftypefnx {Function} {} CDF.VBNOR (@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. @@ -1544,7 +1511,7 @@ subtraction. @enumerate @item -@code{( )} +@code{()} @item @code{**} @item @@ -1554,7 +1521,11 @@ subtraction. @item @code{+ -} @item -@code{EQ GE GT LE LT NE} +@code{= >= > <= < <>} +@item +@code{NOT} +@item +@code{AND} @item -@code{AND NOT OR} +@code{OR} @end enumerate