String Functions

Pikt offers a wide variety of built-in functions, both string and numerical.  An unusual feature of Pikt functions is that they are data-typed: their return value is signified by either the "$" (for string) or "#" (for number) prefix.  (Functions never return a preceding or previous value, so no functions are of the type @foo() or %foo().)  (Note: Whitespace between the function name and the opening left parenthesis is illegal.)

Note that many of the functions have synonymous names, in some cases abbreviations, in other cases names by which they are known in other popular programming languages.

In the function descriptions below, "x" signifies any expression that evaluates to either TRUE (non-zero) or FALSE (zero); "a" any string expression; "n" any numerical expression; and "F" a filehandle.

Where inappropriate in any of the following functions (indeed, in any of the number functions above), a non-integer numerical argument will have the function return the string "<<ERR>>" (and this error will be logged).

The string functions (functions that return a character string) include:

$alarm()
$script()
        returns the name of the currently executing alarm script

$alert()
        returns the current alarm's alert name (e.g., "Urgent")

$ampm()
        returns "AM" if the current time falls between
        midnight and twelve noon, else "PM" if between noon
        and midnight
$ampm(n)
        returns "AM" if datevalue n's time falls between
        midnight and twelve noon, else "PM" if between noon
        and midnight

$basename(a)
        for the path a, strips off the directory portion and
        returns the terminating filename

$char(n)
        returns the char associated with the ASCII value n

$checksum(-3,a)
        returns the output of the system cksum command for
        file a
$checksum(-2,a)
        returns the output of the system sum command for
        file a
$checksum(-1,a)
        returns the output of the system 'sum -r' command for
        file a
$checksum( 0,a)
        returns the null checksum (0), also the number of
        bytes, for file a
$checksum( 1,a)
        returns the BSD-style sum computed internally,
        also the number of 512-byte blocks, for file a
$checksum( 2,a)
        returns the SysV-style sum computed internally,
        also the number of 512-byte blocks, for file a
$checksum( 3,a)
        returns the POSIX cksum computed internally,
        also the number of bytes, for file a
$checksum( 4,a)
        returns the MD4 checksum, also the number of bytes,
        for file a
$checksum( 5,a)
        returns the MD5 checksum, also the number of bytes,
        for file a

        note: the checksums assigned to the different levels
        might change, and more levels might be added in the
        future to compute, for example, these additional
        checksums: SNEFRU, HAVAL, SHA

$chop(a,n)
        returns string a with n chars chopped off the end
$chop(a)
        returns string a minus its last char

$command(a)
        executes the command string a, returning its first
        line of output only; if more than one output line is
        needed, uses #popen() and #read() instead

$dayname()
        for the current day, returns the
        day name ("Sunday", "Monday", ...)
$dayname(n)
        for the given day number (1-7), returns the
        day name ("Sunday", "Monday", ...)

$dirname(a)
        for the path a, strips off the terminating filename
        and returns the directory portion

$dquote()
        returns the double quote (") char

$err()
        returns "<<ERR>>"

$filemode(a)
        for path a, returns its mode in octal format

$fixed(n)
$str(n)
$string(n)
$text(n)
        returns #trunc(n) as a string with no decimal places
$fixed(n1,n2)
$str(n1,n2)
$string(n1,n2)
$text(n1,n2)
        returns n1 as as string with n2 decimal places

$grname(a)
$grname(n)
$groupname(a)
$groupname(n)
        for group name a, or gid n, returns its group name
        (as recorded in the system group file)

$grpassword(a)
$grpassword(n)
$grouppassword(a)
$grouppassword(n)
        for group name a, or gid n, returns its group password
        (as recorded in the system group file)

$grmem(a)
$grmem(n)
$groupmem(a)
$groupmem(n)
$grmembers(a)
$grmembers(n)
$groupmembers(a)
$groupmembers(n)
        for group name a, or gid n, returns its group members
        (as recorded in the system group file)

$hostname()
        returns the system hostname

$if(x,a1,a2)
        returns a1, if x is TRUE; else a2, if x is FALSE
$if(x,a)
        returns a, if x is TRUE; else the string "<<NIL>>",
        if x is false

$inlin()
$inline()
$inputline()
        returns the current input line (without the trailing
        line-feed; also available as $inlin, $inline, and
        $inputline)

$left(a,n)
        returns the n left-most chars in a

$level()
        returns the current alarm's level (EMERG, ALERT,
        CRIT, ERR, WARNING, NOTICE, INFO, DEBUG)

$lower(a)
        returns a all in lower-case

$ltrim(a)
        returns a stripped of any leading (leftmost) whitespace

$mid()
$middle()
        [see $substring()]

$monthname()
        for the current month, returns the
        month name ("January", "February", ...)
$monthname(n)
        for the given month number (1-12), returns the
        month name ("January", "February", ...)

$newline()
        returns the newline ('\n') char

$nil()
        returns "<<NIL>>"

$passwdname()
        [see $pwname()]

$passwdpassword()
        [see $pwpassword()]

$passwdgecos()
$passwdcomment()
        [see $pwgecos()]

$passwddir()
        [see $pwdir()]

$passwdshell()
        [see $pwshell()]

$proper(a)
        returns a with every word capitalized

$pwname(a)
$pwname(n)
$passwdname(a)
$passwdname(n)
        for user name a, or uid n, returns its user name
        (as recorded in the system passwd file)

$pwpassword(a)
$pwpassword(n)
$passwdpassword(a)
$passwdpassword(n)
        for user name a, or uid n, returns its password
        (as recorded in the system passwd file)

$pwgecos(a)
$pwgecos(n)
$passwdgecos(a)
$passwdgecos(n)
$pwcomment(a)
$pwcomment(n)
$passwdcomment(a)
$passwdcomment(n)
        for user name a, or uid n, returns its gecos/comment
        (as recorded in the system passwd file)

$pwdir(a)
$pwdir(n)
$passwddir(a)
$passwddir(n)
        for user name a, or uid n, returns its home directory
        (as recorded in the system passwd file)

$pwshell(a)
$pwshell(n)
$passwdshell(a)
$passwdshell(n)
        for user name a, or uid n, returns its login shell
        (as recorded in the system passwd file)

$repeat(a,n)
        returns a repeated n times

$replace(a1,a2,n1,n2)
        in the string a1, replace the chars from index position
        n1 through n2 with the string a2

$reverse(a)
        returns string a with its chars reversed

$right(a,n)
        returns the n right-most chars in a

$rtrim(a)
        returns a stripped of any trailing (rightmost) whitespace

$script()
        [see $alarm()]

$space()
        returns the space (' ') char

$squote()
        returns the single quote (') char

$str()
$string()
        [see $fixed()]

$substitute(a1,a2,a3,n)
        in the string a1, replace the string a2 with the string
        a3, beginning at index position n
$substitute(a1,a2,a3)
        in the string a1, replace every instance of the string a2
        with the string a3

$substring(a,n1,n2)
$substr(a,n1,n2)
$middle(a,n1,n2)
$mid(a,n1,n2)
        for string a, return n2 chars starting at
        index position n1
$substring(a,n1)
$substr(a,n1)
$middle(a,n1)
$mid(a,n1)
        for string a, return all chars to the end of the string
        starting at index position n1

$tab()
        returns the tab ('\t') char

$task()
        returns the current alarm's task description

$text()
        [see $fixed()]

$trim(a)
        returns a stripped of any leading and/or trailing
        whitespace (spaces or tabs)

$upper(a)
        returns a all in upper-case


prev page 1st page next page
Home | FAQ | News | Intro | Samples | Tutorial | Reference | Software | DevNotes | Licensing | Authors | Pikt-Users | Pikt-Workers | Links | SiteIndex | ContactUs
Page best viewed at 1024x768.   Page last updated 2006-09-10.   This site is PIKT® powered.
PIKT® is a registered trademark of the University of Chicago.   Copyright © 1998-2006 Robert Osterlund.  All rights reserved.
Home FAQ News Intro Samples Tutorial Reference Software
PIKT Logo
PIKT Page Title