1 @node Expressions, Data Input and Output, Language, Top
2 @chapter Mathematical Expressions
3 @cindex expressions, mathematical
4 @cindex mathematical expressions
6 Some PSPP commands use expressions, which share a common syntax
7 among all PSPP commands. Expressions are made up of
8 @dfn{operands}, which can be numbers, strings, or variable names,
9 separated by @dfn{operators}. There are five types of operators:
10 grouping, arithmetic, logical, relational, and functions.
12 Every operator takes one or more @dfn{arguments} as input and produces
13 or @dfn{returns} exactly one result as output. Both strings and numeric
14 values can be used as arguments and are produced as results, but each
15 operator accepts only specific combinations of numeric and string values
16 as arguments. With few exceptions, operator arguments may be
17 full-fledged expressions in themselves.
20 * Boolean Values:: Boolean values.
21 * Missing Values in Expressions:: Using missing values in expressions.
22 * Grouping Operators:: parentheses
23 * Arithmetic Operators:: add sub mul div pow
24 * Logical Operators:: AND NOT OR
25 * Relational Operators:: EQ GE GT LE LT NE
26 * Functions:: More-sophisticated operators.
27 * Order of Operations:: Operator precedence.
30 @node Boolean Values, Missing Values in Expressions, Expressions, Expressions
31 @section Boolean Values
33 @cindex values, Boolean
35 Some PSPP operators and expressions work with Boolean values, which
36 represent true/false conditions. Booleans have only three possible
37 values: 0 (false), 1 (true), and system-missing (unknown).
38 System-missing is neither true nor false and indicates that the true
41 Boolean-typed operands or function arguments must take on one of these
42 three values. Other values are considered false, but cause an error
43 when the expression is evaluated.
45 Strings and Booleans are not compatible, and neither may be used in
48 @node Missing Values in Expressions, Grouping Operators, Boolean Values, Expressions
49 @section Missing Values in Expressions
51 String missing values are not treated specially in expressions. Most
52 numeric operators return system-missing when given system-missing
53 arguments. Exceptions are listed under particular operator
56 User-missing values for numeric variables are always transformed into
57 the system-missing value, except inside the arguments to the
58 @code{VALUE} and @code{SYSMIS} functions.
60 The missing-value functions can be used to precisely control how missing
61 values are treated in expressions. @xref{Missing Value Functions}, for
64 @node Grouping Operators, Arithmetic Operators, Missing Values in Expressions, Expressions
65 @section Grouping Operators
68 @cindex grouping operators
69 @cindex operators, grouping
71 Parentheses (@samp{()}) are the grouping operators. Surround an
72 expression with parentheses to force early evaluation.
74 Parentheses also surround the arguments to functions, but in that
75 situation they act as punctuators, not as operators.
77 @node Arithmetic Operators, Logical Operators, Grouping Operators, Expressions
78 @section Arithmetic Operators
79 @cindex operators, arithmetic
80 @cindex arithmetic operators
82 The arithmetic operators take numeric arguments and produce numeric
88 @item @var{a} + @var{b}
89 Adds @var{a} and @var{b}, returning the sum.
93 @item @var{a} - @var{b}
94 Subtracts @var{b} from @var{a}, returning the difference.
97 @cindex multiplication
98 @item @var{a} * @var{b}
99 Multiplies @var{a} and @var{b}, returning the product.
103 @item @var{a} / @var{b}
104 Divides @var{a} by @var{b}, returning the quotient. If @var{b} is
105 zero, the result is system-missing.
108 @cindex exponentiation
109 @item @var{a} ** @var{b}
110 Returns the result of raising @var{a} to the power @var{b}. If
111 @var{a} is negative and @var{b} is not an integer, the result is
112 system-missing. The result of @code{0**0} is system-missing as well.
117 Reverses the sign of @var{a}.
120 @node Logical Operators, Relational Operators, Arithmetic Operators, Expressions
121 @section Logical Operators
122 @cindex logical operators
123 @cindex operators, logical
128 @cindex values, system-missing
129 @cindex system-missing
130 The logical operators take logical arguments and produce logical
131 results, meaning ``true or false''. PSPP logical operators are
132 not true Boolean operators because they may also result in a
133 system-missing value.
138 @cindex intersection, logical
139 @cindex logical intersection
140 @item @var{a} AND @var{b}
141 @itemx @var{a} & @var{b}
142 True if both @var{a} and @var{b} are true, false otherwise. If one
143 argument is false, the result is false even if the other is missing. If
144 both arguments are missing, the result is missing.
148 @cindex union, logical
149 @cindex logical union
150 @item @var{a} OR @var{b}
151 @itemx @var{a} | @var{b}
152 True if at least one of @var{a} and @var{b} is true. If one argument is
153 true, the result is true even if the other argument is missing. If both
154 arguments are missing, the result is missing.
158 @cindex inversion, logical
159 @cindex logical inversion
162 True if @var{a} is false. If the argument is missing, then the result
166 @node Relational Operators, Functions, Logical Operators, Expressions
167 @section Relational Operators
169 The relational operators take numeric or string arguments and produce Boolean
172 Strings cannot be compared to numbers. When strings of different
173 lengths are compared, the shorter string is right-padded with spaces
174 to match the length of the longer string.
176 The results of string comparisons, other than tests for equality or
177 inequality, are dependent on the character set in use. String
178 comparisons are case-sensitive.
181 @cindex equality, testing
182 @cindex testing for equality
185 @item @var{a} EQ @var{b}
186 @itemx @var{a} = @var{b}
187 True if @var{a} is equal to @var{b}.
189 @cindex less than or equal to
192 @item @var{a} LE @var{b}
193 @itemx @var{a} <= @var{b}
194 True if @var{a} is less than or equal to @var{b}.
199 @item @var{a} LT @var{b}
200 @itemx @var{a} < @var{b}
201 True if @var{a} is less than @var{b}.
203 @cindex greater than or equal to
206 @item @var{a} GE @var{b}
207 @itemx @var{a} >= @var{b}
208 True if @var{a} is greater than or equal to @var{b}.
213 @item @var{a} GT @var{b}
214 @itemx @var{a} > @var{b}
215 True if @var{a} is greater than @var{b}.
217 @cindex inequality, testing
218 @cindex testing for inequality
222 @item @var{a} NE @var{b}
223 @itemx @var{a} ~= @var{b}
224 @itemx @var{a} <> @var{b}
225 True is @var{a} is not equal to @var{b}.
228 @node Functions, Order of Operations, Relational Operators, Expressions
237 @cindex names, of functions
238 PSPP functions provide mathematical abilities above and beyond
239 those possible using simple operators. Functions have a common
240 syntax: each is composed of a function name followed by a left
241 parenthesis, one or more arguments, and a right parenthesis. Function
242 names are @strong{not} reserved; their names are specially treated
243 only when followed by a left parenthesis: @code{EXP(10)} refers to the
244 constant value @code{e} raised to the 10th power, but @code{EXP} by
245 itself refers to the value of variable EXP.
247 The sections below describe each function in detail.
250 * Advanced Mathematics:: EXP LG10 LN SQRT
251 * Miscellaneous Mathematics:: ABS MOD MOD10 RND TRUNC
252 * Trigonometry:: ACOS ARCOS ARSIN ARTAN ASIN ATAN COS SIN TAN
253 * Missing Value Functions:: MISSING NMISS NVALID SYSMIS VALUE
254 * Pseudo-Random Numbers:: NORMAL UNIFORM
255 * Set Membership:: ANY RANGE
256 * Statistical Functions:: CFVAR MAX MEAN MIN SD SUM VARIANCE
257 * String Functions:: CONCAT INDEX LENGTH LOWER LPAD LTRIM NUMBER
258 RINDEX RPAD RTRIM STRING SUBSTR UPCASE
259 * Time & Date:: CTIME.xxx DATE.xxx TIME.xxx XDATE.xxx
260 * Miscellaneous Functions:: LAG YRMODA
261 * Functions Not Implemented:: CDF.xxx CDFNORM IDF.xxx NCDF.xxx PROBIT RV.xxx
264 @node Advanced Mathematics, Miscellaneous Mathematics, Functions, Functions
265 @subsection Advanced Mathematical Functions
266 @cindex mathematics, advanced
268 Advanced mathematical functions take numeric arguments and produce
271 @deftypefn {Function} {} EXP (@var{exponent})
272 Returns @i{e} (approximately 2.71828) raised to power @var{exponent}.
276 @deftypefn {Function} {} LG10 (@var{number})
277 Takes the base-10 logarithm of @var{number}. If @var{number} is
278 not positive, the result is system-missing.
281 @deftypefn {Function} {} LN (@var{number})
282 Takes the base-@i{e} logarithm of @var{number}. If @var{number} is
283 not positive, the result is system-missing.
287 @deftypefn {Function} {} SQRT (@var{number})
288 Takes the square root of @var{number}. If @var{number} is negative,
289 the result is system-missing.
292 @node Miscellaneous Mathematics, Trigonometry, Advanced Mathematics, Functions
293 @subsection Miscellaneous Mathematical Functions
294 @cindex mathematics, miscellaneous
296 Miscellaneous mathematical functions take numeric arguments and produce
299 @cindex absolute value
300 @deftypefn {Function} {} ABS (@var{number})
301 Results in the absolute value of @var{number}.
305 @deftypefn {Function} {} MOD (@var{numerator}, @var{denominator})
306 Returns the remainder (modulus) of @var{numerator} divided by
307 @var{denominator}. If @var{denominator} is 0, the result is
308 system-missing. However, if @var{numerator} is 0 and
309 @var{denominator} is system-missing, the result is 0.
312 @cindex modulus, by 10
313 @deftypefn {Function} {} MOD10 (@var{number})
314 Returns the remainder when @var{number} is divided by 10. If
315 @var{number} is negative, MOD10(@var{number}) is negative or zero.
319 @deftypefn {Function} {} RND (@var{number})
320 Takes the absolute value of @var{number} and rounds it to an integer.
321 Then, if @var{number} was negative originally, negates the result.
325 @deftypefn {Function} {} TRUNC (@var{number})
326 Discards the fractional part of @var{number}; that is, rounds
327 @var{number} towards zero.
330 @node Trigonometry, Missing Value Functions, Miscellaneous Mathematics, Functions
331 @subsection Trigonometric Functions
334 Trigonometric functions take numeric arguments and produce numeric
338 @cindex inverse cosine
339 @deftypefn {Function} {} ARCOS (@var{number})
340 Takes the arccosine, in radians, of @var{number}. Results in
341 system-missing if @var{number} is not between -1 and 1.
346 @deftypefn {Function} {} ARSIN (@var{number})
347 Takes the arcsine, in radians, of @var{number}. Results in
348 system-missing if @var{number} is not between -1 and 1 inclusive.
352 @cindex inverse tangent
353 @deftypefn {Function} {} ARTAN (@var{number})
354 Takes the arctangent, in radians, of @var{number}.
358 @deftypefn {Function} {} COS (@var{angle})
359 Takes the cosine of @var{angle} which should be in radians.
363 @deftypefn {Function} {} SIN (@var{angle})
364 Takes the sine of @var{angle} which should be in radians.
368 @deftypefn {Function} {} TAN (@var{angle})
369 Takes the tangent of @var{angle} which should be in radians.
370 Results in system-missing at values
371 of @var{angle} that are too close to odd multiples of pi/2.
375 @node Missing Value Functions, Pseudo-Random Numbers, Trigonometry, Functions
376 @subsection Missing-Value Functions
377 @cindex missing values
378 @cindex values, missing
379 @cindex functions, missing-value
381 Missing-value functions take various numeric arguments and yield
382 various types of results. Note that the normal rules of evaluation
383 apply within expression arguments to these functions. In particular,
384 user-missing values for numeric variables are converted to
385 system-missing values.
387 @deftypefn {Function} {} MISSING (@var{expr})
388 Returns 1 if @var{expr} has the system-missing value, 0 otherwise.
391 @deftypefn {Function} {} NMISS (@var{expr} [, @var{expr}]@dots{})
392 Each argument must be a numeric expression. Returns the number of
393 system-missing values in the list. As a special extension,
394 the syntax @code{@var{var1} TO @var{var2}} may be used to refer to a
395 range of variables; see @ref{Sets of Variables}, for more details.
398 @deftypefn {Function} {} NVALID (@var{expr} [, @var{expr}]@dots{})
399 Each argument must be a numeric expression. Returns the number of
400 values in the list that are not system-missing. As a special extension,
401 the syntax @code{@var{var1} TO @var{var2}} may be used to refer to a
402 range of variables; see @ref{Sets of Variables}, for more details.
405 @deftypefn {Function} {} SYSMIS (@var{expr})
406 When @var{expr} is simply the name of a numeric variable, returns 1 if
407 the variable has the system-missing value, 0 if it is user-missing or
408 not missing. If given @var{expr} takes another form, results in 1 if
409 the value is system-missing, 0 otherwise.
412 @deftypefn {Function} {} VALUE (@var{variable})
413 Prevents the user-missing values of @var{variable} from being
414 transformed into system-missing values, and always results in the
415 actual value of @var{variable}, whether it is user-missing,
416 system-missing or not missing at all.
419 @node Pseudo-Random Numbers, Set Membership, Missing Value Functions, Functions
420 @subsection Pseudo-Random Number Generation Functions
421 @cindex random numbers
422 @cindex pseudo-random numbers (see random numbers)
424 Pseudo-random number generation (PRNG) functions take numeric arguments and
425 produce numeric results.
427 PSPP uses the ``Mersenne Twister'' PRNG as implemented in the GNU
428 Scientific Library, specifically the @code{gsl_rng_mt19937} variant.
429 This PRNG is a variant of the twisted generalized feedback
430 shift-register algorithm The bytes output by this PRNG are
431 system-independent for a given random seed, but differences in
432 endianness and floating-point formats will make PRNG results differ
433 from system to system.
435 @cindex random numbers, normally-distributed
436 @deftypefn {Function} {} NORMAL (@var{stddev})
437 Results in a random number. Results from @code{NORMAL} are normally
438 distributed with a mean of 0 and a standard deviation of @var{stddev}.
441 @cindex random numbers, uniformly-distributed
442 @deftypefn {Function} {} UNIFORM (@var{max})
443 Results in a random number in the half-open interval [0,@var{max}).
444 Results from @code{UNIFORM} are evenly distributed across its entire
445 range. There may be a maximum on the largest random number ever
446 generated---this is often
453 (2,147,483,647), but it may be orders of magnitude
457 @node Set Membership, Statistical Functions, Pseudo-Random Numbers, Functions
458 @subsection Set-Membership Functions
459 @cindex set membership
460 @cindex membership, of set
462 Set membership functions determine whether a value is a member of a set.
463 They take a set of numeric arguments or a set of string arguments, and
464 produce Boolean results.
466 String comparisons are performed according to the rules given in
467 @ref{Relational Operators}.
469 @deftypefn {Function} {} ANY (@var{value}, @var{set} [, @var{set}]@dots{})
470 Results in true if @var{value} is equal to any of the @var{set}
471 values. Otherwise, results in false. If @var{value} is
472 system-missing, returns system-missing. System-missing values in
473 @var{set} do not cause ANY to return system-missing.
476 @deftypefn {Function} {} RANGE (@var{value}, @var{low}, @var{high} [, @var{low}, @var{high}]@dots{})
477 Results in true if @var{value} is in any of the intervals bounded by
478 @var{low} and @var{high} inclusive. Otherwise, results in false.
479 Each @var{low} must be less than or equal to its corresponding
480 @var{high} value. @var{low} and @var{high} must be given in pairs.
481 If @var{value} is system-missing, returns system-missing.
482 System-missing values in @var{set} do not cause RANGE to return
486 @node Statistical Functions, String Functions, Set Membership, Functions
487 @subsection Statistical Functions
488 @cindex functions, statistical
491 Statistical functions compute descriptive statistics on a list of
492 values. Some statistics can be computed on numeric or string values;
493 other can only be computed on numeric values. Their results have the
494 same type as their arguments. The current case's weighting factor
495 (@pxref{WEIGHT}) has no effect on statistical functions.
497 @cindex arguments, minimum valid
498 @cindex minimum valid number of arguments
499 With statistical functions it is possible to specify a minimum number of
500 non-missing arguments for the function to be evaluated. To do so,
501 append a dot and the number to the function name. For instance, to
502 specify a minimum of three valid arguments to the MEAN function, use the
505 @cindex coefficient of variation
506 @cindex variation, coefficient of
507 @deftypefn {Function} {} CFVAR (@var{number}, @var{number}[, @dots{}])
508 Results in the coefficient of variation of the values of @var{number}.
509 This function requires at least two valid arguments to give a
510 non-missing result. (The coefficient of variation is the standard
511 deviation divided by the mean.)
515 @deftypefn {Function} {} MAX (@var{value}, @var{value}[, @dots{}])
516 Results in the value of the greatest @var{value}. The @var{value}s may
517 be numeric or string. Although at least two arguments must be given,
518 only one need be valid for MAX to give a non-missing result.
522 @deftypefn {Function} {} MEAN (@var{number}, @var{number}[, @dots{}])
523 Results in the mean of the values of @var{number}. Although at least
524 two arguments must be given, only one need be valid for MEAN to give a
529 @deftypefn {Function} {} MIN (@var{number}, @var{number}[, @dots{}])
530 Results in the value of the least @var{value}. The @var{value}s may
531 be numeric or string. Although at least two arguments must be given,
532 only one need be valid for MAX to give a non-missing result.
535 @cindex standard deviation
536 @cindex deviation, standard
537 @deftypefn {Function} {} SD (@var{number}, @var{number}[, @dots{}])
538 Results in the standard deviation of the values of @var{number}.
539 This function requires at least two valid arguments to give a
544 @deftypefn {Function} {} SUM (@var{number}, @var{number}[, @dots{}])
545 Results in the sum of the values of @var{number}. Although at least two
546 arguments must be given, only one need by valid for SUM to give a
551 @deftypefn {Function} {} VARIANCE (@var{number}, @var{number}[, @dots{}])
552 Results in the variance of the values of @var{number}. This function
553 requires at least two valid arguments to give a non-missing result.
556 @node String Functions, Time & Date, Statistical Functions, Functions
557 @subsection String Functions
558 @cindex functions, string
559 @cindex string functions
561 String functions take various arguments and return various results.
563 @cindex concatenation
564 @cindex strings, concatenation of
565 @deftypefn {Function} {} CONCAT (@var{string}, @var{string}[, @dots{}])
566 Returns a string consisting of each @var{string} in sequence.
567 @code{CONCAT("abc", "def", "ghi")} has a value of @code{"abcdefghi"}.
568 The resultant string is truncated to a maximum of 255 characters.
571 @cindex searching strings
572 @deftypefn {Function} {} INDEX (@var{haystack}, @var{needle})
573 Returns a positive integer indicating the position of the first
574 occurrence @var{needle} in @var{haystack}. Returns 0 if @var{haystack}
575 does not contain @var{needle}. Returns system-missing if @var{needle}
579 @deftypefn {Function} {} INDEX (@var{haystack}, @var{needle}, @var{divisor})
580 Divides @var{needle} into parts, each with length @var{divisor}.
581 Searches @var{haystack} for the first occurrence of each part, and
582 returns the smallest value. Returns 0 if @var{haystack} does not
583 contain any part in @var{needle}. It is an error if @var{divisor}
584 cannot be evenly divided into the length of @var{needle}. Returns
585 system-missing if @var{needle} is an empty string.
588 @cindex strings, finding length of
589 @deftypefn {Function} {} LENGTH (@var{string})
590 Returns the number of characters in @var{string}.
593 @cindex strings, case of
594 @deftypefn {Function} {} LOWER (@var{string})
595 Returns a string identical to @var{string} except that all uppercase
596 letters are changed to lowercase letters. The definitions of
597 ``uppercase'' and ``lowercase'' are system-dependent.
600 @cindex strings, padding
601 @deftypefn {Function} {} LPAD (@var{string}, @var{length})
602 If @var{string} is at least @var{length} characters in length, returns
603 @var{string} unchanged. Otherwise, returns @var{string} padded with
604 spaces on the left side to length @var{length}. Returns an empty string
605 if @var{length} is system-missing, negative, or greater than 255.
608 @deftypefn {Function} {} LPAD (@var{string}, @var{length}, @var{padding})
609 If @var{string} is at least @var{length} characters in length, returns
610 @var{string} unchanged. Otherwise, returns @var{string} padded with
611 @var{padding} on the left side to length @var{length}. Returns an empty
612 string if @var{length} is system-missing, negative, or greater than 255, or
613 if @var{padding} does not contain exactly one character.
616 @cindex strings, trimming
617 @cindex whitespace, trimming
618 @deftypefn {Function} {} LTRIM (@var{string})
619 Returns @var{string}, after removing leading spaces. Other whitespace,
620 such as tabs, carriage returns, line feeds, and vertical tabs, is not
624 @deftypefn {Function} {} LTRIM (@var{string}, @var{padding})
625 Returns @var{string}, after removing leading @var{padding} characters.
626 If @var{padding} does not contain exactly one character, returns an
630 @cindex numbers, converting from strings
631 @cindex strings, converting to numbers
632 @deftypefn {Function} {} NUMBER (@var{string}, @var{format})
633 Returns the number produced when @var{string} is interpreted according
634 to format specifier @var{format}. If the format width @var{w} is less
635 than the length of @var{string}, then only the first @var{w}
636 characters in @var{string} are used, e.g.@: @code{NUMBER("123", F3.0)}
637 and @code{NUMBER("1234", F3.0)} both have value 123. If @var{w} is
638 greater than @var{string}'s length, then it is treated as if it were
639 right-padded with spaces. If @var{string} is not in the correct
640 format for @var{format}, system-missing is returned.
643 @cindex strings, searching backwards
644 @deftypefn {Function} {} RINDEX (@var{string}, @var{format})
645 Returns a positive integer indicating the position of the last
646 occurrence of @var{needle} in @var{haystack}. Returns 0 if
647 @var{haystack} does not contain @var{needle}. Returns system-missing if
648 @var{needle} is an empty string.
651 @deftypefn {Function} {} RINDEX (@var{haystack}, @var{needle}, @var{divisor})
652 Divides @var{needle} into parts, each with length @var{divisor}.
653 Searches @var{haystack} for the last occurrence of each part, and
654 returns the largest value. Returns 0 if @var{haystack} does not contain
655 any part in @var{needle}. It is an error if @var{divisor} cannot be
656 evenly divided into the length of @var{needle}. Returns system-missing
657 if @var{needle} is an empty string.
660 @cindex padding strings
661 @cindex strings, padding
662 @deftypefn {Function} {} RPAD (@var{string}, @var{length})
663 If @var{string} is at least @var{length} characters in length, returns
664 @var{string} unchanged. Otherwise, returns @var{string} padded with
665 spaces on the right to length @var{length}. Returns an empty string if
666 @var{length} is system-missing, negative, or greater than 255.
669 @deftypefn {Function} {} RPAD (@var{string}, @var{length}, @var{padding})
670 If @var{string} is at least @var{length} characters in length, returns
671 @var{string} unchanged. Otherwise, returns @var{string} padded with
672 @var{padding} on the right to length @var{length}. Returns an empty
673 string if @var{length} is system-missing, negative, or greater than 255,
674 or if @var{padding} does not contain exactly one character.
677 @cindex strings, trimming
678 @cindex whitespace, trimming
679 @deftypefn {Function} {} RTRIM (@var{string})
680 Returns @var{string}, after removing trailing spaces. Other types of
681 whitespace are not removed.
684 @deftypefn {Function} {} RTRIM (@var{string}, @var{padding})
685 Returns @var{string}, after removing trailing @var{padding} characters.
686 If @var{padding} does not contain exactly one character, returns an
690 @cindex strings, converting from numbers
691 @cindex numbers, converting to strings
692 @deftypefn {Function} {} STRING (@var{number}, @var{format})
693 Returns a string corresponding to @var{number} in the format given by
694 format specifier @var{format}. For example, @code{STRING(123.56, F5.1)}
695 has the value @code{"123.6"}.
699 @cindex strings, taking substrings of
700 @deftypefn {Function} {} SUBSTR (@var{string}, @var{start})
701 Returns a string consisting of the value of @var{string} from position
702 @var{start} onward. Returns an empty string if @var{start} is system-missing
703 or has a value less than 1 or greater than the number of characters in
707 @deftypefn {Function} {} SUBSTR (@var{string}, @var{start}, @var{count})
708 Returns a string consisting of the first @var{count} characters from
709 @var{string} beginning at position @var{start}. Returns an empty string
710 if @var{start} or @var{count} is system-missing, if @var{start} is less
711 than 1 or greater than the number of characters in @var{string}, or if
712 @var{count} is less than 1. Returns a string shorter than @var{count}
713 characters if @var{start} + @var{count} - 1 is greater than the number
714 of characters in @var{string}. Examples: @code{SUBSTR("abcdefg", 3, 2)}
715 has value @code{"cd"}; @code{SUBSTR("Ben Pfaff", 5, 10)} has the value
719 @cindex case conversion
720 @cindex strings, case of
721 @deftypefn {Function} {} UPCASE (@var{string})
722 Returns @var{string}, changing lowercase letters to uppercase letters.
725 @node Time & Date, Miscellaneous Functions, String Functions, Functions
726 @subsection Time & Date Functions
727 @cindex functions, time & date
731 @cindex dates, legal range of
732 The legal range of dates for use in PSPP is 15 Oct 1582
733 through 31 Dec 19999.
735 @cindex arguments, invalid
736 @cindex invalid arguments
738 @strong{Please note:} Most time & date extraction functions will accept
743 Negative numbers in PSPP time format.
745 Numbers less than 86,400 in PSPP date format.
748 However, sensible results are not guaranteed for these invalid values.
749 The given equivalents for these functions are definitely not guaranteed
754 @strong{Please note also:} The time & date construction
755 functions @strong{do} produce reasonable and useful results for
756 out-of-range values; these are not considered invalid.
760 * Time & Date Concepts:: How times & dates are defined and represented
761 * Time Construction:: TIME.@{DAYS HMS@}
762 * Time Extraction:: CTIME.@{DAYS HOURS MINUTES SECONDS@}
763 * Date Construction:: DATE.@{DMY MDY MOYR QYR WKYR YRDAY@}
764 * Date Extraction:: XDATE.@{DATE HOUR JDAY MDAY MINUTE MONTH
765 QUARTER SECOND TDAY TIME WEEK
769 @node Time & Date Concepts, Time Construction, Time & Date, Time & Date
770 @subsubsection How times & dates are defined and represented
772 @cindex time, concepts
773 @cindex time, intervals
774 Times and dates are handled by PSPP as single numbers. A
775 @dfn{time} is an interval. PSPP measures times in seconds.
776 Thus, the following intervals correspond with the numeric values given:
781 1 day, 3 hours, 10 seconds 97,210
783 10010 d, 14 min, 24 s 864,864,864
786 @cindex dates, concepts
787 @cindex time, instants of
788 A @dfn{date}, on the other hand, is a particular instant in the past or
789 the future. PSPP represents a date as a number of seconds after the
790 midnight that separated 8 Oct 1582 and 9 Oct 1582. (Please note that 15
791 Oct 1582 immediately followed 9 Oct 1582.) Thus, the midnights before
792 the dates given below correspond with the numeric PSPP dates given:
796 4 Jul 1776 6,113,318,400
797 1 Jan 1900 10,010,390,400
798 1 Oct 1978 12,495,427,200
799 24 Aug 1995 13,028,601,600
802 @cindex time, mathematical properties of
803 @cindex mathematics, applied to times & dates
804 @cindex dates, mathematical properties of
810 A time may be added to, or subtracted from, a date, resulting in a date.
813 The difference of two dates may be taken, resulting in a time.
816 Two times may be added to, or subtracted from, each other, resulting in
820 (Adding two dates does not produce a useful result.)
822 Since times and dates are merely numbers, the ordinary addition and
823 subtraction operators are employed for these purposes.
826 @strong{Please note:} Many dates and times have extremely large
827 values---just look at the values above. Thus, it is not a good idea to
828 take powers of these values; also, the accuracy of some procedures may
829 be affected. If necessary, convert times or dates in seconds to some
830 other unit, like days or years, before performing analysis.
833 @node Time Construction, Time Extraction, Time & Date Concepts, Time & Date
834 @subsubsection Functions that Produce Times
835 @cindex times, constructing
836 @cindex constructing times
838 These functions take numeric arguments and produce numeric results in
842 @cindex time, in days
843 @deftypefn {Function} {} TIME.DAYS (@var{ndays})
844 Results in a time value corresponding to @var{ndays} days.
845 (@code{TIME.DAYS(@var{x})} is equivalent to @code{@var{x} * 60 * 60 *
849 @cindex hours-minutes-seconds
850 @cindex time, in hours-minutes-seconds
851 @deftypefn {Function} {} TIME.HMS (@var{nhours}, @var{nmins}, @var{nsecs})
852 Results in a time value corresponding to @var{nhours} hours, @var{nmins}
853 minutes, and @var{nsecs} seconds. (@code{TIME.HMS(@var{h}, @var{m},
854 @var{s})} is equivalent to @code{@var{h}*60*60 + @var{m}*60 +
858 @node Time Extraction, Date Construction, Time Construction, Time & Date
859 @subsubsection Functions that Examine Times
860 @cindex extraction, of time
861 @cindex time examination
862 @cindex examination, of times
863 @cindex time, lengths of
865 These functions take numeric arguments in PSPP time format and
866 give numeric results.
869 @cindex time, in days
870 @deftypefn {Function} {} CTIME.DAYS (@var{time})
871 Results in the number of days and fractional days in @var{time}.
872 (@code{CTIME.DAYS(@var{x})} is equivalent to @code{@var{x}/60/60/24}.)
876 @cindex time, in hours
877 @deftypefn {Function} {} CTIME.HOURS (@var{time})
878 Results in the number of hours and fractional hours in @var{time}.
879 (@code{CTIME.HOURS(@var{x})} is equivalent to @code{@var{x}/60/60}.)
883 @cindex time, in minutes
884 @deftypefn {Function} {} CTIME.MINUTES (@var{time})
885 Results in the number of minutes and fractional minutes in @var{time}.
886 (@code{CTIME.MINUTES(@var{x})} is equivalent to @code{@var{x}/60}.)
890 @cindex time, in seconds
891 @deftypefn {Function} {} CTIME.SECONDS (@var{time})
892 Results in the number of seconds and fractional seconds in @var{time}.
893 (@code{CTIME.SECONDS} does nothing; @code{CTIME.SECONDS(@var{x})} is
894 equivalent to @code{@var{x}}.)
897 @node Date Construction, Date Extraction, Time Extraction, Time & Date
898 @subsubsection Functions that Produce Dates
899 @cindex dates, constructing
900 @cindex constructing dates
902 @cindex arguments, of date construction functions
903 These functions take numeric arguments and give numeric results in the
904 PSPP date format. Arguments taken by these functions are:
908 Refers to a day of the month between 1 and 31.
911 Refers to a month of the year between 1 and 12.
914 Refers to a quarter of the year between 1 and 4. The quarters of the
915 year begin on the first days of months 1, 4, 7, and 10.
918 Refers to a week of the year between 1 and 53.
921 Refers to a day of the year between 1 and 366.
924 Refers to a year between 1582 and 19999.
927 @cindex arguments, invalid
928 If these functions' arguments are out-of-range, they are correctly
929 normalized before conversion to date format. Non-integers are rounded
932 @cindex day-month-year
933 @cindex dates, day-month-year
934 @deftypefn {Function} {} DATE.DMY (@var{day}, @var{month}, @var{year})
935 @deftypefnx {Function} {} DATE.MDY (@var{month}, @var{day}, @var{year})
936 Results in a date value corresponding to the midnight before day
937 @var{day} of month @var{month} of year @var{year}.
941 @cindex dates, month-year
942 @deftypefn {Function} {} DATE.MOYR (@var{month}, @var{year})
943 Results in a date value corresponding to the midnight before the first
944 day of month @var{month} of year @var{year}.
948 @cindex dates, quarter-year
949 @deftypefn {Function} {} DATE.QYR (@var{quarter}, @var{year})
950 Results in a date value corresponding to the midnight before the first
951 day of quarter @var{quarter} of year @var{year}.
955 @cindex dates, week-year
956 @deftypefn {Function} {} DATE.WKYR (@var{week}, @var{year})
957 Results in a date value corresponding to the midnight before the first
958 day of week @var{week} of year @var{year}.
962 @cindex dates, year-day
963 @deftypefn {Function} {} DATE.YRDAY (@var{year}, @var{yday})
964 Results in a date value corresponding to the midnight before day
965 @var{yday} of year @var{year}.
968 @node Date Extraction, , Date Construction, Time & Date
969 @subsubsection Functions that Examine Dates
970 @cindex extraction, of dates
971 @cindex date examination
973 @cindex arguments, of date extraction functions
974 These functions take numeric arguments in PSPP date or time
975 format and give numeric results. These names are used for arguments:
979 A numeric value in PSPP date format.
982 A numeric value in PSPP time format.
985 A numeric value in PSPP time or date format.
989 @cindex dates, in days
990 @cindex time, in days
991 @deftypefn {Function} {} XDATE.DATE (@var{time-or-date})
992 For a time, results in the time corresponding to the number of whole
993 days @var{date-or-time} includes. For a date, results in the date
994 corresponding to the latest midnight at or before @var{date-or-time};
995 that is, gives the date that @var{date-or-time} is in.
996 (XDATE.DATE(@var{x}) is equivalent to TRUNC(@var{x}/86400)*86400.)
997 Applying this function to a time is a non-portable feature.
1001 @cindex dates, in hours
1002 @cindex time, in hours
1003 @deftypefn {Function} {} XDATE.HOUR (@var{time-or-date})
1004 For a time, results in the number of whole hours beyond the number of
1005 whole days represented by @var{date-or-time}. For a date, results in
1006 the hour (as an integer between 0 and 23) corresponding to
1007 @var{date-or-time}. (XDATE.HOUR(@var{x}) is equivalent to
1008 MOD(TRUNC(@var{x}/3600),24)) Applying this function to a time is a
1009 non-portable feature.
1012 @cindex day of the year
1013 @cindex dates, day of the year
1014 @deftypefn {Function} {} XDATE.JDAY (@var{date})
1015 Results in the day of the year (as an integer between 1 and 366)
1016 corresponding to @var{date}.
1019 @cindex day of the month
1020 @cindex dates, day of the month
1021 @deftypefn {Function} {} XDATE.MDAY (@var{date})
1022 Results in the day of the month (as an integer between 1 and 31)
1023 corresponding to @var{date}.
1027 @cindex dates, in minutes
1028 @cindex time, in minutes
1029 @deftypefn {Function} {} XDATE.MINUTE (@var{time-or-date})
1030 Results in the number of minutes (as an integer between 0 and 59) after
1031 the last hour in @var{time-or-date}. (XDATE.MINUTE(@var{x}) is
1032 equivalent to MOD(TRUNC(@var{x}/60),60)) Applying this function to a
1033 time is a non-portable feature.
1037 @cindex dates, in months
1038 @deftypefn {Function} {} XDATE.MONTH (@var{date})
1039 Results in the month of the year (as an integer between 1 and 12)
1040 corresponding to @var{date}.
1044 @cindex dates, in quarters
1045 @deftypefn {Function} {} XDATE.QUARTER (@var{date})
1046 Results in the quarter of the year (as an integer between 1 and 4)
1047 corresponding to @var{date}.
1051 @cindex dates, in seconds
1052 @cindex time, in seconds
1053 @deftypefn {Function} {} XDATE.SECOND (@var{time-or-date})
1054 Results in the number of whole seconds after the last whole minute (as
1055 an integer between 0 and 59) in @var{time-or-date}.
1056 (XDATE.SECOND(@var{x}) is equivalent to MOD(@var{x}, 60).) Applying
1057 this function to a time is a non-portable feature.
1061 @cindex times, in days
1062 @deftypefn {Function} {} XDATE.TDAY (@var{time})
1063 Results in the number of whole days (as an integer) in @var{time}.
1064 (XDATE.TDAY(@var{x}) is equivalent to TRUNC(@var{x}/86400).)
1068 @cindex dates, time of day
1069 @deftypefn {Function} {} XDATE.TIME (@var{date})
1070 Results in the time of day at the instant corresponding to @var{date},
1071 in PSPP time format. This is the number of seconds since
1072 midnight on the day corresponding to @var{date}. (XDATE.TIME(@var{x}) is
1073 equivalent to TRUNC(@var{x}/86400)*86400.)
1077 @cindex dates, in weeks
1078 @deftypefn {Function} {} XDATE.WEEK (@var{date})
1079 Results in the week of the year (as an integer between 1 and 53)
1080 corresponding to @var{date}.
1083 @cindex day of the week
1085 @cindex dates, day of the week
1086 @cindex dates, in weekdays
1087 @deftypefn {Function} {} XDATE.WKDAY (@var{date})
1088 Results in the day of week (as an integer between 1 and 7) corresponding
1089 to @var{date}. The days of the week are:
1110 @cindex dates, in years
1111 @deftypefn {Function} {} XDATE.YEAR (@var{date})
1112 Returns the year (as an integer between 1582 and 19999) corresponding to
1116 @node Miscellaneous Functions, Functions Not Implemented, Time & Date, Functions
1117 @subsection Miscellaneous Functions
1118 @cindex functions, miscellaneous
1120 Miscellaneous functions take various arguments and produce various
1123 @cindex cross-case function
1124 @cindex function, cross-case
1125 @deftypefn {Function} {} LAG (@var{variable})
1127 @var{variable} must be a numeric or string variable name. @code{LAG}
1128 results in the value of that variable for the case before the current
1129 one. In case-selection procedures, @code{LAG} results in the value of
1130 the variable for the last case selected. Results in system-missing (for
1131 numeric variables) or blanks (for string variables) for the first case
1132 or before any cases are selected.
1135 @deftypefn {Function} {} LAG (@var{variable}, @var{ncases})
1136 @var{variable} must be a numeric or string variable name. @var{ncases}
1137 must be a small positive constant integer, although there is no explicit
1138 limit. (Use of a large value for @var{ncases} will increase memory
1139 consumption, since PSPP must keep @var{ncases} cases in memory.)
1140 @code{LAG (@var{variable}, @var{ncases}} results in the value of
1141 @var{variable} that is @var{ncases} before the case currently being
1142 processed. See @code{LAG (@var{variable})} above for more details.
1145 @cindex date, Julian
1147 @deftypefn {Function} {} YRMODA (@var{year}, @var{month}, @var{day})
1148 @var{year} is a year between 0 and 199 or 1582 and 19999. @var{month} is
1149 a month between 1 and 12. @var{day} is a day between 1 and 31. If
1150 @var{month} or @var{day} is out-of-range, it changes the next higher
1151 unit. For instance, a @var{day} of 0 refers to the last day of the
1152 previous month, and a @var{month} of 13 refers to the first month of the
1153 next year. @var{year} must be in range. If @var{year} is between 0 and
1154 199, 1900 is added. @var{year}, @var{month}, and @var{day} must all be
1157 @code{YRMODA} results in the number of days between 15 Oct 1582 and
1158 the date specified, plus one. The date passed to @code{YRMODA} must be
1159 on or after 15 Oct 1582. 15 Oct 1582 has a value of 1.
1162 @node Functions Not Implemented, , Miscellaneous Functions, Functions
1163 @subsection Functions Not Implemented
1164 @cindex functions, not implemented
1165 @cindex not implemented
1166 @cindex features, not implemented
1168 These functions are not yet implemented and thus not yet documented,
1169 since it's a hassle.
1193 @node Order of Operations, , Functions, Expressions
1194 @section Operator Precedence
1195 @cindex operator precedence
1196 @cindex precedence, operator
1197 @cindex order of operations
1198 @cindex operations, order of
1200 The following table describes operator precedence. Smaller-numbered
1201 levels in the table have higher precedence. Within a level, operations
1202 are performed from left to right, except for level 2 (exponentiation),
1203 where operations are performed from right to left. If an operator
1204 appears in the table in two places (@code{-}), the first occurrence is
1205 unary, the second is binary.
1219 @code{EQ GE GT LE LT NE}
1223 @setfilename ignored