#set TITLE = "available functions"
#include top

.SH DESCRIPTION
Functions may be used within ploticus scripts to return 
values for assignation to variables.
They may also be used within conditional expressions.

.SH SYNTAX
.LP
Function names always start with a dollar sign ($).
In the following summaries, the function name appears along with a
template for arguments that must be supplied.
.LP
\fBEmbedded spaces are not allowed anywhere within the function call structure.\fR
.LP
Some examples of the syntax used with functions in ploticus scripts:
.LP
\fC#set RESULT = $todaysdate()\fR
.IP
would set the variable RESULT to hold todays date (in the default notation).
.LP
\fCselect:  $inrange(@@3,Y) = 1\fR
.IP
(a select condition) would select data rows where field 3 is within the defined
range of Y.


.LP
.SH DETERIMINING IF DATA IS IN RANGE FOR PLOTTING
.LP
\fB$inrange(\fIvalue,axis\fB)\fR  (or \fB$inrange(\fIvalue,axis,loval,hival\fR)\fR
.IP
This is useful in rejecting data that are completely out of the plotting area.
Returns 1 if \fIvalue\fR is in plottable range for the given \fIaxis\fR.
If not, 0 is returned.
The full range of the axis (as defined in proc areadef) is assumed,
unless \fIloval\fR and \fIhival\fR are given.
.br
Example: (see above).


.LP
.SH LOOPING THROUGH A SET OF CATEGORIES OR ROW STUBS
.LP
\fB$nextstub(\fImaxlen\fB)\fR
.IP
Returns the text of a defined category or pltab row stub.
Usually called multiple times within a #loop; 
the result is used to build an expression to 
select data rows.
The first time it is
called, the first category or row stub text will be returned; second
time, the second category or row stub text will be returned, and so on.
The length will be limited to \fImaxlen\fR.
Any embedded spaces will be converted to underscores.
.IP
Example: \fC#set S = $nextstub(5)\fR
.IP
A gallery example where this is used is
.ig >>
<a href="../tabgallery/caselist.html">
.>>
caselist
.ig >>
</a>
.>>


.LP
.SH ACCESSING A FIELD FROM THE CURRENT DATA SET
.LP
\fB$dataitem(row,field)\fR
.IP
Returns the contents of the data item in the requested row and field.
Rows are specified by number and the first row is 1.  
Fields may be specified by number (first=1) or name.
.IP
Example: #set S = $dataitem(1,rate)

.LP
.SH CONVERTING FROM DATA SCALE TO ABSOLUTE UNITS
.LP
\fB$data_to_absolute(axis,value)\fR
.IP
Returns the absolute location of a value in data units (numeric, date, time, etc.).


.SH ARITHMETIC / NUMERIC PROCESSING

.LP
\fB$arith(\fIexp\fB)\fP 
.IP
Arithmetic expression evaluator. Unary plus/minus are allowed.
Evaluation is strictly left to right; no parens may be used.
Does not allow non-numeric operands or malformed arithmetic expressions.
.br
Example: \fC#set RESULT = $arith(2+8/5)\fP  (result: 2)
.br
Example: \fC#set RESULT = $arith(2+-8)\fP  (result: -6)

.LP
\fB$arithl(\fIexp\fB)\fP
.IP
Same as \fB$arith()\fP except 
lazy, i.e. non-numeric operands 
are accepted and treated as if they were 0.  

.LP
\fB$max(\fIa,b,c,..)\fR
.IP
Find the greatest value amongst the supplied arguments
and return it.  Any number of arguments (1 or more) may
be used.  (This function added in version 1.35)
Non-numeric or zero length arguments will be skipped.
.br
Example: \fC#set MAX = $max(24,9,33)\fR  (result: 33)

.LP
\fB$isnumber(\fIs\fB)\fP
.IP
Returns 1 if \fIs\fB is a valid number, 0 if not.
.br
Example: \fC#set RESULT = $isnumber(-0.24)\fR  (result: 1)
.br
Example: \fC#set RESULT = $isnumber(=)\fR  (result: 0)

.LP
\fB$formatfloat(\fIx,fmt\fB)\fR
.IP
format \fIx\fR using 
.ig >>
<a href="attributetypes.html#printfspec">
.>>
printf-style
.ig >>
</a>
.>>
format string \fIfmt\fR.
.br
Example: \fC#set RESULT = $formatfloat(3.4425,%3.2f)\fR (result: 3.44)



.SH STRING PROCESSING

.LP
\fB$exists(value)\fR = test value to see if it is non-missing and
has a length greater than 0.
Convenient to see if a variable has a value, without worrying about embedded
spaces or whether missing data codes are present or hidden.
$exists() and $notexists() are different
from all other functions in that the argument may contain embedded
white space, and in their syntax (see example).
They may only be used in #if statements, and may not be
logically ANDed or ORed with other expressions.
.br
Example: \fC#if $exists(@USERVAR)\fR

.LP
\fB$notexists(value)\fR = opposite of $exists() (see above).


.LP
\fB$change(\fIs,t,string\fB)\fR
.IP
change every occurance of character \fIs\fP to \fIt\fP 
in \fIstring\fP.  The special symbol \fCspace\fR may be used
for t to get spaces (necessary since spaces not allowed in
function call constructs).
.br
Example: \fC#set RESULT = $change(_,~,Hello_world)\fP (result: \fCHello~world\fP)

.LP
\fB$char(\fIn,string\fB)\fP
.IP
get the \fIn\fPth character of \fIstring\fP (first is 1).
.br
Example: \fC#set RESULT = $char(3,ABCDEFG)\fP (result: C)


.LP
\fB$lowerc(\fIstring\fB)\fP
.IP
lower-case equivalent of \fIstring\fP.
.br
Example: \fC#set RESULT = $lowerc(HELLO)\fP (result: \fChello\fP)

.LP
\fB$padr(\fIlen,string\fB)\fP
.IP
pad the right end of \fIstring\fP to a length of \fIlen\fP
with underscores (which are displayed as blanks).
.br
Example: \fC#set RESULT = $padr(10,hello)\fP (result: \fChello_____\fP)

.LP
\fB$strcat(\fIs,t\fB)\fP
.IP
concatenate strings \fIs\fP and \fIt\fP
.br
Example: \fC#set RESULT = $strcat(ABC,XY)\fP  (result: \fCABCXY\fP)

.LP
\fB$strlen(\fIs\fB)\fP
.IP
get length of string \fIs\fP.  Zero length strings are permissible.
.br
Example: \fC#set RESULT = $strlen(hello)\fP (result: 5)

.LP
\fB$substring(\fIs,from,nchar\fB)\fP
.IP
get a substring of \fIs\fP
.br
Example: \fC#set RESULT = $substring(abcde,3,99)\fP (result: \fCcde\fP)
.br
Example: \fC#set RESULT = $substring(abcde,-2,99)\fP (result: \fCde\fP)
.br
Example: \fC#set RESULT = $substring(abcde,1,2)\fP (result: \fCab\fP)

.LP
\fB$upperc(\fIstring\fB)\fP
.IP
get the upper-case equivalent of \fIstring\fP
.br
Example: \fC#set RESULT = $upperc(Hello)\fP (result: \fCHELLO\fP)


.LP
.SH LIST PROCESSING
.LP
These functions operate on a string which is in the format
of a comma-delimited list.  This may be used in a limited way
to work with vectors, since there are no arrays in ploticus scripts.

.LP
\fB$count(\fIstr,list\fB)\fP
.IP
count the number of times \fIstr\fP appears in 
\fIlist\fP.  \fIlist\fP is a comma-delimited list.  
.br
Example: \fC#set RESULT = $count(hello,aba,gabba,jabba)\fP (result: 0)
.br
Example: \fC#set RESULT = $count(x,x,y,x,y,y,z,x)\fP (result: 3)

.LP
\fB$nmember(\fIn,list\fB)\fP
.IP
get the \fIn\fPth member of \fIlist\fP.  
\fIlist\fP is a comma-delimited list.
.br
Example: \fC#set RESULT = $nmember(2,a,b,c,d,e)\fP (result: \fCb\fB)


.LP
.SH DATES
.LP
Individual scripts may set the current date format as needed
using $setdatefmt().  The date format is also set when specified
in a proc areadef scaletype attribute.
Unless otherwise specified, these functions expect date arguments
to be in the current date format.

.LP
\fB$formatdate(\fIdate,newformat\fB)\fR
.IP
Return \fIdate\fR, formatted to \fInewformat\fR.
.br
Example: \fC#set RESULT = $formatdate(062698,yyyymmmdd)\fR

.LP
\fB$setdatefmt(\fIformat\fB)\fR
.IP
set the current date format.  Available date notations
are described in
.ig >>
<a href="dates.html">
.>>
dates
.ig >>
</a>
.>>
.br
Example: \fC#set STATUS = $setdatefmt(yyyymmdd)\fR


.LP
\fB$defaultdatefmt()\fR
.IP
reset the current date format to the project default.
.br
Example: \fC#set STATUS = $defaultdatefmt()\fR

.LP
\fB$todaysdate()\fR
.IP
return the current date.  It will be in the 
date format currently in effect.
.br
Example: \fC#set RESULT = $todaysdate()\fR

.LP
\fB$daysdiff(\fIdate1,date2\fB)\fR
.IP
return the difference in days between
\fIdate1\fR and \fIdate2\fR.
.br
Example: \fC#set RESULT = $daysdiff(011298,010198)\fR (result: 11)

.LP
\fB$dateinrange(\fItestdate,earlydate,latedate\fR)\fR
.IP
return 1 if
testdate is within interval (exclusive) defined by
\fIearlydate\fR and \fIlatedate\fR.  Otherwise 0 is returned.
.br
Example: \fC#set RESULT = $dateinrange(011298,010198,063098)\fR (result: 11)

.LP
\fB$daysdiff_m(\fIdate1,fmt1,date2,fmt2\fB)\fR
.IP
same as daysdiff() but the two
dates may be in any supported format.
.br
Example: \fC#set RESULT = $daysdiff_m(011298,mmddyy,1998jan01,yyyymmmdd)\fR (result: 11)

.LP
\fB$dateadd(\fIdate,ndays\fR)\fR
.IP
return a date resulting when 
\fIndays\fR are added to \fIdate\fR.  
.br
Example: \fC#set RESULT = $dateadd(010198,11)\fR (result: 011298)

.LP
\fB$weekday(\fIdate\fR)\fR
.IP
return the day of the week (a three-character abbreviation)
corresponding to \fBdate\fR.
.br
Example: \fC#set RESULT = $weekday(022098)\fR (result: Fri)

.LP
\fB$yearsold(\fIbirthdate,testdate\fB)
.IP
return the integer age in years as of 
\fItestdate\fR of a person born on \fIbirthdate\fR.
(This can be used for objects other than people of course.)
.br
Example: \fC#set RESULT = $yearsold(062661,022098)\fR (result: 36)

.ig >>
<a name=setdateparms></a>
.>>
.LP
\fB$setdateparms(\fIparmname,value\fB)\fR
.IP
set a date-related profile parameter.
May be used to set either the pivot year, or to allow lazy dates.
.br
A pivot year is used to accomodate two-digit year values.
.br
A lazy date has 00 as the day and/or month portion and is usually
used in situations where the day and/or month is unknown or unavailable.
.br
Example of setting the pivot year: \fC#set STATUS = $setdateparms(Pivotyear,90)\fR
.br
Example of allowing lazy days: \fC#set STATUS = $setdateparms(Lazydates,days)\fR
.br
Example of allowing lazy days and months: \fC#set STATUS = $setdateparms(Lazydates,both)\fR


.LP
.SH TIMES

.LP
\fB$time()\fP
.IP
get current time in hh:mm:ss format.
.br
Example: \fC#set RESULT = $time()\fP

.LP
\fB$timesec()\fP
.IP
get number of seconds since midnight for the current time.
.br
Example: \fC#set RESULT = $timesec()\fP

.LP
\fB$minutesdiff(\fItime1,time2\fB)\fR
.IP
return number of minutes between two hh:mm 
times from the same day.  Times may include :ss (seconds) but these are truncated
before the arithmetic is done.
.br
Example: \fC#set RESULT = $minutesdiff(15:20,14:55)\fR (result: 25)


.LP
.SH MISCELLANEOUS 


.LP
\fB$system(\fIcommand\fB)\fP
.IP
execute the given shell \fIcommand\fP.  
Any spaces within the \fIcommand\fR should be represented as single quotes (').
Result is the first line of standard output produced by the command, 
without trailing newline, and with any spaces converted to underscores.  
.br
Example: \fC#set RESULT = $system(myprog'488)\fP


.LP
\fB$validate(\fIval,datatype\fB)\fR
.IP
return 1 if \fIval\fR conforms to the 
given datatype, 0 if not.  Single quotes (') must be used to represent spaces
in \fIdatatype\fR.  Datatypes include: \fCdate\fR.
.br
Example: \fC#if $validate(@INDATE,date) == 1\fP 


.SH LIMITATIONS AND BUGS
.LP
Function calls cannot contain embedded white space.
.LP
Function calls may not be nested.

#include bottom
