|
Manual page for FUNCTIONS(PL)
Categories of available functions:
plotting
arithmetic
strings
commalists
shell
sql
dates
times
HOW TO USE FUNCTIONS
A number of functions are available for use in
scripts
, for a wide range of purposes including processing of arithmetic, strings
dates, times,
, and so on.
Functions usually take one or more arguments and return a value.
Functions may be used with
#set
,
#call
, or as operands in
#if/#elseif
conditional expressions
.
Custom functions may be coded and added to the file custom.c,
and accessed like any of the built in functions, except that the
names of custom functions should begin with a
double dollar sign ($$) when invoked from scripts.
FUNCTION SYNTAX
Function names always start with a dollar sign ($).
Function arguments are enclosed by parentheses and if more than one
argument, separated by commas (,). For example:
$formatfloat( @NUM, "%7.2f" )
Function calls may not be nested, ie. function arguments may not be functions.
In the following summaries, the function name appears along with a
template for arguments that must be supplied.
PLOTTING
Note: the functions in this section may be used with a double dollar sign ($$)
for faster function name search.
$inrange( value, axis ) or
$inrange( value, axis, min, max )
Return 1 if value within a range on the given axis.
min and max are optional; if given they determine the range.
If they are not given the range is the range of the axis within the
plotting area.
$icolor( i )
Return one of 20 preselected colors. The color sequence was
selected to give good contrast between nearby entries.
i allowable range is 1 to 20; values out of this range
are modulo into range.
Example: #set COLOR = $icolor( 2 )
$fieldname( n )
Return the field name assigned to field n. First is 1.
If no field name was defined, noname is returned.
$dataitem( row, field )
Return the contents of the item in row and field of
the current data set. row is a number, first is 1.
field is either a number or an assigned name.
$data_to_absolute( axis, val )
Given a data location va in either X or Y space (specified by
axis), return the absolute location.
$nextstub( maxlen )
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 maxlen. Any embedded spaces will be converted to underscores.
Example: #set S = $nextstub(5)
A gallery example where this is used is
caselist
$sleep( n )
Delay for n seconds.
Occasionally useful when viewing plots interactively.
$getclick()
Produce a "More.." button and wait for user to click on it.
Upon the click, return.
Occasionally useful when viewing plots interactively.
ARITHMETIC AND NUMBERS
$arith(exp)
Simplistic arithmetic expression evaluator.
exp is an expression made up of numbers and the arithmetic operators
+ - * /.
No embedded spaces nor parentheses are allowed within the expression.
Evaluation is strictly left to right.
Unary plus/minus are allowed.
Example: #set RESULT = $arith(2+8/5) (result: 2)
Example: #set RESULT = $arith(2+-8) (result: -6)
$arithl(exp)
Same as $arith() except
lazy, i.e. non-numeric operands
are accepted and treated as if they were 0.
$isnumber(s)
Returns 1 if s is a valid number, 0 if not.
Example: #set RESULT = $isnumber(-0.24) (result: 1)
Example: #set RESULT = $isnumber(=) (result: 0)
$formatfloat(x,fmt)
Format x using printf-style format string fmt.
May also be used to format integers by using a fmt such as %03.0f.
Example: #set RESULT = $formatfloat( 3.4425, "%3.2f" ) (result: 3.44)
$inr(n,lo,hi)
See if n is within the numeric range of lo
to hi. Returns 1 if so, 0 if not. Non-numeric n always returns 0.
$autoround(val,d)
Round val to a reasonable precision.
Use a value of 0 for d for normal behavior. Increase d to
get more precision, reduce d to get less precision.
Example: #set X = $autoround( @X, 0 )
$math(what,val)
Mathematical functions on val.
what returns
---- -------
abs absolute value (integer or floating point)
Example: #set X = $math(abs,@X)
$random()
Returns a random number between 0.0 and 1.0.
STRINGS
$len(s)
Return the length of s.
$change(s1,s2,string)
Change all occurances of s1 to s2 in string.
Example: #set T = $change( "<", "<sup>", @T )
$substring(s,n,len)
Return a substring of s. Substring begins at character n (first is 1)
for a maximum length of len.
Example: $substring( "abcde", 3, 99 ) would give cde
$changechars(clist,s,newchar)
If string s contains any of chars in clist, change that
character to newchar.
clist may be passed as the word comma to represent a comma (,).
Example: #set RESULT = $changechars("*'", @S, "_" )
$deletechars(clist,s)
If string s contains any of chars in clist, delete that character.
Example: #set RESULT = $deletechars("*'",@S)
$contains(clist,s)
If string s contains any of chars in clist, return position
(first=1) of the first occurance. Return 0 if none found.
clist may be passed as the word comma to represent a comma (,).
Example: #set RESULT = $contains( "*'", @S )
Example: #set RESULT = $contains( ",", @S )
$fuzzymatch(s1,s2,degree)
Perform an approximate match of s1 against s2.
A wildcard character '*' at the beginning or end of s2 indicates
that a match can occur anywhere within s1 (eg. smith* would match
smithington and *smith would match harrowsmith; *smith* would match
both). If there are no asterisks, lengths of the two strings must be similar.
degree changes the 'looseness' of the match.
5 = strict, 4 = medium-strict, 3 = medium 2= loose, 1 = very loose.
Returns 1 on a match, 0 not.
Example: #set STAT = $fuzzymatch(hello,hillo,3) (result: 1)
Example: #set STAT = $fuzzymatch(hello,hillo,5) (result: 0)
$lowerc(string)
Return the lower-case equivalent of string.
Example: #set RESULT = $lowerc(HELLO) (result: hello)
$upperc(string)
Return the upper-case equivalent of string
Example: #set RESULT = $upperc(Hello) (result: HELLO)
$strcat(s,t)
Return the concatenatation of strings s and t
Example: #set RESULT = $strcat(ABC,XY) (result: ABCXY)
$ntoken( n, s )
return the nth whitespace-delimited token in s.
$extractnum( s )
extract the first numeric entity embedded anywhere in s and return it.
COMMALISTS
These functions operate on a string which is in the form of a
commalist
.
$count(str,list)
Count the number of times str appears in
list. If str is passed as * then this function
will count the number of members in the list.
Example: #set RESULT = $count( "hello,aba,gabba,jabba" ) (result: 0)
Example: #set RESULT = $count( "x", "x,y,x,y,y,z,x" ) (result: 3)
$addmember(newmem,list)
Append a new member newmem to end of list.
If list is empty before call, result will have one member.
Example: #set RESULT = $addmember( "red", @MYLIST )
$nmember(n,list)
Get the nth member of list.
Example: #set RESULT = $nmember( 2, "a,b,c,d,e" ) (result: b)
$commonmembers( list1, list2, mode )
Detect if list1 and list2 have any members in common.
Returns 0 if no members in common.
If mode is "count", then the number in common is returned.
Otherwise, when a match is found 1 is returned immediately.
Example: #set MATCH = $commonmembers( "a,b,c,d,e", "c,d,ee", "count" ) (result: 2)
$makelist( s )
Convert s, a list of items separated by commas and/or whitespace,
and return a commalist.
Useful for building commalists from user input.
Example: #set LIST = $makelist( "1101 1102 1103" ) (result: 1101,1102,1103)
Example: #set LIST = $makelist( "1101, 1102, 1103" ) (result: 1101,1102,1103)
SHELL COMMAND INTERFACE
Functions related to the shell interface are described on the
#shell manual page
.
SQL DATABASE INTERFACE
Functions related to SQL interface are described on the
#sql manual page
.
DATES
These functions work with
dates in various notations
. Some date-related parameters may be set in the
project config file
The default date format is mmddyy.
Unless otherwise specified, these functions expect date arguments
to be in the "current date format".
$setdatefmt(format)
Set the current date format.
Example: #call $setdatefmt( "yyyymmdd" )
$formatdate(date,newformat)
Return date, formatted to newformat.
Use to convert dates to different notations, to extract year, month, day
components, or to get weekday equivalent.
Available formats are described
here
Example: #set RESULT = $formatdate( @D, "yyyymmmdd" )
$datevalid(date)
Return 1 if date is a valid one in the current date format;
return 0 if it is not.
Example: #if $datevalid(@apptdate) != 1
$todaysdate()
Return the current date. It will be in the date format currently in effect.
Example: #set RESULT = $todaysdate()
$daysdiff(date1,date2)
Return the difference in days between date1 and date2.
Example: #set RESULT = $daysdiff( 011298, 010198 ) (result: 11)
$julian(date)
Return the julian (number of days since Jan 1, 1977) equivalent of date.
date should be a date in current format, or the special symbol today.
$jultodate(jul)
Return the date (in current format) that is equivalent to julian value jul.
$dateadd(date,ndays)
Return the date resulting when ndays are added to date.
Example: #set RESULT = $dateadd( 010198, 11 ) (result: 011298)
$dategroup( interval, mode, input )
Take date, datetime, or time input value, and adjust it for
grouping purposes. For example, after a set of dates
are processed using $dategroup( week, mid, .. ), the result can be tabulated to
get a weekly distribution.
Allowable interval values are week month quarter year day hour.
Allowable mode values are mid and first.
First character is sufficient for these two args.
$yearsold(birthdate,testdate)
Return the integer age in years as of
testdate of a person born on birthdate.
Example: #set RESULT = $yearsold( 062661, 022098 ) (result: 36)
$setdateparms(parmname,value)
Set a date parameter. See
config file documentation
for descriptions of these parameters, including
strictness of date format checking,
the century pivot year, and lazy dates.
A pivot year is used to accomodate two-digit year values.
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.
Strictness of date format checking: by default the length of a presented date must be
consistent with the format specification. For example, an mm/dd/yy date must be
8 or 10 characters long; other lengths result in an error.
This strictness may be relaxed by doing: #set STATUS = $setdateparms(Strictdatelengths,no)
Example of setting the pivot year: #set STATUS = $setdateparms(Pivotyear,90)
Example of allowing lazy days: #set STATUS = $setdateparms(Lazydates,days)
Example of allowing lazy days and months: #set STATUS = $setdateparms(Lazydates,both)
TIMES
These functions work with
time values
in various notations.
$settimefmt(fmt)
Set the current time notation to fmt.
Available notations are HH:MM:SS, HH:MM, and MM:SS.
(A leading HH can handle single digit hour values; a leading MM
can handle single digit minute values).
Example: #set RESULT = $settimefmt(MM:SS)
These functions work with time values.
$time()
Return the current time in hh:mm:ss format.
Example: #set RESULT = $time()
$timevalid(time)
Return 1 if time is valid in the current time format;
return 0 if it is not.
Example: #if $timevalid(@appttime) != 1
$formattime(time,newformat)
Take time, which is in the current time format,
and reformat it using newformat.
Example: #set t2 = $formattime( "14:22", "hh:mma" )
$timesec()
Get number of seconds since midnight for the current time.
Example: #set RESULT = $timesec()
$tomin(t)
Take t (a value in the current time notation) and return the equivalent,
expressed in # of minutes since 0:00:00. Result is float,
with any seconds expressed as the decimal portion of a minute.
Example: #set RESULT = $tomin( "3:45" )
$frommin(m)
Inverse of $tomin(), where m is a float minutes value.
Result is equivalent time in current notation.
Example: #set RESULT = $frommin( 3.75 )
$timediff(t1,t2)
Find the difference between two times
t1 and t2 (both in current notation). Result is expressed
in float minutes (any seconds expressed as fraction of a minute)
Example: #set RESULT = $timediff( "3:43", "2:28" )
CHECKSUMS
Checksum routines use an odd-even algorithm that takes an integer and
computes a checksum digit 0 - 9 or x. This checksum digit may be
used to guard against key errors and transposed digits.
$checksumvalid(s)
Returns 1 if s is a valid
number with checksum. 0 if not.
Example: #if $checksumgood(39) = 1 (result: true)
$checksumencode(i)
Result is integer i with
a checksum digit appended.
Example: #set CHECKNUM = $checksumencode(29) (result: 294)
$checksumnext(s)
Take s which is a number
including trailing checksum digit, and increment the number and
recompute new checksum digit. Result is returned.
Example: #set RESULT = $checksumnext(39) = 1 (result: 41)
MISCELLANEOUS
$getenv(varname)
Return the contents of environment variable varname.
$uniquename()
Return a short identifier generated
using the current date, time to the current second, and process id.
The name will be unique on a per-host basis.
$tmpfilename(tag)
Generate a unique (on a per-host basis) temporary file name, suitable
for use in shell commands. Uses tmpdir as specified in
project config file
. Format of the name is tmpdir/tag.uniquename where
uniquename is a short name generated using the current date, current time
to the second, and process id. tag may be passed as a zero length string
if desired.
$fileexists( dir, name )
Return 1 if the requested file can be opened, 0 otherwise.
dir indicates the directory that name is relative to
and may be one of /, scriptdir, datadir, tmpdir.
Example: #set A = $fileexists( tmpdir, "mytmp" )
$ref( varname )
Return the contents of varname. May be useful when a variable contains
the name of another variable, to extract the value of the other variable.
Example:
#set A = "hello"
#set B = "A"
#set C = $ref(@B)
C would then contain hello.
$def( varname )
Return 1 if varname has been set to a value.
Return 0 otherwise.
|
 data display engine
Copyright Steve Grubb
|