ploticus: functions

## FUNCTIONS | Welcome Gallery Handbook |
| 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

Markup created by unroff 1.0, `` `` September 13, 2001.