-@node Expressions, Data Input and Output, Language, Top
+@node Expressions
@chapter Mathematical Expressions
@cindex expressions, mathematical
@cindex mathematical expressions
full-fledged expressions in themselves.
@menu
-* Boolean Values:: Boolean values.
-* Missing Values in Expressions:: Using missing values in expressions.
-* Grouping Operators:: parentheses
-* Arithmetic Operators:: add sub mul div pow
-* Logical Operators:: AND NOT OR
-* Relational Operators:: EQ GE GT LE LT NE
-* Functions:: More-sophisticated operators.
-* Order of Operations:: Operator precedence.
+* Boolean Values:: Boolean values
+* Missing Values in Expressions:: Using missing values in expressions
+* Grouping Operators:: parentheses
+* Arithmetic Operators:: add sub mul div pow
+* Logical Operators:: AND NOT OR
+* Relational Operators:: EQ GE GT LE LT NE
+* Functions:: More-sophisticated operators
+* Order of Operations:: Operator precedence
@end menu
@node Boolean Values
* Statistical Functions:: CFVAR MAX MEAN MIN SD SUM VARIANCE
* String Functions:: CONCAT INDEX LENGTH LOWER LPAD LTRIM NUMBER
RINDEX RPAD RTRIM STRING SUBSTR UPCASE
-* Time & Date:: CTIME.xxx DATE.xxx TIME.xxx XDATE.xxx
-* Miscellaneous Functions:: LAG YRMODA
+* Time and Date:: CTIME.xxx DATE.xxx TIME.xxx XDATE.xxx
+ DATEDIFF DATESUM
+* Miscellaneous Functions:: LAG YRMODA VALUELABEL
* Statistical Distribution Functions:: PDF CDF SIG IDF RV NPDF NCDF
@end menu
@end deftypefn
@cindex strings, trimming
-@cindex whitespace, trimming
+@cindex white space, trimming
@deftypefn {Function} {} LTRIM (@var{string})
-Returns @var{string}, after removing leading spaces. Other whitespace,
+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
@end deftypefn
@cindex strings, trimming
-@cindex whitespace, trimming
+@cindex white space, trimming
@deftypefn {Function} {} RTRIM (@var{string})
Returns @var{string}, after removing trailing spaces. Other types of
-whitespace are not removed.
+white space are not removed.
@end deftypefn
@deftypefn {Function} {} RTRIM (@var{string}, @var{padding})
Returns @var{string}, changing lowercase letters to uppercase letters.
@end deftypefn
-@node Time & Date
+@node Time and Date
@subsection Time & Date Functions
@cindex functions, time & date
@cindex times
Most time and date functions will not accept earlier dates.
@menu
-* Time & Date Concepts:: How times & dates are defined and represented
+* Time and Date Concepts:: How times & dates are defined and represented
* Time Construction:: TIME.@{DAYS HMS@}
* Time Extraction:: CTIME.@{DAYS HOURS MINUTES SECONDS@}
* Date Construction:: DATE.@{DMY MDY MOYR QYR WKYR YRDAY@}
* Date Extraction:: XDATE.@{DATE HOUR JDAY MDAY MINUTE MONTH
QUARTER SECOND TDAY TIME WEEK
WKDAY YEAR@}
+* Time and Date Arithmetic:: DATEDIFF DATESUM
@end menu
-@node Time & Date Concepts
+@node Time and Date Concepts
@subsubsection How times & dates are defined and represented
@cindex time, concepts
24 Aug 1995 13,028,601,600
@end example
-@cindex time, mathematical properties of
-@cindex mathematics, applied to times & dates
-@cindex dates, mathematical properties of
-@noindent
-Ordinary arithmetic operations on dates and times often produce
-sensible results. Adding a time to, or subtracting one from, a date
-produces a new date that much earlier or later. The difference of two
-dates yields the time between those dates. Adding two times produces
-the combined time. Multiplying a time by a scalar produces a time
-that many times longer. Since times and dates are just numbers, the
-ordinary addition and subtraction operators are employed for these
-purposes.
-
-Adding two dates does not produce a useful result.
-
-As the table shows, dates and times may have very large values. Thus,
-it is not a good idea to take powers of these values; also, the
-accuracy of some procedures may be affected. If necessary, convert
-times or dates in seconds to some other unit, like days or years,
-before performing analysis.
-
@node Time Construction
@subsubsection Functions that Produce Times
@cindex times, constructing
@var{date}.
@end deftypefn
+@node Time and Date Arithmetic
+@subsubsection Time and Date Arithmetic
+
+@cindex time, mathematical properties of
+@cindex mathematics, applied to times & dates
+@cindex dates, mathematical properties of
+@noindent
+Ordinary arithmetic operations on dates and times often produce
+sensible results. Adding a time to, or subtracting one from, a date
+produces a new date that much earlier or later. The difference of two
+dates yields the time between those dates. Adding two times produces
+the combined time. Multiplying a time by a scalar produces a time
+that many times longer. Since times and dates are just numbers, the
+ordinary addition and subtraction operators are employed for these
+purposes.
+
+Adding two dates does not produce a useful result.
+
+Dates and times may have very large values. Thus,
+it is not a good idea to take powers of these values; also, the
+accuracy of some procedures may be affected. If necessary, convert
+times or dates in seconds to some other unit, like days or years,
+before performing analysis.
+
+PSPP supplies a few functions for date arithmetic:
+
+@deftypefn {Function} {} DATEDIFF (@var{date2}, @var{date1}, @var{unit})
+Returns the span of time from @var{date1} to @var{date2} in terms of
+@var{unit}, which must be a quoted string, one of @samp{years},
+@samp{quarters}, @samp{months}, @samp{weeks}, @samp{days},
+@samp{hours}, @samp{minutes}, and @samp{seconds}. The result is an
+integer, truncated toward zero.
+
+One year is considered to span from a given date to the same month,
+day, and time of day the next year. Thus, from Jan.@tie{}1 of one
+year to Jan.@tie{}1 the next year is considered to be a full year, but
+Feb.@tie{}29 of a leap year to the following Feb.@tie{}28 is not.
+Similarly, one month spans from a given day of the month to the same
+day of the following month. Thus, there is never a full month from
+Jan.@tie{}31 of a given year to any day in the following February.
+@end deftypefn
+
+@deftypefn {Function} {} DATESUM (@var{date}, @var{quantity}, @var{unit}[, @var{method}])
+Returns @var{date} advanced by the given @var{quantity} of the
+specified @var{unit}, which must be one of the strings @samp{years},
+@samp{quarters}, @samp{months}, @samp{weeks}, @samp{days},
+@samp{hours}, @samp{minutes}, and @samp{seconds}.
+
+When @var{unit} is @samp{years}, @samp{quarters}, or @samp{months},
+only the integer part of @var{quantity} is considered. Adding one of
+these units can cause the day of the month to exceed the number of
+days in the month. In this case, the @var{method} comes into
+play: if it is omitted or specified as @samp{closest} (as a quoted
+string), then the resulting day is the last day of the month;
+otherwise, if it is specified as @samp{rollover}, then the extra days
+roll over into the following month.
+
+When @var{unit} is @samp{weeks}, @samp{days}, @samp{hours},
+@samp{minutes}, or @samp{seconds}, the @var{quantity} is not rounded
+to an integer and @var{method}, if specified, is ignored.
+@end deftypefn
+
@node Miscellaneous Functions
@subsection Miscellaneous Functions
@cindex functions, miscellaneous
-Miscellaneous functions take various arguments and produce various
-results.
-
@cindex cross-case function
@cindex function, cross-case
-@deftypefn {Function} {} LAG (@var{variable}[, @var{ncases}])
+@deftypefn {Function} {} LAG (@var{variable}[, @var{n}])
@anchor{LAG}
+
@var{variable} must be a numeric or string variable name. @code{LAG}
-results in the value of that variable for the case @var{ncases} before
-the current one. In case-selection procedures, @code{LAG} results in
-the value of the variable for the last case selected. Results in
-system-missing (for numeric variables) or blanks (for string
-variables) for the first case or before any cases are selected.
+yields the value of that variable for the case @var{n} before the
+current one. Results in system-missing (for numeric variables) or
+blanks (for string variables) for the first @var{n} cases.
+
+@code{LAG} obtains values from the cases that become the new active file
+after a procedure executes. Thus, @code{LAG} will not return values
+from cases dropped by transformations such as @cmd{SELECT IF}, and
+transformations like @cmd{COMPUTE} that modify data will change the
+values returned by @code{LAG}. These are both the case whether these
+transformations precede or follow the use of @code{LAG}.
+
+If @code{LAG} is used before @cmd{TEMPORARY}, then the values it returns
+are those in cases just before @cmd{TEMPORARY}. @code{LAG} may not be
+used after @cmd{TEMPORARY}.
If omitted, @var{ncases} defaults to 1. Otherwise, @var{ncases} must
be a small positive constant integer. There is no explicit limit, but
on or after 15 Oct 1582. 15 Oct 1582 has a value of 1.
@end deftypefn
+@cindex value label
+@deftypefn {Function} VALUELABEL (@var{variable})
+Returns a string matching the label associated with the current value
+of @var{variable}. If the current value of @var{variable} has no
+associated label, then this function returns the empty string.
+@var{variable} may be a numeric or string variable.
+@end deftypefn
+
@node Statistical Distribution Functions
@subsection Statistical Distribution Functions
@item
@code{AND NOT OR}
@end enumerate
-@setfilename ignored