Split pspp.texi into one texi file per chapter
[pspp-builds.git] / doc / expressions.texi
1 @node Expressions, Data Input and Output, Language, Top
2 @chapter Mathematical Expressions
3 @cindex expressions, mathematical
4 @cindex mathematical expressions
5
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.
11
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.
18
19 @menu
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.
28 @end menu
29
30 @node Boolean Values, Missing Values in Expressions, Expressions, Expressions
31 @section Boolean Values
32 @cindex Boolean
33 @cindex values, Boolean
34
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
39 value is unknown.
40
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.
44
45 Strings and Booleans are not compatible, and neither may be used in
46 place of the other.
47
48 @node Missing Values in Expressions, Grouping Operators, Boolean Values, Expressions
49 @section Missing Values in Expressions
50
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
54 descriptions.
55
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.
59
60 The missing-value functions can be used to precisely control how missing
61 values are treated in expressions.  @xref{Missing Value Functions}, for
62 more details.
63
64 @node Grouping Operators, Arithmetic Operators, Missing Values in Expressions, Expressions
65 @section Grouping Operators
66 @cindex parentheses
67 @cindex @samp{(  )}
68 @cindex grouping operators
69 @cindex operators, grouping
70
71 Parentheses (@samp{()}) are the grouping operators.  Surround an
72 expression with parentheses to force early evaluation.
73
74 Parentheses also surround the arguments to functions, but in that
75 situation they act as punctuators, not as operators.
76
77 @node Arithmetic Operators, Logical Operators, Grouping Operators, Expressions
78 @section Arithmetic Operators
79 @cindex operators, arithmetic
80 @cindex arithmetic operators
81
82 The arithmetic operators take numeric arguments and produce numeric
83 results.
84
85 @table @code
86 @cindex @samp{+}
87 @cindex addition
88 @item @var{a} + @var{b}
89 Adds @var{a} and @var{b}, returning the sum.
90
91 @cindex @samp{-}
92 @cindex subtraction
93 @item @var{a} - @var{b}
94 Subtracts @var{b} from @var{a}, returning the difference.
95
96 @cindex @samp{*}
97 @cindex multiplication
98 @item @var{a} * @var{b}
99 Multiplies @var{a} and @var{b}, returning the product.
100
101 @cindex @samp{/}
102 @cindex division
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.
106
107 @cindex @samp{**}
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.
113
114 @cindex @samp{-}
115 @cindex negation
116 @item - @var{a}
117 Reverses the sign of @var{a}.  
118 @end table
119
120 @node Logical Operators, Relational Operators, Arithmetic Operators, Expressions
121 @section Logical Operators
122 @cindex logical operators
123 @cindex operators, logical
124
125 @cindex true
126 @cindex false
127 @cindex Boolean
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.
134
135 @table @code
136 @cindex @code{AND}
137 @cindex @samp{&}
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.
145
146 @cindex @code{OR}
147 @cindex @samp{|}
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.
155
156 @cindex @code{NOT}
157 @cindex @samp{~}
158 @cindex inversion, logical
159 @cindex logical inversion
160 @item NOT @var{a}
161 @itemx ~ @var{a}
162 True if @var{a} is false.  If the argument is missing, then the result
163 is missing.
164 @end table
165
166 @node Relational Operators, Functions, Logical Operators, Expressions
167 @section Relational Operators
168
169 The relational operators take numeric or string arguments and produce Boolean
170 results.
171
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.
175
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.
179
180 @table @code
181 @cindex equality, testing
182 @cindex testing for equality
183 @cindex @code{EQ}
184 @cindex @samp{=}
185 @item @var{a} EQ @var{b}
186 @itemx @var{a} = @var{b}
187 True if @var{a} is equal to @var{b}.
188
189 @cindex less than or equal to
190 @cindex @code{LE}
191 @cindex @code{<=}
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}.
195
196 @cindex less than
197 @cindex @code{LT}
198 @cindex @code{<}
199 @item @var{a} LT @var{b}
200 @itemx @var{a} < @var{b}
201 True if @var{a} is less than @var{b}.
202
203 @cindex greater than or equal to
204 @cindex @code{GE}
205 @cindex @code{>=}
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}.
209
210 @cindex greater than
211 @cindex @code{GT}
212 @cindex @samp{>}
213 @item @var{a} GT @var{b}
214 @itemx @var{a} > @var{b}
215 True if @var{a} is greater than @var{b}.
216
217 @cindex inequality, testing
218 @cindex testing for inequality
219 @cindex @code{NE}
220 @cindex @code{~=}
221 @cindex @code{<>}
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}.
226 @end table
227
228 @node Functions, Order of Operations, Relational Operators, Expressions
229 @section Functions
230 @cindex functions
231
232 @cindex mathematics
233 @cindex operators
234 @cindex parentheses
235 @cindex @code{(}
236 @cindex @code{)}
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.
246
247 The sections below describe each function in detail.
248
249 @menu
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
262 @end menu
263
264 @node Advanced Mathematics, Miscellaneous Mathematics, Functions, Functions
265 @subsection Advanced Mathematical Functions
266 @cindex mathematics, advanced
267
268 Advanced mathematical functions take numeric arguments and produce
269 numeric results.
270
271 @deftypefn {Function} {} EXP (@var{exponent})
272 Returns @i{e} (approximately 2.71828) raised to power @var{exponent}.
273 @end deftypefn
274
275 @cindex logarithms
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.
279 @end deftypefn
280
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.
284 @end deftypefn
285
286 @cindex square roots
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.
290 @end deftypefn
291
292 @node Miscellaneous Mathematics, Trigonometry, Advanced Mathematics, Functions
293 @subsection Miscellaneous Mathematical Functions
294 @cindex mathematics, miscellaneous
295
296 Miscellaneous mathematical functions take numeric arguments and produce
297 numeric results.
298
299 @cindex absolute value
300 @deftypefn {Function} {} ABS (@var{number})
301 Results in the absolute value of @var{number}.
302 @end deftypefn
303
304 @cindex modulus
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.
310 @end deftypefn
311
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.
316 @end deftypefn
317
318 @cindex rounding
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.
322 @end deftypefn
323
324 @cindex truncation
325 @deftypefn {Function} {} TRUNC (@var{number})
326 Discards the fractional part of @var{number}; that is, rounds
327 @var{number} towards zero.
328 @end deftypefn
329
330 @node Trigonometry, Missing Value Functions, Miscellaneous Mathematics, Functions
331 @subsection Trigonometric Functions
332 @cindex trigonometry
333
334 Trigonometric functions take numeric arguments and produce numeric
335 results.
336
337 @cindex arccosine
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.
342 @end deftypefn
343
344 @cindex arcsine
345 @cindex inverse sine
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.
349 @end deftypefn
350
351 @cindex arctangent
352 @cindex inverse tangent
353 @deftypefn {Function} {} ARTAN (@var{number})
354 Takes the arctangent, in radians, of @var{number}.
355 @end deftypefn
356
357 @cindex cosine
358 @deftypefn {Function} {} COS (@var{angle})
359 Takes the cosine of @var{angle} which should be in radians.
360 @end deftypefn
361
362 @cindex sine
363 @deftypefn {Function} {} SIN (@var{angle})
364 Takes the sine of @var{angle} which should be in radians.
365 @end deftypefn
366
367 @cindex tangent
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.
372 Portability: none.
373 @end deftypefn
374
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
380
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.
386
387 @deftypefn {Function} {} MISSING (@var{expr})
388 Returns 1 if @var{expr} has the system-missing value, 0 otherwise.
389 @end deftypefn
390
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.
396 @end deftypefn
397
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.
403 @end deftypefn
404
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.
410 @end deftypefn
411
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.
417 @end deftypefn
418
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)
423
424 Pseudo-random number generation functions take numeric arguments and
425 produce numeric results.
426
427 PSPP uses the alleged RC4 cipher as a pseudo-random number generator
428 (PRNG).  The bytes output by this PRNG are system-independent for a
429 given random seed, but differences in endianness and floating-point
430 formats will make PRNG results differ from system to system.  RC4
431 should produce high-quality random numbers for simulation purposes.
432 (If you're concerned about the quality of the random number generator,
433 well, you're using a statistical processing package---analyze it!)
434
435 PSPP's implementation of RC4 has not undergone any security auditing.
436 Furthermore, various precautions that would be necessary for secure
437 operation, such as secure seeding and discarding the first several
438 bytes of output, have not been taken.  Therefore, PSPP's
439 implementation of RC4 should not be used for security purposes.
440
441 @cindex random numbers, normally-distributed
442 @deftypefn {Function} {} NORMAL (@var{number})
443 Results in a random number.  Results from @code{NORMAL} are normally
444 distributed with a mean of 0 and a standard deviation of @var{number}.
445 @end deftypefn
446
447 @cindex random numbers, uniformly-distributed
448 @deftypefn {Function} {} UNIFORM (@var{number})
449 Results in a random number between 0 and @var{number}.  Results from
450 @code{UNIFORM} are evenly distributed across its entire range.  There
451 may be a maximum on the largest random number ever generated---this is
452 often 
453 @ifinfo 
454 2**31-1 
455 @end ifinfo
456 @tex
457 $2^{31}-1$
458 @end tex
459 (2,147,483,647), but it may be orders of magnitude
460 higher or lower.
461 @end deftypefn
462
463 @node Set Membership, Statistical Functions, Pseudo-Random Numbers, Functions
464 @subsection Set-Membership Functions
465 @cindex set membership
466 @cindex membership, of set
467
468 Set membership functions determine whether a value is a member of a set.
469 They take a set of numeric arguments or a set of string arguments, and
470 produce Boolean results.
471
472 String comparisons are performed according to the rules given in
473 @ref{Relational Operators}.
474
475 @deftypefn {Function} {} ANY (@var{value}, @var{set} [, @var{set}]@dots{})
476 Results in true if @var{value} is equal to any of the @var{set}
477 values.  Otherwise, results in false.  If @var{value} is
478 system-missing, returns system-missing.  System-missing values in
479 @var{set} do not cause ANY to return system-missing.
480 @end deftypefn
481
482 @deftypefn {Function} {} RANGE (@var{value}, @var{low}, @var{high} [, @var{low}, @var{high}]@dots{})
483 Results in true if @var{value} is in any of the intervals bounded by
484 @var{low} and @var{high} inclusive.  Otherwise, results in false.
485 Each @var{low} must be less than or equal to its corresponding
486 @var{high} value.  @var{low} and @var{high} must be given in pairs.
487 If @var{value} is system-missing, returns system-missing.
488 System-missing values in @var{set} do not cause RANGE to return
489 system-missing.
490 @end deftypefn
491
492 @node Statistical Functions, String Functions, Set Membership, Functions
493 @subsection Statistical Functions
494 @cindex functions, statistical
495 @cindex statistics
496
497 Statistical functions compute descriptive statistics on a list of
498 values.  Some statistics can be computed on numeric or string values;
499 other can only be computed on numeric values.  Their results have the
500 same type as their arguments.  The current case's weighting factor
501 (@pxref{WEIGHT}) has no effect on statistical functions.
502
503 @cindex arguments, minimum valid
504 @cindex minimum valid number of arguments
505 With statistical functions it is possible to specify a minimum number of
506 non-missing arguments for the function to be evaluated.  To do so,
507 append a dot and the number to the function name.  For instance, to
508 specify a minimum of three valid arguments to the MEAN function, use the
509 name @code{MEAN.3}.
510
511 @cindex coefficient of variation
512 @cindex variation, coefficient of
513 @deftypefn {Function} {} CFVAR (@var{number}, @var{number}[, @dots{}])
514 Results in the coefficient of variation of the values of @var{number}.
515 This function requires at least two valid arguments to give a
516 non-missing result.  (The coefficient of variation is the standard
517 deviation divided by the mean.)
518 @end deftypefn
519
520 @cindex maximum
521 @deftypefn {Function} {} MAX (@var{value}, @var{value}[, @dots{}])
522 Results in the value of the greatest @var{value}.  The @var{value}s may
523 be numeric or string.  Although at least two arguments must be given,
524 only one need be valid for MAX to give a non-missing result.
525 @end deftypefn
526
527 @cindex mean
528 @deftypefn {Function} {} MEAN (@var{number}, @var{number}[, @dots{}])
529 Results in the mean of the values of @var{number}.  Although at least
530 two arguments must be given, only one need be valid for MEAN to give a
531 non-missing result.
532 @end deftypefn
533
534 @cindex minimum
535 @deftypefn {Function} {} MIN (@var{number}, @var{number}[, @dots{}])
536 Results in the value of the least @var{value}.  The @var{value}s may
537 be numeric or string.  Although at least two arguments must be given,
538 only one need be valid for MAX to give a non-missing result.
539 @end deftypefn
540
541 @cindex standard deviation
542 @cindex deviation, standard
543 @deftypefn {Function} {} SD (@var{number}, @var{number}[, @dots{}])
544 Results in the standard deviation of the values of @var{number}.
545 This function requires at least two valid arguments to give a
546 non-missing result.
547 @end deftypefn
548
549 @cindex sum
550 @deftypefn {Function} {} SUM (@var{number}, @var{number}[, @dots{}])
551 Results in the sum of the values of @var{number}.  Although at least two
552 arguments must be given, only one need by valid for SUM to give a
553 non-missing result.
554 @end deftypefn
555
556 @cindex variance
557 @deftypefn {Function} {} VARIANCE (@var{number}, @var{number}[, @dots{}])
558 Results in the variance of the values of @var{number}.  This function
559 requires at least two valid arguments to give a non-missing result.
560 @end deftypefn
561
562 @node String Functions, Time & Date, Statistical Functions, Functions
563 @subsection String Functions
564 @cindex functions, string
565 @cindex string functions
566
567 String functions take various arguments and return various results.
568
569 @cindex concatenation
570 @cindex strings, concatenation of
571 @deftypefn {Function} {} CONCAT (@var{string}, @var{string}[, @dots{}])
572 Returns a string consisting of each @var{string} in sequence.
573 @code{CONCAT("abc", "def", "ghi")} has a value of @code{"abcdefghi"}.
574 The resultant string is truncated to a maximum of 255 characters.
575 @end deftypefn
576
577 @cindex searching strings
578 @deftypefn {Function} {} INDEX (@var{haystack}, @var{needle})
579 Returns a positive integer indicating the position of the first
580 occurrence @var{needle} in @var{haystack}.  Returns 0 if @var{haystack}
581 does not contain @var{needle}.  Returns system-missing if @var{needle}
582 is an empty string.
583 @end deftypefn
584
585 @deftypefn {Function} {} INDEX (@var{haystack}, @var{needle}, @var{divisor})
586 Divides @var{needle} into parts, each with length @var{divisor}.
587 Searches @var{haystack} for the first occurrence of each part, and
588 returns the smallest value.  Returns 0 if @var{haystack} does not
589 contain any part in @var{needle}.  It is an error if @var{divisor}
590 cannot be evenly divided into the length of @var{needle}.  Returns
591 system-missing if @var{needle} is an empty string.
592 @end deftypefn
593
594 @cindex strings, finding length of
595 @deftypefn {Function} {} LENGTH (@var{string})
596 Returns the number of characters in @var{string}.
597 @end deftypefn
598
599 @cindex strings, case of
600 @deftypefn {Function} {} LOWER (@var{string})
601 Returns a string identical to @var{string} except that all uppercase
602 letters are changed to lowercase letters.  The definitions of
603 ``uppercase'' and ``lowercase'' are system-dependent.
604 @end deftypefn
605
606 @cindex strings, padding
607 @deftypefn {Function} {} LPAD (@var{string}, @var{length})
608 If @var{string} is at least @var{length} characters in length, returns
609 @var{string} unchanged.  Otherwise, returns @var{string} padded with
610 spaces on the left side to length @var{length}.  Returns an empty string
611 if @var{length} is system-missing, negative, or greater than 255.
612 @end deftypefn
613
614 @deftypefn {Function} {} LPAD (@var{string}, @var{length}, @var{padding})
615 If @var{string} is at least @var{length} characters in length, returns
616 @var{string} unchanged.  Otherwise, returns @var{string} padded with
617 @var{padding} on the left side to length @var{length}.  Returns an empty
618 string if @var{length} is system-missing, negative, or greater than 255, or
619 if @var{padding} does not contain exactly one character.
620 @end deftypefn
621
622 @cindex strings, trimming
623 @cindex whitespace, trimming
624 @deftypefn {Function} {} LTRIM (@var{string})
625 Returns @var{string}, after removing leading spaces.  Other whitespace,
626 such as tabs, carriage returns, line feeds, and vertical tabs, is not
627 removed.
628 @end deftypefn
629
630 @deftypefn {Function} {} LTRIM (@var{string}, @var{padding})
631 Returns @var{string}, after removing leading @var{padding} characters.
632 If @var{padding} does not contain exactly one character, returns an
633 empty string.
634 @end deftypefn
635
636 @cindex numbers, converting from strings
637 @cindex strings, converting to numbers
638 @deftypefn {Function} {} NUMBER (@var{string}, @var{format})
639 Returns the number produced when @var{string} is interpreted according
640 to format specifier @var{format}.  If the format width @var{w} is less
641 than the length of @var{string}, then only the first @var{w}
642 characters in @var{string} are used, e.g.@: @code{NUMBER("123", F3.0)}
643 and @code{NUMBER("1234", F3.0)} both have value 123.  If @var{w} is
644 greater than @var{string}'s length, then it is treated as if it were
645 right-padded with spaces.  If @var{string} is not in the correct
646 format for @var{format}, system-missing is returned.
647 @end deftypefn
648
649 @cindex strings, searching backwards
650 @deftypefn {Function} {} RINDEX (@var{string}, @var{format})
651 Returns a positive integer indicating the position of the last
652 occurrence of @var{needle} in @var{haystack}.  Returns 0 if
653 @var{haystack} does not contain @var{needle}.  Returns system-missing if
654 @var{needle} is an empty string.
655 @end deftypefn
656
657 @deftypefn {Function} {} RINDEX (@var{haystack}, @var{needle}, @var{divisor})
658 Divides @var{needle} into parts, each with length @var{divisor}.
659 Searches @var{haystack} for the last occurrence of each part, and
660 returns the largest value.  Returns 0 if @var{haystack} does not contain
661 any part in @var{needle}.  It is an error if @var{divisor} cannot be
662 evenly divided into the length of @var{needle}.  Returns system-missing
663 if @var{needle} is an empty string.
664 @end deftypefn
665
666 @cindex padding strings
667 @cindex strings, padding
668 @deftypefn {Function} {} RPAD (@var{string}, @var{length})
669 If @var{string} is at least @var{length} characters in length, returns
670 @var{string} unchanged.  Otherwise, returns @var{string} padded with
671 spaces on the right to length @var{length}.  Returns an empty string if
672 @var{length} is system-missing, negative, or greater than 255.
673 @end deftypefn
674
675 @deftypefn {Function} {} RPAD (@var{string}, @var{length}, @var{padding})
676 If @var{string} is at least @var{length} characters in length, returns
677 @var{string} unchanged.  Otherwise, returns @var{string} padded with
678 @var{padding} on the right to length @var{length}.  Returns an empty
679 string if @var{length} is system-missing, negative, or greater than 255,
680 or if @var{padding} does not contain exactly one character.
681 @end deftypefn
682
683 @cindex strings, trimming
684 @cindex whitespace, trimming
685 @deftypefn {Function} {} RTRIM (@var{string})
686 Returns @var{string}, after removing trailing spaces.  Other types of
687 whitespace are not removed.
688 @end deftypefn
689
690 @deftypefn {Function} {} RTRIM (@var{string}, @var{padding})
691 Returns @var{string}, after removing trailing @var{padding} characters.
692 If @var{padding} does not contain exactly one character, returns an
693 empty string.
694 @end deftypefn
695
696 @cindex strings, converting from numbers
697 @cindex numbers, converting to strings
698 @deftypefn {Function} {} STRING (@var{number}, @var{format})
699 Returns a string corresponding to @var{number} in the format given by
700 format specifier @var{format}.  For example, @code{STRING(123.56, F5.1)}
701 has the value @code{"123.6"}.
702 @end deftypefn
703
704 @cindex substrings
705 @cindex strings, taking substrings of
706 @deftypefn {Function} {} SUBSTR (@var{string}, @var{start})
707 Returns a string consisting of the value of @var{string} from position
708 @var{start} onward.  Returns an empty string if @var{start} is system-missing
709 or has a value less than 1 or greater than the number of characters in
710 @var{string}.
711 @end deftypefn
712
713 @deftypefn {Function} {} SUBSTR (@var{string}, @var{start}, @var{count})
714 Returns a string consisting of the first @var{count} characters from
715 @var{string} beginning at position @var{start}.  Returns an empty string
716 if @var{start} or @var{count} is system-missing, if @var{start} is less
717 than 1 or greater than the number of characters in @var{string}, or if
718 @var{count} is less than 1.  Returns a string shorter than @var{count}
719 characters if @var{start} + @var{count} - 1 is greater than the number
720 of characters in @var{string}.  Examples: @code{SUBSTR("abcdefg", 3, 2)}
721 has value @code{"cd"}; @code{SUBSTR("Ben Pfaff", 5, 10)} has the value
722 @code{"Pfaff"}.
723 @end deftypefn
724
725 @cindex case conversion
726 @cindex strings, case of
727 @deftypefn {Function} {} UPCASE (@var{string})
728 Returns @var{string}, changing lowercase letters to uppercase letters.
729 @end deftypefn
730
731 @node Time & Date, Miscellaneous Functions, String Functions, Functions
732 @subsection Time & Date Functions
733 @cindex functions, time & date
734 @cindex times
735 @cindex dates
736
737 @cindex dates, legal range of
738 The legal range of dates for use in PSPP is 15 Oct 1582
739 through 31 Dec 19999.
740
741 @cindex arguments, invalid
742 @cindex invalid arguments
743 @quotation
744 @strong{Please note:} Most time & date extraction functions will accept
745 invalid arguments:
746
747 @itemize @bullet
748 @item
749 Negative numbers in PSPP time format.
750 @item
751 Numbers less than 86,400 in PSPP date format.
752 @end itemize
753
754 However, sensible results are not guaranteed for these invalid values.
755 The given equivalents for these functions are definitely not guaranteed
756 for invalid values.
757 @end quotation
758
759 @quotation
760 @strong{Please note also:} The time & date construction
761 functions @strong{do} produce reasonable and useful results for
762 out-of-range values; these are not considered invalid.
763 @end quotation
764
765 @menu
766 * Time & Date Concepts::        How times & dates are defined and represented
767 * Time Construction::           TIME.@{DAYS HMS@}
768 * Time Extraction::             CTIME.@{DAYS HOURS MINUTES SECONDS@}
769 * Date Construction::           DATE.@{DMY MDY MOYR QYR WKYR YRDAY@}
770 * Date Extraction::             XDATE.@{DATE HOUR JDAY MDAY MINUTE MONTH
771                                        QUARTER SECOND TDAY TIME WEEK
772                                        WKDAY YEAR@}
773 @end menu
774
775 @node Time & Date Concepts, Time Construction, Time & Date, Time & Date
776 @subsubsection How times & dates are defined and represented
777
778 @cindex time, concepts
779 @cindex time, intervals
780 Times and dates are handled by PSPP as single numbers.  A
781 @dfn{time} is an interval.  PSPP measures times in seconds.
782 Thus, the following intervals correspond with the numeric values given:
783                 
784 @example
785           10 minutes                        600
786           1 hour                          3,600
787           1 day, 3 hours, 10 seconds     97,210
788           40 days                     3,456,000
789           10010 d, 14 min, 24 s     864,864,864
790 @end example
791
792 @cindex dates, concepts
793 @cindex time, instants of
794 A @dfn{date}, on the other hand, is a particular instant in the past or
795 the future.  PSPP represents a date as a number of seconds after the
796 midnight that separated 8 Oct 1582 and 9 Oct 1582.  (Please note that 15
797 Oct 1582 immediately followed 9 Oct 1582.)  Thus, the midnights before
798 the dates given below correspond with the numeric PSPP dates given:
799
800 @example
801               15 Oct 1582                86,400
802                4 Jul 1776         6,113,318,400
803                1 Jan 1900        10,010,390,400
804                1 Oct 1978        12,495,427,200
805               24 Aug 1995        13,028,601,600
806 @end example
807
808 @cindex time, mathematical properties of
809 @cindex mathematics, applied to times & dates
810 @cindex dates, mathematical properties of
811 @noindent
812 Please note: 
813
814 @itemize @bullet
815 @item
816 A time may be added to, or subtracted from, a date, resulting in a date.
817
818 @item
819 The difference of two dates may be taken, resulting in a time.  
820
821 @item 
822 Two times may be added to, or subtracted from, each other, resulting in
823 a time.
824 @end itemize
825
826 (Adding two dates does not produce a useful result.)
827
828 Since times and dates are merely numbers, the ordinary addition and
829 subtraction operators are employed for these purposes.
830
831 @quotation
832 @strong{Please note:} Many dates and times have extremely large
833 values---just look at the values above.  Thus, it is not a good idea to
834 take powers of these values; also, the accuracy of some procedures may
835 be affected.  If necessary, convert times or dates in seconds to some
836 other unit, like days or years, before performing analysis.
837 @end quotation
838
839 @node Time Construction, Time Extraction, Time & Date Concepts, Time & Date
840 @subsubsection Functions that Produce Times
841 @cindex times, constructing
842 @cindex constructing times
843
844 These functions take numeric arguments and produce numeric results in
845 PSPP time format.
846
847 @cindex days
848 @cindex time, in days
849 @deftypefn {Function} {} TIME.DAYS (@var{ndays})
850 Results in a time value corresponding to @var{ndays} days.
851 (@code{TIME.DAYS(@var{x})} is equivalent to @code{@var{x} * 60 * 60 *
852 24}.)
853 @end deftypefn
854
855 @cindex hours-minutes-seconds
856 @cindex time, in hours-minutes-seconds
857 @deftypefn {Function} {} TIME.HMS (@var{nhours}, @var{nmins}, @var{nsecs})
858 Results in a time value corresponding to @var{nhours} hours, @var{nmins}
859 minutes, and @var{nsecs} seconds.  (@code{TIME.HMS(@var{h}, @var{m},
860 @var{s})} is equivalent to @code{@var{h}*60*60 + @var{m}*60 +
861 @var{s}}.)
862 @end deftypefn
863
864 @node Time Extraction, Date Construction, Time Construction, Time & Date
865 @subsubsection Functions that Examine Times
866 @cindex extraction, of time
867 @cindex time examination
868 @cindex examination, of times
869 @cindex time, lengths of
870
871 These functions take numeric arguments in PSPP time format and
872 give numeric results.
873
874 @cindex days
875 @cindex time, in days
876 @deftypefn {Function} {} CTIME.DAYS (@var{time})
877 Results in the number of days and fractional days in @var{time}.
878 (@code{CTIME.DAYS(@var{x})} is equivalent to @code{@var{x}/60/60/24}.)
879 @end deftypefn
880
881 @cindex hours
882 @cindex time, in hours
883 @deftypefn {Function} {} CTIME.HOURS (@var{time})
884 Results in the number of hours and fractional hours in @var{time}.
885 (@code{CTIME.HOURS(@var{x})} is equivalent to @code{@var{x}/60/60}.)
886 @end deftypefn
887
888 @cindex minutes
889 @cindex time, in minutes
890 @deftypefn {Function} {} CTIME.MINUTES (@var{time})
891 Results in the number of minutes and fractional minutes in @var{time}.
892 (@code{CTIME.MINUTES(@var{x})} is equivalent to @code{@var{x}/60}.)
893 @end deftypefn
894
895 @cindex seconds
896 @cindex time, in seconds
897 @deftypefn {Function} {} CTIME.SECONDS (@var{time})
898 Results in the number of seconds and fractional seconds in @var{time}.
899 (@code{CTIME.SECONDS} does nothing; @code{CTIME.SECONDS(@var{x})} is
900 equivalent to @code{@var{x}}.)
901 @end deftypefn
902
903 @node Date Construction, Date Extraction, Time Extraction, Time & Date
904 @subsubsection Functions that Produce Dates
905 @cindex dates, constructing
906 @cindex constructing dates
907
908 @cindex arguments, of date construction functions
909 These functions take numeric arguments and give numeric results in the
910 PSPP date format.  Arguments taken by these functions are:
911
912 @table @var
913 @item day
914 Refers to a day of the month between 1 and 31.
915
916 @item month
917 Refers to a month of the year between 1 and 12.
918
919 @item quarter
920 Refers to a quarter of the year between 1 and 4.  The quarters of the
921 year begin on the first days of months 1, 4, 7, and 10.
922
923 @item week
924 Refers to a week of the year between 1 and 53.
925
926 @item yday
927 Refers to a day of the year between 1 and 366.
928
929 @item year
930 Refers to a year between 1582 and 19999.
931 @end table
932
933 @cindex arguments, invalid
934 If these functions' arguments are out-of-range, they are correctly
935 normalized before conversion to date format.  Non-integers are rounded
936 toward zero.
937
938 @cindex day-month-year
939 @cindex dates, day-month-year
940 @deftypefn {Function} {} DATE.DMY (@var{day}, @var{month}, @var{year})
941 @deftypefnx {Function} {} DATE.MDY (@var{month}, @var{day}, @var{year})
942 Results in a date value corresponding to the midnight before day
943 @var{day} of month @var{month} of year @var{year}.
944 @end deftypefn
945
946 @cindex month-year
947 @cindex dates, month-year
948 @deftypefn {Function} {} DATE.MOYR (@var{month}, @var{year})
949 Results in a date value corresponding to the midnight before the first
950 day of month @var{month} of year @var{year}.
951 @end deftypefn
952
953 @cindex quarter-year
954 @cindex dates, quarter-year
955 @deftypefn {Function} {} DATE.QYR (@var{quarter}, @var{year})
956 Results in a date value corresponding to the midnight before the first
957 day of quarter @var{quarter} of year @var{year}.
958 @end deftypefn
959
960 @cindex week-year
961 @cindex dates, week-year
962 @deftypefn {Function} {} DATE.WKYR (@var{week}, @var{year})
963 Results in a date value corresponding to the midnight before the first
964 day of week @var{week} of year @var{year}.
965 @end deftypefn
966
967 @cindex year-day
968 @cindex dates, year-day
969 @deftypefn {Function} {} DATE.YRDAY (@var{year}, @var{yday})
970 Results in a date value corresponding to the midnight before day
971 @var{yday} of year @var{year}.
972 @end deftypefn
973
974 @node Date Extraction,  , Date Construction, Time & Date
975 @subsubsection Functions that Examine Dates
976 @cindex extraction, of dates
977 @cindex date examination
978
979 @cindex arguments, of date extraction functions
980 These functions take numeric arguments in PSPP date or time
981 format and give numeric results.  These names are used for arguments:
982
983 @table @var
984 @item date
985 A numeric value in PSPP date format.
986
987 @item time
988 A numeric value in PSPP time format.
989
990 @item time-or-date
991 A numeric value in PSPP time or date format.
992 @end table
993
994 @cindex days
995 @cindex dates, in days
996 @cindex time, in days
997 @deftypefn {Function} {} XDATE.DATE (@var{time-or-date})
998 For a time, results in the time corresponding to the number of whole
999 days @var{date-or-time} includes.  For a date, results in the date
1000 corresponding to the latest midnight at or before @var{date-or-time};
1001 that is, gives the date that @var{date-or-time} is in.
1002 (XDATE.DATE(@var{x}) is equivalent to TRUNC(@var{x}/86400)*86400.)
1003 Applying this function to a time is a non-portable feature.
1004 @end deftypefn
1005
1006 @cindex hours
1007 @cindex dates, in hours
1008 @cindex time, in hours
1009 @deftypefn {Function} {} XDATE.HOUR (@var{time-or-date})
1010 For a time, results in the number of whole hours beyond the number of
1011 whole days represented by @var{date-or-time}.  For a date, results in
1012 the hour (as an integer between 0 and 23) corresponding to
1013 @var{date-or-time}.  (XDATE.HOUR(@var{x}) is equivalent to
1014 MOD(TRUNC(@var{x}/3600),24))  Applying this function to a time is a
1015 non-portable feature.
1016 @end deftypefn
1017
1018 @cindex day of the year
1019 @cindex dates, day of the year
1020 @deftypefn {Function} {} XDATE.JDAY (@var{date})
1021 Results in the day of the year (as an integer between 1 and 366)
1022 corresponding to @var{date}.
1023 @end deftypefn
1024
1025 @cindex day of the month
1026 @cindex dates, day of the month
1027 @deftypefn {Function} {} XDATE.MDAY (@var{date})
1028 Results in the day of the month (as an integer between 1 and 31)
1029 corresponding to @var{date}.
1030 @end deftypefn
1031
1032 @cindex minutes
1033 @cindex dates, in minutes
1034 @cindex time, in minutes
1035 @deftypefn {Function} {} XDATE.MINUTE (@var{time-or-date})
1036 Results in the number of minutes (as an integer between 0 and 59) after
1037 the last hour in @var{time-or-date}.  (XDATE.MINUTE(@var{x}) is
1038 equivalent to MOD(TRUNC(@var{x}/60),60)) Applying this function to a
1039 time is a non-portable feature.
1040 @end deftypefn
1041
1042 @cindex months
1043 @cindex dates, in months
1044 @deftypefn {Function} {} XDATE.MONTH (@var{date})
1045 Results in the month of the year (as an integer between 1 and 12)
1046 corresponding to @var{date}.
1047 @end deftypefn
1048
1049 @cindex quarters
1050 @cindex dates, in quarters
1051 @deftypefn {Function} {} XDATE.QUARTER (@var{date})
1052 Results in the quarter of the year (as an integer between 1 and 4)
1053 corresponding to @var{date}.
1054 @end deftypefn
1055
1056 @cindex seconds
1057 @cindex dates, in seconds
1058 @cindex time, in seconds
1059 @deftypefn {Function} {} XDATE.SECOND (@var{time-or-date})
1060 Results in the number of whole seconds after the last whole minute (as
1061 an integer between 0 and 59) in @var{time-or-date}.
1062 (XDATE.SECOND(@var{x}) is equivalent to MOD(@var{x}, 60).)  Applying
1063 this function to a time is a non-portable feature.
1064 @end deftypefn
1065
1066 @cindex days
1067 @cindex times, in days
1068 @deftypefn {Function} {} XDATE.TDAY (@var{time})
1069 Results in the number of whole days (as an integer) in @var{time}.
1070 (XDATE.TDAY(@var{x}) is equivalent to TRUNC(@var{x}/86400).)
1071 @end deftypefn
1072
1073 @cindex time
1074 @cindex dates, time of day
1075 @deftypefn {Function} {} XDATE.TIME (@var{date})
1076 Results in the time of day at the instant corresponding to @var{date},
1077 in PSPP time format.  This is the number of seconds since
1078 midnight on the day corresponding to @var{date}.  (XDATE.TIME(@var{x}) is
1079 equivalent to TRUNC(@var{x}/86400)*86400.)
1080 @end deftypefn
1081
1082 @cindex week
1083 @cindex dates, in weeks
1084 @deftypefn {Function} {} XDATE.WEEK (@var{date})
1085 Results in the week of the year (as an integer between 1 and 53)
1086 corresponding to @var{date}.
1087 @end deftypefn
1088
1089 @cindex day of the week
1090 @cindex weekday
1091 @cindex dates, day of the week
1092 @cindex dates, in weekdays
1093 @deftypefn {Function} {} XDATE.WKDAY (@var{date})
1094 Results in the day of week (as an integer between 1 and 7) corresponding
1095 to @var{date}.  The days of the week are:
1096
1097 @table @asis
1098 @item 1
1099 Sunday
1100 @item 2
1101 Monday
1102 @item 3
1103 Tuesday
1104 @item 4
1105 Wednesday
1106 @item 5
1107 Thursday
1108 @item 6
1109 Friday
1110 @item 7
1111 Saturday
1112 @end table
1113 @end deftypefn
1114
1115 @cindex years
1116 @cindex dates, in years
1117 @deftypefn {Function} {} XDATE.YEAR (@var{date})
1118 Returns the year (as an integer between 1582 and 19999) corresponding to
1119 @var{date}.
1120 @end deftypefn
1121
1122 @node Miscellaneous Functions, Functions Not Implemented, Time & Date, Functions
1123 @subsection Miscellaneous Functions
1124 @cindex functions, miscellaneous
1125
1126 Miscellaneous functions take various arguments and produce various
1127 results.
1128
1129 @cindex cross-case function
1130 @cindex function, cross-case
1131 @deftypefn {Function} {} LAG (@var{variable})
1132 @anchor{LAG}
1133 @var{variable} must be a numeric or string variable name.  @code{LAG}
1134 results in the value of that variable for the case before the current
1135 one.  In case-selection procedures, @code{LAG} results in the value of
1136 the variable for the last case selected.  Results in system-missing (for
1137 numeric variables) or blanks (for string variables) for the first case
1138 or before any cases are selected.
1139 @end deftypefn
1140
1141 @deftypefn {Function} {} LAG (@var{variable}, @var{ncases})
1142 @var{variable} must be a numeric or string variable name.  @var{ncases}
1143 must be a small positive constant integer, although there is no explicit
1144 limit.  (Use of a large value for @var{ncases} will increase memory
1145 consumption, since PSPP must keep @var{ncases} cases in memory.)
1146 @code{LAG (@var{variable}, @var{ncases}} results in the value of
1147 @var{variable} that is @var{ncases} before the case currently being
1148 processed.  See @code{LAG (@var{variable})} above for more details.
1149 @end deftypefn
1150
1151 @cindex date, Julian
1152 @cindex Julian date
1153 @deftypefn {Function} {} YRMODA (@var{year}, @var{month}, @var{day})
1154 @var{year} is a year between 0 and 199 or 1582 and 19999.  @var{month} is
1155 a month between 1 and 12.  @var{day} is a day between 1 and 31.  If
1156 @var{month} or @var{day} is out-of-range, it changes the next higher
1157 unit.  For instance, a @var{day} of 0 refers to the last day of the
1158 previous month, and a @var{month} of 13 refers to the first month of the
1159 next year.  @var{year} must be in range.  If @var{year} is between 0 and
1160 199, 1900 is added.  @var{year}, @var{month}, and @var{day} must all be
1161 integers.
1162
1163 @code{YRMODA} results in the number of days between 15 Oct 1582 and
1164 the date specified, plus one.  The date passed to @code{YRMODA} must be
1165 on or after 15 Oct 1582.  15 Oct 1582 has a value of 1.
1166 @end deftypefn
1167
1168 @node Functions Not Implemented,  , Miscellaneous Functions, Functions
1169 @subsection Functions Not Implemented
1170 @cindex functions, not implemented
1171 @cindex not implemented
1172 @cindex features, not implemented
1173
1174 These functions are not yet implemented and thus not yet documented,
1175 since it's a hassle.
1176
1177 @findex CDF.xxx
1178 @findex CDFNORM
1179 @findex IDF.xxx
1180 @findex NCDF.xxx
1181 @findex PROBIT
1182 @findex RV.xxx
1183
1184 @itemize @bullet
1185 @item
1186 @code{CDF.xxx}
1187 @item
1188 @code{CDFNORM}
1189 @item
1190 @code{IDF.xxx}
1191 @item
1192 @code{NCDF.xxx}
1193 @item
1194 @code{PROBIT}
1195 @item
1196 @code{RV.xxx}
1197 @end itemize
1198
1199 @node Order of Operations,  , Functions, Expressions
1200 @section Operator Precedence
1201 @cindex operator precedence
1202 @cindex precedence, operator
1203 @cindex order of operations
1204 @cindex operations, order of
1205
1206 The following table describes operator precedence.  Smaller-numbered
1207 levels in the table have higher precedence.  Within a level, operations
1208 are performed from left to right, except for level 2 (exponentiation),
1209 where operations are performed from right to left.  If an operator
1210 appears in the table in two places (@code{-}), the first occurrence is
1211 unary, the second is binary.
1212
1213 @enumerate
1214 @item
1215 @code{(  )}
1216 @item
1217 @code{**}
1218 @item
1219 @code{-}
1220 @item
1221 @code{*  /}
1222 @item
1223 @code{+  -}
1224 @item
1225 @code{EQ  GE  GT  LE  LT  NE}
1226 @item
1227 @code{AND  NOT  OR}
1228 @end enumerate
1229 @setfilename ignored